cppguide: New Drake-specific rules for comments

[EricCousineau-TRI]

Derived from Jeremy's branch:
RobotLocomotion/drake#13461 (comment)

To preview:
https://rawcdn.githack.com/EricCousineau-TRI/styleguide/feature-cpp-docstring/cppguide.html#Doxygen
https://htmlpreview.github.io/?https://github.com/EricCousineau-TRI/styleguide/blob/feature-cpp-docstring/cppguide.html
(rawgit is down, and htmlpreview sometimes doesn't preview the ToC :/)

Example automatic linting tool in this PR:
RobotLocomotion/drake#13461

Example of this tool applied to all of Drake:
RobotLocomotion/drake#13491

---

This change is 

[EricCousineau-TRI]

+@jwnimmer-tri and +@ggould-tri for initial review, please!

(\cc @SeanCurtis-TRI if you want to chime in)

Reviewable status: all discussions resolved, LGTM missing from assignee jwnimmer-tri, LGTM missing from assignee ggould-tri, platform LGTM missing (waiting on @ggould-tri and @jwnimmer-tri)

[EricCousineau-TRI]

Reviewable status: 1 unresolved discussion, LGTM missing from assignee ggould-tri, LGTM missing from assignee jwnimmer-tri, platform LGTM missing (waiting on @ggould-tri and @jwnimmer-tri)

a discussion (no related file):
Requires commit curation.

---

[sherm1]

Reviewed 1 of 1 files at r2.
Reviewable status: 3 unresolved discussions, LGTM missing from assignee ggould-tri, LGTM missing from assignee jwnimmer-tri, platform LGTM missing (waiting on @EricCousineau-TRI, @ggould-tri, and @jwnimmer-tri)

---

cppguide.html, line 5119 at r2 (raw file):

in places where the comment is not configured to be displayed in Drake's
Doxygen output. Specifically, code within the <code>internal</code> namespace
should not use this syntax.</p>

We should allow Doxygen's end-of-line comments ///< blah for enums and public (struct) members. Those can be handy for saving vertical space and improving readability. For example, check out this beautiful enum in symbolic_expression.h. I think /** should still be preferred if the comments won't fit on one line though.

---

cppguide.html, line 5182 at r2 (raw file):

  /* Air pressure; never negative. */
  double bar_{};

We should allow // end-of-line comments on data members when there isn't much to say, for the same reasons as using ///< for enums.

[jwnimmer-tri]

Example of this tool applied to all of Drake: RobotLocomotion/drake#13491

At first glance, the sample only appears to apply the /// => /** change. This proposal contains more substantial changes than just that one, e.g. "compress first and last line adjacent to the marker" and "use /* */ (not //) for private function specifications", etc.

I don't need the tool to autofix (or even report on) those changes yet, but in order to assess the proposal itself we do need to have one fully-worked example of all of the new rules applied to a few files of varying original style, e.g., one in geometry, one in solvers, one in framework. Then we can review those few files carefully, to make sure we like the outcome of these new rules.

[ggould-tri]

Reviewable status: 8 unresolved discussions, LGTM missing from assignee ggould-tri, LGTM missing from assignee jwnimmer-tri, platform LGTM missing (waiting on @EricCousineau-TRI and @jwnimmer-tri)

a discussion (no related file):
This change makes cppguide.html inconsistent with its siblings in the same directory (notable google-c-style.el) which has the effect of losing emacs (and eclipse) support for styling. I don't know if that is intended.

---

---

cppguide.html, line 5089 at r2 (raw file):

<div class="stylebody">
<p>Drake uses Doxygen to document its public (and sometimes
private) APIs. All public APIs should have documentation strings (or

Is "documentation strings" really right? Strings implies the std::string language constructs, while the text below just talks about documentation comments. Moreover the terms "documentation string" or "docstring" are used nowhere in the text below.

---

cppguide.html, line 5102 at r2 (raw file):

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.

nit: typo "compatctness"

---

cppguide.html, line 5131 at r2 (raw file):

<p>Prefer Doxygen comment blocks that are readable in both a rendered and
un-rendered state. This could mean foregoing the most beautiful LaTeX

nit: "foregoing" means "previous" ; you want "forgoing" meaning "doing without".

---

cppguide.html, line 5159 at r2 (raw file):

<p>Use <code>//</code> style inside the body of a function. The multi-line
<code>/* */</code> style within a function body is tool difficult to tease

nit: Typo "tool" -> "too"

[jwnimmer-tri]

... have one fully-worked example of all of the new rules ...

To be clear, I am not going to begin review of this document until a fully-worked example (or few) are posted.

[ggould-tri]

Reviewable status: 8 unresolved discussions, LGTM missing from assignee ggould-tri, LGTM missing from assignee jwnimmer-tri, platform LGTM missing (waiting on @EricCousineau-TRI and @jwnimmer-tri)

[EricCousineau-TRI]

Here's a minor attempt to reformat private docstrings:
RobotLocomotion/drake@73294d8

It prolly won't ever be automated (unless clang can give us some good tokens, or someone wants to learn cpplints code structure), but the tool could have something like --try-private-docs that people then have to cherry-pick.

[sherm1]

Looks promising! I saw a few that looked like they could be improved:

/*
Gets Python type for a C++ vector that is not registered using
PYBIND11_MAKE_OPAQUE. */

and

/* Decrements reference count. See `py::handle::dec_ref()` for more details.
 */

[EricCousineau-TRI]

Sweet! Yeah, there's some more tuning necessary.
Also, that commit isn't actually aligned to what's spec'd out here, so my statement above was a bold-faced lie :P
Will fix in another week or so...