From: Dmitri Gribenko <gribozavr@gmail.com>
Date: Thu, 6 Mar 2014 16:32:09 +0000 (+0000)
Subject: Expand documentation section on comment parsing
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=ad1d5b1cef9e462fdfadbc782339a61156e7348e;p=clang

Expand documentation section on comment parsing

Patch by Jonathan Sauer, with a little editing by me.


git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@203128 91177308-0d34-0410-b5e6-96231b3b80d8
---

diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst
index ba91501823..53efadd875 100644
--- a/docs/UsersManual.rst
+++ b/docs/UsersManual.rst
@@ -1095,18 +1095,43 @@ below. If multiple flags are present, the last one is used.
   Generate complete debug info.
 
 Comment Parsing Options
---------------------------
+-----------------------
 
 Clang parses Doxygen and non-Doxygen style documentation comments and attaches
 them to the appropriate declaration nodes.  By default, it only parses
 Doxygen-style comments and ignores ordinary comments starting with ``//`` and
 ``/*``.
 
+.. option:: -Wdocumentation
+
+  Emit warnings about use of documentation comments.  This warning group is off
+  by default.
+
+  This includes checking that ``\param`` commands name parameters that actually
+  present in the function signature, checking that ``\returns`` is used only on
+  functions that actually return a value etc.
+
+.. option:: -Wno-documentation-unknown-command
+
+  Don't warn when encountering an unknown Doxygen command.
+
 .. option:: -fparse-all-comments
 
   Parse all comments as documentation comments (including ordinary comments
   starting with ``//`` and ``/*``).
 
+.. option:: -fcomment-block-commands=[commands]
+
+  Define custom documentation commands as block commands.  This allows Clang to
+  construct the correct AST for these custom commands, and silences warnings
+  about unknown commands.  Several commands must be separated by a comma
+  *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines
+  custom commands ``\foo`` and ``\bar``.
+
+  It is also possible to use ``-fcomment-block-commands`` several times; e.g.
+  ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same
+  as above.
+
 .. _c:
 
 C Language Features