Classes and methods should be documented using Doxygen.
-Use either the // or /* */
-syntax, as long as you are consistent.
Drake uses Doxygen to document its public (and sometimes +private) APIs. All public APIs should have documentation strings (or +docstrings).
+ +See +documentation generation instructions +for how to preview the output locally.
+ +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.
+Drake will provide linting tools that can identify and fix these errors, so
+they should not be discussed in normal code review.
+
+
/** 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's
+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.
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.
+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;
+
+