Three slashes for brief comment

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Three slashes for brief comment

Florian Lindner
Hello,

I use this syntax to make a only a brief description:

  /// true if the mapping along some axis should be ignored
  bool* _deadAxis;

JAVADOC_AUTOBRIEF is off, almost everything else is doxygens default.

It seems to work fine, the result is the same as prefixed with //
@brief foobar.

But I have found it in the documentation nowhere.

There is something like that mentioned in
http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html but it talks
about at least two comment lines.

Is the syntax above ok that way? Or will it eventually cease to work
some day?

Thanks,
Florian



------------------------------------------------------------------------------
Site24x7 APM Insight: Get Deep Visibility into Application Performance
APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
Monitor end-to-end web transactions and take corrective actions now
Troubleshoot faster and improve end-user experience. Signup Now!
http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|

Re: Three slashes for brief comment

Christoph Lipka
Hi Florian,

to quote from the docs:

"For the *brief* description there are also several possibilities:

 1.

    One could use the \brief
    <http://www.stack.nl/%7Edimitri/doxygen/manual/commands.html#cmdbrief>
    command [...]

 2.

    If JAVADOC_AUTOBRIEF
    <http://www.stack.nl/%7Edimitri/doxygen/manual/config.html#cfg_javadoc_autobrief>
    is set to |YES| in the configuration file, then [...]

 3.

    A third option is to use a special *C++ style comment* which does
    not span more than *one line*. Here are two examples:

    /// Brief description.
    /** Detailed description. */

    or

    //! Brief description.

    //! Detailed description
    //! starts here.

    Note the blank line in the last example, which is required to
    separate the brief description from the block containing the
    detailed description. The JAVADOC_AUTOBRIEF
    <http://www.stack.nl/%7Edimitri/doxygen/manual/config.html#cfg_javadoc_autobrief>
    should also be set to |NO| for this case."

(emphasis added).

In other words, you're doing it perfectly right, and the behaviour is
officially supported.


Am 04.02.2016 um 09:31 schrieb Florian Lindner:

> Hello,
>
> I use this syntax to make a only a brief description:
>
>   /// true if the mapping along some axis should be ignored
>   bool* _deadAxis;
>
> JAVADOC_AUTOBRIEF is off, almost everything else is doxygens default.
>
> It seems to work fine, the result is the same as prefixed with //
> @brief foobar.
>
> But I have found it in the documentation nowhere.
>
> There is something like that mentioned in
> http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html but it talks
> about at least two comment lines.
>
> Is the syntax above ok that way? Or will it eventually cease to work
> some day?
>
> Thanks,
> Florian
>
>
>
> ------------------------------------------------------------------------------
> Site24x7 APM Insight: Get Deep Visibility into Application Performance
> APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
> Monitor end-to-end web transactions and take corrective actions now
> Troubleshoot faster and improve end-user experience. Signup Now!
> http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
> _______________________________________________
> Doxygen-users mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>


------------------------------------------------------------------------------
Site24x7 APM Insight: Get Deep Visibility into Application Performance
APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
Monitor end-to-end web transactions and take corrective actions now
Troubleshoot faster and improve end-user experience. Signup Now!
http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|

Re: Three slashes for brief comment

albert
In a number of cases (not sure about which) adding /// \file  on the top of the file helps.

Albert

On Thu, Feb 4, 2016 at 4:03 PM, Christoph Lipka <[hidden email]> wrote:
Hi Florian,

to quote from the docs:

"For the *brief* description there are also several possibilities:

 1.

    One could use the \brief
    <http://www.stack.nl/%7Edimitri/doxygen/manual/commands.html#cmdbrief>
    command [...]

 2.

    If JAVADOC_AUTOBRIEF
    <http://www.stack.nl/%7Edimitri/doxygen/manual/config.html#cfg_javadoc_autobrief>
    is set to |YES| in the configuration file, then [...]

 3.

    A third option is to use a special *C++ style comment* which does
    not span more than *one line*. Here are two examples:

    /// Brief description.
    /** Detailed description. */

    or

    //! Brief description.

    //! Detailed description
    //! starts here.

    Note the blank line in the last example, which is required to
    separate the brief description from the block containing the
    detailed description. The JAVADOC_AUTOBRIEF
    <http://www.stack.nl/%7Edimitri/doxygen/manual/config.html#cfg_javadoc_autobrief>
    should also be set to |NO| for this case."

(emphasis added).

In other words, you're doing it perfectly right, and the behaviour is
officially supported.


Am 04.02.2016 um 09:31 schrieb Florian Lindner:
> Hello,
>
> I use this syntax to make a only a brief description:
>
>   /// true if the mapping along some axis should be ignored
>   bool* _deadAxis;
>
> JAVADOC_AUTOBRIEF is off, almost everything else is doxygens default.
>
> It seems to work fine, the result is the same as prefixed with //
> @brief foobar.
>
> But I have found it in the documentation nowhere.
>
> There is something like that mentioned in
> http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html but it talks
> about at least two comment lines.
>
> Is the syntax above ok that way? Or will it eventually cease to work
> some day?
>
> Thanks,
> Florian
>
>
>
> ------------------------------------------------------------------------------
> Site24x7 APM Insight: Get Deep Visibility into Application Performance
> APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
> Monitor end-to-end web transactions and take corrective actions now
> Troubleshoot faster and improve end-user experience. Signup Now!
> http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
> _______________________________________________
> Doxygen-users mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>


------------------------------------------------------------------------------
Site24x7 APM Insight: Get Deep Visibility into Application Performance
APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
Monitor end-to-end web transactions and take corrective actions now
Troubleshoot faster and improve end-user experience. Signup Now!
http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users


------------------------------------------------------------------------------
Site24x7 APM Insight: Get Deep Visibility into Application Performance
APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
Monitor end-to-end web transactions and take corrective actions now
Troubleshoot faster and improve end-user experience. Signup Now!
http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users