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

[Paul Robinson via Phabricator via llvm-commits]

This revision was automatically updated to reflect the committed changes.
Closed by commit rL346861: Document how to comment an actual parameter. (authored by probinson, committed by ).

Changed prior to commit:
  https://reviews.llvm.org/D54446?vs=173754&id=174023#toc

Repository:
  rL LLVM

https://reviews.llvm.org/D54446

Files:
  llvm/trunk/docs/CodingStandards.rst


Index: llvm/trunk/docs/CodingStandards.rst
===================================================================
--- llvm/trunk/docs/CodingStandards.rst
+++ llvm/trunk/docs/CodingStandards.rst
@@ -305,6 +305,21 @@
 #. 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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D54446.174023.patch
Type: text/x-patch
Size: 1062 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20181114/ca04d9e6/attachment.bin>