doxygen/examples/doxygen-example-issues.cpp

   1 // The struct itself is not documented; other comments within the declaration
   2 // are ignored.
   3
   4 struct t_struct {
   5
   6     // The comment tries to document both members at once, but it only
   7     // applies to the first.  The second produces warnings about missing
   8     // documentation (if the enclosing struct was documented).
   9
  10     //! Angle parameters.
  11     double alpha, beta;
  12 };
  13
  14
  15 // This does not produce any brief documentation.
  16 // An explicit \brief is required, or //! (C++) or /** */ (C) should be used.
  17
  18 /*! Brief comment. */
  19 int gmx_function();
  20
  21
  22 // This does not produce any documentation at all, since a ! is missing at
  23 // the beginning.
  24
  25 /* \brief
  26  * Brief description.
  27  *
  28  * More details.
  29  */
  30 int gmx_function();
  31
  32
  33 // This puts the whole paragraph into the brief description.
  34 // A short description is preferable, separated by an empty line from the rest
  35 // of the text.
  36
  37 /*! \brief
  38  * Brief description. The description continues with all kinds of details about
  39  * what the function does and how it should be called.
  40  */
  41 int gmx_function();
  42
  43
  44 // This may be a Doxygen bug, but this does not produce any brief description.
  45
  46 /** \internal Brief description. */
  47 int gmx_function();
  48
  49
  50 // If the first declaration below appears in a header, and the second in a
  51 // source file, then Doxygen does not associate them correctly and complains
  52 // about missing documentation for the latter.  The solution is to explicitly
  53 // add a namespace prefix also in the source file, even though the compiler
  54 // does not require it.
  55
  56 // Header file
  57 //! Example function with a namespace-qualified parameter type.
  58 int gmx_function(const gmx::SomeClass &param);
  59
  60 // Source file
  61 using gmx::SomeClass;
  62
  63 int gmx_function(const SomeClass &param);
  64
  65
  66 // This puts the namespace into the mentioned module, instead of the contents
  67 // of the namespace.  \addtogroup should go within the innermost scope.
  68
  69 //! \addtogroup module_example
  70 //! \{
  71
  72 namespace gmx
  73 {
  74
  75 //! Function intended to be part of module_example.
  76 int gmx_function();
  77
  78 }