docs/doxygen/examples/doxygen-example.cpp

   1 /*! \libinternal \file
   2  * \brief
   3  * Declares gmx::MyClass.
   4  *
   5  * More details.  The documentation is still extracted for the class even if
   6  * this whole comment block is missing.
   7  *
   8  * \author Example Author <example@author.com>
   9  * \inlibraryapi
  10  * \ingroup module_mymodule
  11  */
  12
  13 namespace gmx
  14 {
  15
  16 /*! \libinternal
  17  * \brief
  18  * Brief description for the class.
  19  *
  20  * More details.  The \\libinternal tag is required for classes, since they are
  21  * extracted into the documentation even in the absence of documentation for
  22  * the enclosing scope.
  23  * The \\libinternal tag is on a separate line because of a bug in Doxygen
  24  * 1.8.5 (only affects \\internal, but for clarity it is also worked around
  25  * here).
  26  *
  27  * \inlibraryapi
  28  * \ingroup module_mymodule
  29  */
  30 class MyClass
  31 {
  32     public:
  33         // Trivial constructors or destructors do not require documentation.
  34         // But if a constructor takes parameters, it should be documented like
  35         // methods below.
  36         MyClass();
  37         ~MyClass();
  38
  39         /*! \brief
  40          * Brief description for the method.
  41          *
  42          * \param[in] param1  Description of the first parameter.
  43          * \param[in] param2  Description of the second parameter.
  44          * \returns   Description of the return value.
  45          * \throws    std::bad_alloc if out of memory.
  46          *
  47          * More details describing the method.  It is not an error to put this
  48          * above the parameter block, but most existing code has it here.
  49          */
  50         int myMethod(int param1, const char *param2) const;
  51
  52         //! Brief description for the accessor.
  53         int simpleAccessor() const { return var_; }
  54         /*! \brief
  55          * Alternative, more verbose way of specifying a brief description.
  56          */
  57         int anotherAccessor() const;
  58         /*! \brief
  59          * Brief description for another accessor that is so long that it does
  60          * not conveniently fit on a single line cannot be specified with //!.
  61          */
  62         int secondAccessor() const;
  63
  64     private:
  65         // Private members (whether methods or variables) are currently ignored
  66         // by Doxygen, so they don't need to be documented.  Documentation
  67         // doesn't hurt, though.
  68         int var_;
  69 };
  70
  71 } // namespace gmx