Dot at the end of a doxygen comment
1vanK opened this issue · 7 comments
At the moment we have a rule to put dot at the end of a doxygen comment:
/// Blah blah blah.
and do not put dot at the end of a regular comment:
// Blah blah blah
Doxygen automatically adds dots in some pages (example) and automatically removes dots in other places (example).
Is there any reason to use a different style for regular and Doxygen comments?
No, these are all brief descriptions, because they are one line
/// Brief description.
/// Detailed description without
/// brief description
From config file:
# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a
# multi-line C++ special comment block (i.e. a block of //! or /// comments) as
# a brief description. This used to be the default behavior. The new default is
# to treat a multi-line C++ comment block as a detailed description. Set this
# tag to YES if you prefer the old behavior instead.
#
# Note that setting this tag to YES also means that rational rose comments are
# not recognized any more.
# The default value is: NO.
MULTILINE_CPP_IS_BRIEF = NO
The dot is used to mark the end of the brief description only if JAVADOC_AUTOBRIEF option is enabled
# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the
# first line (until the first dot) of a Javadoc-style comment as the brief
# description. If set to NO, the Javadoc-style will behave just like regular Qt-
# style comments (thus requiring an explicit @brief command for a brief
# description.)
# The default value is: NO.
JAVADOC_AUTOBRIEF = NO
and works only for multiline comments
/// Brief description. Detailed
/// description
/// Brief description. Brief description.
For experiments:
doxygen.exe -g Doxyfile.in
generates template config file with all options- Small doxygen test project: DoxyTest.zip
Actually we have such a problem:
/// Set the Interpolation Mode.
/// @property
void SetInterpolationMode(InterpolationMode interpolationMode);
interpreted as a detailed description without brief description.
So I think MULTILINE_CPP_IS_BRIEF should be enabled
https://rurho3d.github.io/doxygen/class_urho3_d_1_1_spline_path.html
Maybe I had run into something with it with a different project, then. Or perhaps I was completely mistaken and was remembering seeing something like the problem of it lacking the brief description for some members before. I'm not sure. I'm glad you were able to fix that one issue at least.
In terms of this issue, I think I favor no period at the end on the doxygen comments if we want to change the current behavior, as many aren't really sentences ("Destructor.") and that saves a (small) number of bytes per file (unless there are multiple sentences for a single item in the documentation, I think).