Dot at the end of a doxygen comment

[1vanK]

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?

[1vanK]

@weitjong

[SirNate0]

I think this has to do with doxygen treating the first sentence (marked by the period) as a brief description. Here's some discussion where people ran into an issue with it. Here and here are documentation pages discussing it. I haven't checked to see if we actually use these parameters.

[1vanK]

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

[1vanK]

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. 

[1vanK]

For experiments:

1. doxygen.exe -g Doxyfile.in generates template config file with all options
2. Small doxygen test project: DoxyTest.zip

[1vanK]

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

[SirNate0]

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).