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 #. When writing a source file that is used by a tool that only accepts C style
comments. 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 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 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 ``#if 0`` and ``#endif``. These nest properly and are better behaved in general