doxygen/examples/doxygen-example-scoping.cpp

   1 /*! \libinternal \file
   2  * \brief
   3  * ...
   4  *
   5  * The examples below assume that the file is documented like this:
   6  * with an \\libinternal definition at the beginning, with an intent to not
   7  * expose anything from the file in the public API.  Things work similarly for
   8  * the full documentation if you replace \\libinternal with \\internal
   9  * everywhere in the example.
  10  *
  11  * \ingroup module_example
  12  */
  13
  14
  15 /*! \brief
  16  * Brief description for a free function.
  17  *
  18  * A free function is not extracted into the documentation unless the enclosing
  19  * scope (in this case, the file) is.  So a \\libinternal is not necessary.
  20  */
  21 void gmx_function();
  22
  23 // Assume that the module_example group is defined in the public API.
  24
  25 //! \addtogroup module_example
  26 //! \{
  27
  28 //! \cond libapi
  29 /*! \brief
  30  * Brief description for a free function within \\addtogroup.
  31  *
  32  * In this case, the enclosing scope is actually the module_example group,
  33  * which is documented, so the function needs to be explicitly excluded.
  34  * \\libinternal does not work, since it would produce warnings about an
  35  * undocumented function, so the whole declaration is hidden from Doxygen.
  36  */
  37 void gmx_function();
  38 //! \endcond
  39
  40 //! \}
  41
  42 // For modules that are only declared in the library API, \addtogroup
  43 // cannot be used without an enclosing \cond.  Otherwise, it will create
  44 // a dummy module with the identifier as the name...
  45
  46 //! \cond libapi
  47 //! \addtogroup module_libmodule
  48 //! \{
  49
  50 /*! \brief
  51  * Brief description.
  52  *
  53  * No \\libinternal is necessary here because of the enclosing \\cond.
  54  */
  55 void gmx_function();
  56
  57 //! \}
  58 //! \endcond
  59
  60 // An alternative to the above is use this, if the enclosing scope is only
  61 // documented in the library API:
  62
  63 //! \libinternal \addtogroup module_libmodule
  64 //! \{
  65
  66 //! Brief description.
  67 void gmx_function()
  68
  69 //! \}
  70
  71 /*! \libinternal \brief
  72  * Brief description for a struct.
  73  *
  74  * Documented structs and classes from headers are always extracted into the
  75  * documentation, so \\libinternal is necessary to exclude it.
  76  * Currently, undocumented structs/classes do not produce warnings, so \\cond
  77  * is not necessary.
  78  */
  79 struct t_example
  80 {
  81     int  member1; //!< Each non-private member should be documented.
  82     bool member2; //!< Otherwise, Doxygen will produce warnings.
  83 };
  84
  85 // This namespace is documented in the public API.
  86 namespace gmx
  87 {
  88
  89 //! \cond libapi
  90 /*! \brief
  91  * Brief description for a free function within a documented namespace.
  92  *
  93  * In this case, the enclosing scope is the documented namespace,
  94  * so a \\cond is necessary to avoid warnings.
  95  */
  96 void gmx_function();
  97 //! \endcond
  98
  99 /*! \brief
 100  * Class meant for subclassing only within the module, but the subclasses will
 101  * be public.
 102  *
 103  * This base class still provides public methods that are visible through the
 104  * subclasses, so it should appear in the public documentation.
 105  * But it is not marked with \\inpublicapi.
 106  */
 107 class BaseClass
 108 {
 109     public:
 110         /*! \brief
 111          * A public method.
 112          *
 113          * This method also appears in the documentation of each subclass in
 114          * the public and library API docs.
 115          */
 116         void method();
 117
 118     protected:
 119         // The \cond is necessary to exlude this documentation from the public
 120         // API, since the public API does not support subclassing.
 121         //! \cond internal
 122         //! A method that only subclasses inside the module see.
 123         void methodForSubclassToCall();
 124
 125         //! A method that needs to be implemented by subclasses.
 126         virtual void virtualMethodToImplement() = 0;
 127         //! \endcond
 128 };
 129
 130 } // namespace gmx