You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Per discussion in issue #2051, this PR enables JAVADOC_AUTOBRIEF in the Drake Doxyfiles for C++ and Matlab.
What this means is that the first sentence of every doxygen comment will automatically be used as though it were preceded by @brief and followed by a blank line. This provides a one-line brief for every class and method that has even a short doxygen comment.
Doxygen considers a sentence to end at the first period -- use \. if you want a period included in the brief or want to have a multi-sentence brief. An explicit @brief will be harmlessly ignored, but those can be removed as code is updated.
Possible source of trouble: explicit @briefs that were previously multi-sentence will be reduced to just their first sentence if no \. is used, although the rest of the brief will still appear in the More... section.
Per discussion in issue #2051, this PR enables JAVADOC_AUTOBRIEF in the Drake Doxyfiles for C++ and Matlab.
What this means is that the first sentence of every doxygen comment will automatically be used as though it were preceded by @brief and followed by a blank line. This provides a one-line brief for every class and method that has even a short doxygen comment.
Doxygen considers a sentence to end at the first period -- use \. if you want a period included in the brief or want to have a multi-sentence brief. An explicit @brief will be harmlessly ignored, but those can be removed as code is updated.
Possible source of trouble: explicit @briefs that were previously multi-sentence will be reduced to just their first sentence if no \. is used, although the rest of the brief will still appear in the More... section.
Quick question in case someone knows and can respond before I actually test this on my local machine: What happens if the first sentence of a comment block spans multiple lines? Will AUTOBRIEF truncate it?
Previously, liangfok (Chien-Liang Fok) wrote…
+@liangfok feature. Sorry I did not see this PR being assigned to me until now. Still review it shortly.
Review status: all files reviewed at latest revision, all discussions resolved, all commit checks successful.
@liangfok: AUTOBRIEF doesn't pay attention to line breaks, it just looks for a period. So multiline briefs work fine, but multi-sentence ones (or sentences with abbreviations like Ph.D.) need to escape the period with a backslash.
Previously, liangfok (Chien-Liang Fok) wrote…
Quick question in case someone knows and can respond before I actually test this on my local machine: What happens if the first sentence of a comment block spans multiple lines? Will AUTOBRIEF truncate it?
Review status: all files reviewed at latest revision, all discussions resolved, some commit checks pending.
@sherm1: Thanks! I actually just verified your statement on my local machine. Thus, this PR .
Previously, sherm1 (Michael Sherman) wrote…
@liangfok: AUTOBRIEF doesn't pay attention to line breaks, it just looks for a period. So multiline briefs work fine, but multi-sentence ones (or sentences with abbreviations like Ph.D.) need to escape the period with a backslash.
Review status: all files reviewed at latest revision, all discussions resolved, some commit checks pending.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
all files reviewed at latest revision, all discussions resolved, all commit checks successful.
Per discussion in issue #2051, this PR enables
JAVADOC_AUTOBRIEFin the Drake Doxyfiles for C++ and Matlab.What this means is that the first sentence of every doxygen comment will automatically be used as though it were preceded by
@briefand followed by a blank line. This provides a one-line brief for every class and method that has even a short doxygen comment.Doxygen considers a sentence to end at the first period -- use
\.if you want a period included in the brief or want to have a multi-sentence brief. An explicit@briefwill be harmlessly ignored, but those can be removed as code is updated.Possible source of trouble: explicit
@briefs that were previously multi-sentence will be reduced to just their first sentence if no\.is used, although the rest of the brief will still appear in theMore...section.Reviews, please:
Feature: @liangfok
Platform: @jwnimmer-tri
This change is
Multiple assignees: 
jwnimmer-tri, 
liangfok