Doxygen: enable autobrief?

We just had some discussion in the IRC channel and wondered whether it would be a good idea to enable one of the doxygen autobrief options for llvm:

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

QT_AUTOBRIEF
If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first line (until the first dot) of a Qt-style comment as the brief description. If set to NO, the Qt-style will behave just like regular Qt-style comments (thus requiring an explicit \brief command for a brief description.)

The default value is: NO.

Seeing that the \brief commands are often missing and visually noisy (IMO) this may improve our documentation and save us some typing in the future.

- Matthias

If they handle our existing explicit-\brief comments correctly I don’t see why not. You might want to add a blurb to http://llvm.org/docs/CodingStandards.html#doxygen-use-in-documentation-comments which currently suggests the explicit-\brief; you probably want to gather a bit more community consensus for updating the coding standard though.

– Sean Silva

Matthias Braun <matze@braunis.de> writes:

We just had some discussion in the IRC channel and wondered whether it
would be a good idea to enable one of the doxygen autobrief options
for llvm:

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

QT_AUTOBRIEF
If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the
first line (until the first dot) of a Qt-style comment as the brief
description. If set to NO, the Qt-style will behave just like regular
Qt-style comments (thus requiring an explicit \brief command for a
brief description.)

The default value is: NO.

Seeing that the \brief commands are often missing and visually noisy
(IMO) this may improve our documentation and save us some typing in
the future.

FWIW, I can't see any downside to enabling this option. Adding \brief is
redundant and hurts readability in the source, and the fact that we're
inconsistent about it means the experience in the doxygen-generated html
is often missing summaries for functions, which is annoying. Setting the
autobrief option improves both of these problems.

+1.

Getting rid of all the distracting \brief comment markers in our header files would be great!
Note that we will also need to update our coding standards to no longer encourage them then.

-- adrian

So far I've heard no objections, I'll wait a few more days and then change the doxygen configuration and the recommendations in the coding standards. I do not plan to remove any of the existing \brief comments though.

- Matthias

I am all for not having to add \brief. The more readable the comments are for someone not using doxygen the better.

Hey,

I probably should have mentioned it in this thread: I enabled autobrief in r237417.

  • Matthias

So, I’d love to not have to write ‘\brief’ but that’s not what this gives us sadly.

The behavior of autobrief is that the brief snippet stops at the first ‘.’ in the text. It doesn’t matter if that ‘.’ is part of code or anything else.

The behavior of the ‘\brief’ command is that the paragraph it marks is the brief comment, and the detailed one starts with the next paragraph.

I want the second behavior, and not the first. Turning on the autobrief setting and encouraging its use will just cause us to have bad brief comments in the doxygen and easy to read source code. =/ I’d actually rather we write the (annoying and ugly) ‘\brief’ command in the comments until the tools for extracting this are fixed to do something more sensible.

  • Matthias

So, I’d love to not have to write ‘\brief’ but that’s not what this gives us sadly.

The behavior of autobrief is that the brief snippet stops at the first ‘.’ in the text. It doesn’t matter if that ‘.’ is part of code or anything else.

Yes, I also find the autobrief setting annoying that it stops at the first dot and not takes the first paragraph. In any way I documented this behaviour in the llvm coding standards.

The behavior of the ‘\brief’ command is that the paragraph it marks is the brief comment, and the detailed one starts with the next paragraph.

I want the second behavior, and not the first. Turning on the autobrief setting and encouraging its use will just cause us to have bad brief comments in the doxygen and easy to read source code. =/ I’d actually rather we write the (annoying and ugly) ‘\brief’ command in the comments until the tools for extracting this are fixed to do something more sensible.

But there is also a problem with the current setting: Several people don’t care or forget to add \brief commands. In fact I’m pretty sure enabling autobrief fixes more places where \brief was accidentally forgotten than we would risk to have bad brief sections because of unintuitive autobrief behaviour. In any both problems can be easily fixed once noticed.

My main motivation to do this change: While I do care a lot about well documented interfaces; I do not care so much about the generated doxygen html pages. I’d dare to say the majority of llvm developers only looks at the headers and not the generated pages. So aiming for less \brief noise in the headers is a good thing.

  • Matthias

- Matthias

So, I'd love to not have to write '\brief' but that's not what this gives us sadly.

The behavior of autobrief is that the brief snippet stops at the first '.' in the text. It doesn't matter if that '.' is part of code or anything else.

Yes, I also find the autobrief setting annoying that it stops at the first dot and not takes the first paragraph. In any way I documented this behaviour in the llvm coding standards.

Huh. I knew this was what autobrief does. I thought `\brief`
had the same behaviour though. (IMO, you should be able to
write a one-sentence high-level description for every function;
if people want details they can look/click through.)

The behavior of the '\brief' command is that the paragraph it marks is the brief comment, and the detailed one starts with the next paragraph.

I want the second behavior, and *not* the first. Turning on the autobrief setting and encouraging its use will just cause us to have bad brief comments in the doxygen and easy to read source code. =/ I'd actually rather we write the (annoying and ugly) '\brief' command in the comments until the tools for extracting this are fixed to do something more sensible.

