From 647ce96f95552f52085a3d33adc678a907d6efaa Mon Sep 17 00:00:00 2001 From: Jeremy Nimmer Date: Thu, 2 Apr 2020 17:17:16 -0400 Subject: [PATCH 1/2] cppguide: New Drake-specific rules for comments --- cppguide.html | 136 ++++++++++++++++++++++++++++++++++---------------- 1 file changed, 94 insertions(+), 42 deletions(-) diff --git a/cppguide.html b/cppguide.html index e33878f9b..cce37caca 100644 --- a/cppguide.html +++ b/cppguide.html @@ -2223,40 +2223,6 @@

C++ Miscellany

we use to make C++ code more robust, and various ways we use C++ that may differ from what you see elsewhere.

-
-

Doxygen

- -
-

Classes and methods should be documented using Doxygen.

-
- -
-
    -
  • Only use Doxygen special comment blocks (comments declared with /// or - /**) on published APIs (public or protected classes and methods). Code - with private access or declared in .cc files should not use the Doxygen - block format. However, note that markup such as @return may still be used - for non-Doxygen (// or /*) comment blocks when it improves readability of - the source code for developers, even though it will never be processed by - Doxygen.
    • -
  • If you decide to use Doxygen formatting hints, then those must render - correctly. For instructions on how to generate the Drake Doxygen website, - click here. For - additional background information, - see PR - #3584.
    • -
  • Prefer Doxygen comment blocks that are readable in both a rendered and - un-rendered state. This could mean foregoing the most beautiful LaTeX - formatting for some serviceable text equations readable in the code. Or, - you may want to augment beautiful-but-unreadable formatting with a - simplified presentation of the same information to accommodate future - programmers, who are likely to only see the header file. For more - background information, - see PR - #3584.
    • -
-
-

Memory Allocation

@@ -5115,20 +5081,106 @@

Comments

understand your code. Be generous — the next one may be you!

-

Comment Style

+
+

Doxygen Style

-
-

Use either the // or /* */ -syntax, as long as you are consistent.

+
+

Drake uses Doxygen to document its APIs.

+ +

See +documentation generation instructions +for how to preview the output locally.

+ +

Comment Markers

+ +

When writing Doxygen comments, use /** */ style, not +/// nor /*! style. The comment should begin on the +same line as the opening mark, and new lines should align with the opening +slash, should not repeat the asterisk, and should close on the last line of +text. This maximizes the vertical and horizontal compatctness of the code. +

/** Returns an iterator for this table. It is the client's responsibility to
+delete the iterator when it is done with it, and it must not use the iterator
+once the GargantuanTable object on which the iterator was created has been
+deleted. */
+Iterator* GetIterator() const;
+
+

+ +

Only use /** */ syntax for comments that appear in Drake' +Doxygen output. The use of /** */ is a signal to the reader that +the comment is part of Doxygen's output, so it is misleading to use that syntax +in places where the comment is not configured to be displayed in Drake's +Doxygen output. Specifically, code within the internal namespace +should not use this syntax.

+ +

Inline Markup

+ +

Markup such as @return may still be used for non-Doxygen (// +or /*) comment blocks when it improves readability of the source +code for developers, even though the markup is not processed by Doxygen.

+ +

If you decide to use Doxygen formatting hints, then those must render +correctly.

+ +

Prefer Doxygen comment blocks that are readable in both a rendered and +un-rendered state. This could mean foregoing the most beautiful LaTeX +formatting for some serviceable text equations readable in the code. Or, you +may want to augment beautiful-but-unreadable formatting with a simplified +presentation of the same information to accommodate future programmers, who are +likely to only see the header file.

+
+

Comment Style

+
+

Use either the // or /* */ +syntax, as long as you are consistent.

+ +

You can use either the // or +the /* */ syntax; however, // is +much more common.

+ +

Be consistent with how you comment and what style you use where.

-

You can use either the // or the /* -*/ syntax; however, // is -much more common. Be consistent with how you -comment and what style you use where.

+
+

Use /* */ style for API-like comments (file, class, function +declaration, member variable declaration) that are not processed by Doxygen, +e.g., in front of private or internal functions. This minimizes formatting +differences with similar comments that are processed by Doxygen. Use +the same line-wrapping rules as we do for Doxygen style.

+ +

Use // style inside the body of a function. The multi-line +/* */ style within a function body is tool difficult to tease +apart from the surrounding statements.

+ +

Intra-line comments may use /* */ style, e.g., +auto x = Calculate(/* callback */ nullptr);.

+ +

Example: +

/** Holds useful information. This is a really long line that wraps after we
+reach the column limit. */
+class Foo {
+ public:
+  /** Returns an approximation of the current air pressure. */
+  double get_bar() const;
+
+ private:
+  /* Updates member data using sensors. For now, we only update `bar_` but in
+  the future we anticipate additional sensors. */
+  void ReadNewData() {
+    // TODO(#123) Add exponential filter(s) here.
+    bar_ = get_sensor_data(22 /* amb_pressure_adc */);
+  }
 
+  /* Air pressure; never negative. */
+  double bar_{};
+};
+
+/** Degrees of freedom of the new robot. */
+constexpr int kNumDofs = 7;
+
+

File Comments

From 1d928e322d1a496f1cb9ff0053b43ce09d815d05 Mon Sep 17 00:00:00 2001 From: Eric Cousineau Date: Fri, 17 Jul 2020 18:18:24 -0400 Subject: [PATCH 2/2] tmp --- cppguide.html | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/cppguide.html b/cppguide.html index e33878f9b..11df96a35 100644 --- a/cppguide.html +++ b/cppguide.html @@ -5115,6 +5115,10 @@

Comments

understand your code. Be generous — the next one may be you!

+

Be sure to provide public documentation strings (docstrings). +These docstrings should be compatible with the conventions described for +Doxygen.

+

Comment Style

@@ -5131,6 +5135,42 @@

Comment Style

+
+For consistency, Drake provides linting tools to detect and fix any comment +strings that deviate from the following prescribed format for public docstrings +(as described in the Doxygen section): + +
/** Single-line docstring comment. */
+
+/** Multi-line docstring comment.
+Line 2.
+Line 3. */
+
+ +This means that all other formatting variants will be transformed into the above format. Examples that will map to the above examples: +
/// Single-line docstring comment.
+
+/**
+ * Single-line docstring comment.
+ */
+
+/// Multi-line docstring comment.
+/// Line 2.
+/// Line 3.
+
+/**
+ * Multi-line docstring comment.
+ * Line 2.
+ * Line 3.
+ */
+
+/** Multi-line docstring comment
+    Line 2.
+    Line 3.
+*/
+
+
+

File Comments