Document how to comment an actual parameter

[probinson]

Summary

This came up in a code review, but I had nothing to point to.
It seems reasonably common practice.
Happy to put the words somewhere else, if that seems preferable.

[dblaikie]

Sounds good to me - I'd usually put spaces inside the start/end of the comment (& maybe between the comment & the constant) but that's just me - I'm not fussed about which way it's documented (although - best it's documented whatever way clang-format formats it, so as not to be confusing)

[rnk]

+1 for writing it as you have it, it's what clang-format does, and so far as I know it's the prevailing style.

[rupprecht]

LGTM for the actual style change, just a wording nit:

llvm/docs/CodingStandards.rst

308 ↗

(On Diff #173754)

Minor nit: s/To document/When documenting/ to maintain consistency with the previous bullet points

[probinson]

My experiments with clang-format show that it is aware of this convention. It will change /*Prefix*/nullptr to /*Prefix*/ nullptr (inserting a space) and will also change /*Prefix=*/ nullptr to /*Prefix=*/nullptr (removing the space, if the comment ends with =).

llvm/trunk/docs/CodingStandards.rst

 #. When writing C code: Obviously if you are writing C code, use C style
    comments.
 
 #. When writing a header file that may be ``#include``\d by a C source file.
 
 #. When writing a source file that is used by a tool that only accepts C style
    comments.
 
+#. When documenting the significance of constants used as actual parameters in
+   a call. This is most helpful for ``bool`` parameters, or passing ``0`` or
+   ``nullptr``. Typically you add the formal parameter name, which ought to be
+   meaningful. For example, it's not clear what the parameter means in this call:
+
+   .. code-block:: c++
+
+     Object.emitName(nullptr);
+
+   An in-line C-style comment makes the intent obvious:
+
+   .. code-block:: c++
+
+     Object.emitName(/*Prefix=*/nullptr);
+
 Commenting out large blocks of code is discouraged, but if you really have to do
 this (for documentation purposes or as a suggestion for debug printing), use
 ``#if 0`` and ``#endif``. These nest properly and are better behaved in general
 than C style comments.
 
 Doxygen Use in Documentation Comments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^