multi-line \briefs

[Anonymous]

[If this issue has already been resolved, can someone point me to the
resolution? -- Thanks, Scott]

The Doxygen documentation says that a \brief command is intended to span only
one line of text; it says that a \brief command is terminated by a blank line
or another command in the source file.  However, the \brief command also will
include text from multiple lines if neither of these termination features are
encountered.  Unfortunately, it does not parse out comment markers (such as
"//" in C++) when it does this, so these comment markers show up in the
"Brief" section in the documenation.

This isn't really a bug in the code, because the documentation doesn't
explicitly rule out this behavior.  But the behavior in this case is
underspecified by the documentation.  The current behavior isn't very
useful, because you cannot get a "clean" \brief section if for some reason
you want the \brief to span multiple source file lines; but Doxygen doesn't
warn or prevent you from making multi-line \briefs either.

There are a few options:

1.  Leave the doxygen code as it is, and update the documentation to state that
the \brief command will include all text, including the source code comment
markers, from subsequent lines until an explicit termination feature is
encountered.

2.  Change the code to print a warning if a multi-line \brief is encountered.

3.  Change the code to parse out comment markers (e.g. "//" in C++) that
appear at the beginning of a new line of text after a \brief, but before a
termination feature is encountered (i.e. make \brief's scope more like the
other commands that can span multiple lines).

4.  Change the code so that \brief uses the end-of-line as a termination
feature (just as, for example, the C++ compiler uses the end-of-line as the
termination feature for a "//"-style comment).  Subsequent lines do not
appear in the \brief section.

I'm sure there are other and better options than what I've outlined above;
does anyone have some wisdom about what might be the best thing to do in
this case?

I've included a sample C++ .h file below that demonstrates the issue, it
should work with the standard default Doxyfile.

Cheers,

Scott Farrar

Here's a simple .h file that demonstrates the issue when it is processed by
Doxygen:

//      /*!
//        \brief this -brief line extends across
//               multiple source file lines
//        \date Date: 2003/03/07 this -date line extends across
//               multiple source file lines
//        \version Revision: #6 this -version line extends across
//               multiple source file lines
//
//        This is a class to test doxygen's
//        parsing behavior.
//
//        \sa this -sa line extends across
//            multiple source file lines
//        \internal this -internal line extends across
//                  multiple source file lines
//        \author this -author line extends across
//                multiple source file lines
//        \modifiedby this -modifiedby line extends across
//                    multiple source file lines
//      */

class foo
{
public:
      // /*!
      //   \brief this -brief method line extends across
      //          multiple source file lines
      //
      //  This is a method
      //  description that spans two lines.
      //
      //  \param x this -param line extends across
      //           multiple source file lines
      // */
      void abcd(int x);
};