RPCS3/llvm-mirror
1
0
Fork 0
mirror of https://github.com/RPCS3/llvm-mirror.git synced 2024-11-25 12:12:47 +01:00
Code Issues Projects Releases Wiki Activity

Document how to comment an actual parameter.

Browse Source 
Differential Revision: https://reviews.llvm.org/D54446

llvm-svn: 346861
This commit is contained in:
Paul Robinson 2018-11-14 13:43:19 +00:00
parent d01d2b7e33
commit 23884518cb
1 changed files with 15 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/CodingStandards.rst
View File

@ -305,6 +305,21 @@ useful to use C style (``/* */``) comments however:
#. 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