[LLVMdev] Doxygen: enable autobrief?

[Justin Bogner]

"Duncan P. N. Exon Smith" <dexonsmith at 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.