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.
11 * \ingroup module_example
16 * Brief description for a free function.
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.
23 // Assume that the module_example group is defined in the public API.
25 //! \addtogroup module_example
30 * Brief description for a free function within \\addtogroup.
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.
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...
47 //! \addtogroup module_libmodule
53 * No \\libinternal is necessary here because of the enclosing \\cond.
60 // An alternative to the above is use this, if the enclosing scope is only
61 // documented in the library API:
63 //! \libinternal \addtogroup module_libmodule
66 //! Brief description.
71 /*! \libinternal \brief
72 * Brief description for a struct.
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
81 int member1; //!< Each non-private member should be documented.
82 bool member2; //!< Otherwise, Doxygen will produce warnings.
85 // This namespace is documented in the public API.
91 * Brief description for a free function within a documented namespace.
93 * In this case, the enclosing scope is the documented namespace,
94 * so a \\cond is necessary to avoid warnings.
100 * Class meant for subclassing only within the module, but the subclasses will
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.
113 * This method also appears in the documentation of each subclass in
114 * the public and library API docs.
119 // The \cond is necessary to exlude this documentation from the public
120 // API, since the public API does not support subclassing.
122 //! A method that only subclasses inside the module see.
123 void methodForSubclassToCall();
125 //! A method that needs to be implemented by subclasses.
126 virtual void virtualMethodToImplement() = 0;