Dot at the end of a doxygen comment about urho3d HOT 7 OPEN

@weitjong

from urho3d.

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.

from urho3d.

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

from urho3d.

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. 

from urho3d.

For experiments:

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

from urho3d.

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

from urho3d.

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

from urho3d.