But there is also a problem with the current setting: Several people don't care or forget to add \brief commands. In fact I'm pretty sure enabling autobrief fixes more places where \brief was accidentally forgotten than we would risk to have bad brief sections because of unintuitive autobrief behaviour. In any both problems can be easily fixed once noticed.

My main motivation to do this change: While I do care a lot about well documented interfaces; I do not care so much about the generated doxygen html pages. I'd dare to say the majority of llvm developers only looks at the headers and not the generated pages. So aiming for less \brief noise in the headers is a good thing.

Personally, I never look at the html, just the headers. But I
know other people that use them. I think it depends on how
comfortable people are with their editors, really, and it's
important to support both workflows.

But the auto-brief behaviour seems right most of the time, and
you can add "\brief" when you really need a multi-sentence
not-so-brief comment. I prefer the new style.

>
>
>
> - Matthias
>
>>
>> So, I'd love to not have to write '\brief' but that's not what this
gives us sadly.
>>
>> The behavior of autobrief is that the brief snippet stops at the first
'.' in the text. It doesn't matter if that '.' is part of code or anything
else.
> Yes, I also find the autobrief setting annoying that it stops at the
first dot and not takes the first paragraph. In any way I documented this
behaviour in the llvm coding standards.

Huh. I knew this was what autobrief does. I thought `\brief`
had the same behaviour though. (IMO, you should be able to
write a one-sentence high-level description for every function;
if people want details they can look/click through.)

>>
>> The behavior of the '\brief' command is that the paragraph it marks is
the brief comment, and the detailed one starts with the next paragraph.
>>
>> I want the second behavior, and *not* the first. Turning on the
autobrief setting and encouraging its use will just cause us to have bad
brief comments in the doxygen and easy to read source code. =/ I'd actually
rather we write the (annoying and ugly) '\brief' command in the comments
until the tools for extracting this are fixed to do something more sensible.
>
> But there is also a problem with the current setting: Several people
don't care or forget to add \brief commands. In fact I'm pretty sure
enabling autobrief fixes more places where \brief was accidentally
forgotten than we would risk to have bad brief sections because of
unintuitive autobrief behaviour. In any both problems can be easily fixed
once noticed.
>
> My main motivation to do this change: While I do care a lot about well
documented interfaces; I do not care so much about the generated doxygen
html pages. I'd dare to say the majority of llvm developers only looks at
the headers and not the generated pages. So aiming for less \brief noise in
the headers is a good thing.
>

Personally, I never look at the html, just the headers. But I
know other people that use them. I think it depends on how
comfortable people are with their editors, really, and it's
important to support both workflows.

Personally I sometimes use the html because I can just google "clang
functiondecl" or "llvm sys::fs" and see it in one click, whereas it's
generally clumsier to find it from an editor (I don't know of any editor
that can easily hone in on just the instance of "FunctionDecl" that is not
a forward declaration, not a use in a cpp file, etc. unless you already
have FunctionDecl handy and can (in an IDE) "Go to definition").

-- Sean Silva

"Duncan P. N. Exon Smith" <dexonsmith@apple.com> writes:

The behavior of the '\brief' command is that the paragraph it marks
is the brief comment, and the detailed one starts with the next
paragraph.

I want the second behavior, and *not* the first. Turning on the
autobrief setting and encouraging its use will just cause us to
have bad brief comments in the doxygen and easy to read source
code. =/ I'd actually rather we write the (annoying and ugly)
'\brief' command in the comments until the tools for extracting
this are fixed to do something more sensible.

But there is also a problem with the current setting: Several people
don't care or forget to add \brief commands. In fact I'm pretty sure
enabling autobrief fixes more places where \brief was accidentally
forgotten than we would risk to have bad brief sections because of
unintuitive autobrief behaviour. In any both problems can be easily
fixed once noticed.

My main motivation to do this change: While I do care a lot about
well documented interfaces; I do not care so much about the
generated doxygen html pages. I'd dare to say the majority of llvm
developers only looks at the headers and not the generated pages. So
aiming for less \brief noise in the headers is a good thing.

Personally, I never look at the html, just the headers. But I
know other people that use them. I think it depends on how
comfortable people are with their editors, really, and it's
important to support both workflows.

But the auto-brief behaviour seems right most of the time, and
you can add "\brief" when you really need a multi-sentence
not-so-brief comment. I prefer the new style.

Agreed. While accepting the first paragraph, assuming that means
everything up to a blank line, is the optimal behaviour, lots of docs
are of the form:

  /// Do the thing with the stuff.
  ///
  /// This does whatever, using \c param1 for something and returning
  /// some sort of result.

Adding a \brief is useless here, and this change means that \brief will
only be needed for things like:

  /// \brief This function does X. It caches some values or something,
  /// and is complicated in some minor way.

It's easy enough to add \brief in this case, and the general case is
that most functions have a somewhat reasonable summary, rather than none
at all.

Basically, we need to use \brief in some cases whether or not we enable
autobrief, and I think we'll need it noticeably less often if autobrief
is on.

My main motivation to do this change: While I do care a lot about well
documented interfaces; I do not care so much about the generated doxygen
html pages. I'd dare to say the majority of llvm developers only looks at
the headers and not the generated pages. So aiming for less \brief noise in
the headers is a good thing.

For what it is worth, I have never looked at the doxygen output of any
project in my life.

Cheers,
Rafael