[PATCH] D54446: Document how to comment an actual parameter

[Paul Robinson via Phabricator via llvm-commits]

probinson created this revision.
probinson added reviewers: chandlerc, rnk, dblaikie.

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.


Repository:
  rL LLVM

https://reviews.llvm.org/D54446

Files:
  llvm/docs/CodingStandards.rst


Index: llvm/docs/CodingStandards.rst
===================================================================
--- llvm/docs/CodingStandards.rst
+++ llvm/docs/CodingStandards.rst
@@ -305,6 +305,21 @@
 #. When writing a source file that is used by a tool that only accepts C style
    comments.
 
+#. To document 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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D54446.173754.patch
Type: text/x-patch
Size: 1034 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20181112/4585fbcd/attachment.bin>