This is an archive of the discontinued LLVM Phabricator instance.

[NFC] Remove doxygen brief tag from BasicBlock.h
ClosedPublic

Authored by mattd on Apr 16 2018, 4:27 PM.

Details

Summary

Documentation is built using the AutoBrief configuration option in docs/doxygen.cfg.in. This change removes the redundant brief tags from BasicBlock.h. I'm happy to write a sed script and remove all \brief tags as a separate commit later.

Diff Detail

Event Timeline

mattd created this revision.Apr 16 2018, 4:27 PM
aprantl accepted this revision.Apr 16 2018, 4:42 PM

thanks!

This revision is now accepted and ready to land.Apr 16 2018, 4:42 PM
aprantl added inline comments.Apr 16 2018, 4:45 PM
BasicBlock.h
138

You might want to reflow the comments afterwards (Esc q / M-x fill-paragraph in emacs).

mattd updated this revision to Diff 142774.Apr 17 2018, 7:45 AM
  • Removed brief doxygen tag.
  • Reflowed the comment text of the paragraph containing the brief tag.
  • Fixed a typo.
This revision was automatically updated to reflect the committed changes.
MatzeB added a subscriber: MatzeB.Apr 18 2018, 1:07 AM

I am pretty sure this is not correct: Autobrief is stupid and stops at the first dot or at the line ending AFAIK. This means when the first sentence stretches over more than 1 line you still need need \brief. So a bunch of the changes here appear invalid to me, please check the doxygen output and revert if necessary.

mattd added a subscriber: aprantl.Apr 18 2018, 1:32 AM

I diffed the two outputs and also pulled up the text in a browser. I do not see any significant changes in browser, and there wasn't. However, I am happy to revert if any noticeable changes are witnessed. I see multiline/paragraph text in the output.

I diffed the two outputs and also pulled up the text in a browser. I do not see any significant changes in browser, and there wasn't. However, I am happy to revert if any noticeable changes are witnessed. I see multiline/paragraph text in the output.

Does that mean the doxygen documentation is just wrong?

https://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_javadoc_autobrief claims:

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

or does doxygen have a different notion of a what “first line” means?

mattd added a comment.Apr 18 2018, 6:58 AM

I diffed the two outputs and also pulled up the text in a browser. I do not see any significant changes in browser, and there wasn't. However, I am happy to revert if any noticeable changes are witnessed. I see multiline/paragraph text in the output.

Does that mean the doxygen documentation is just wrong?

https://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_javadoc_autobrief claims:

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

or does doxygen have a different notion of a what “first line” means?

What I am seeing, is what I was expecting, the first line is up until the first dot, or to the first blank comment line. The definition you reference seems incomplete; Mainly, the end of brief appears to be either either the first . in the comment or the first blank comment line.