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 /*! \libinternal \brief
  61  * Brief description for a struct.
  62  *
  63  * Documented structs and classes from headers are always extracted into the
  64  * documentation, so \\libinternal is necessary to exclude it.
  65  * Currently, undocumented structs/classes do not produce warnings, so \\cond
  66  * is not necessary.
  67  */
  68 struct t_example
  69 {
  70     int  member1; //!< Each non-private member should be documented.
  71     bool member2; //!< Otherwise, Doxygen will produce warnings.
  72 };
  73
  74 // This namespace is documented in the public API.
  75 namespace gmx
  76 {
  77
  78 //! \cond libapi
  79 /*! \brief
  80  * Brief description for a free function within a documented namespace.
  81  *
  82  * In this case, the enclosing scope is the documented namespace,
  83  * so a \\cond is necessary to avoid warnings.
  84  */
  85 void gmx_function();
  86 //! \endcond
  87
  88 /*! \brief
  89  * Class meant for subclassing only within the module, but the subclasses will
  90  * be public.
  91  *
  92  * This base class still provides public methods that are visible through the
  93  * subclasses, so it should appear in the public documentation.
  94  * But it is not marked with \\inpublicapi.
  95  */
  96 class BaseClass
  97 {
  98     public:
  99         /*! \brief
 100          * A public method.
 101          *
 102          * This method also appears in the documentation of each subclass in
 103          * the public and library API docs.
 104          */
 105         void method();
 106
 107     protected:
 108         // The \cond is necessary to exlude this documentation from the public
 109         // API, since the public API does not support subclassing.
 110         //! \cond internal
 111         //! A method that only subclasses inside the module see.
 112         void methodForSubclassToCall();
 113
 114         //! A method that needs to be implemented by subclasses.
 115         virtual void virtualMethodToImplement() = 0;
 116         //! \endcond
 117 };
 118
 119 } // namespace gmx