diff options
| author | Dmitri Gribenko <gribozavr@gmail.com> | 2012-12-16 17:38:09 +0000 |
|---|---|---|
| committer | Dmitri Gribenko <gribozavr@gmail.com> | 2012-12-16 17:38:09 +0000 |
| commit | 4f35f74017aa581986927bb3602d98a1ce969093 (patch) | |
| tree | f7f86e2d6788fd0f6302d7e5ea0faeff7218605b | |
| parent | b22acbb043a23fe0c862a8b61c01baeac5522a37 (diff) | |
Clang ReleaseNotes: add information about documentation comments support
git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@170294 91177308-0d34-0410-b5e6-96231b3b80d8
| -rw-r--r-- | docs/ReleaseNotes.html | 33 |
1 files changed, 33 insertions, 0 deletions
diff --git a/docs/ReleaseNotes.html b/docs/ReleaseNotes.html index 8a195f0b83..f1f70c77f7 100644 --- a/docs/ReleaseNotes.html +++ b/docs/ReleaseNotes.html @@ -174,6 +174,10 @@ int f(vector<map<int, double>>); <tt>-fsanitize=undefined</tt> and has grown the ability to check for several new types of undefined behavior. See the Users Manual for more information. + + <li><tt>-Wdocumentation</tt> enables warnings about documentation comments. + See section "Documentation comment support" for an example.</li> + <!-- Flesh this out prior to release. --> <!-- Document renaming of -faddress-sanitizer and -fthread-sanitizer. --> @@ -215,6 +219,35 @@ function call.</p> <code>pointer_with_type_tag</code> and <code>type_tag_for_datatype</code> attributes in Clang language extensions documentation.</p> +<h4>Documentation comment support</h4> +<p>Clang now supports documentation comments written in a Doxygen-like syntax. +Clang parses the comments and can detect syntactic and semantic errors in +comments. These warnings are off by default. Pass <tt>-Wdocumentation</tt> +flag to enable warnings about documentation comments.</p> + +<p>For example, given:</p> + +<pre>/// \param [in] Str the string. +/// \returns a modified string. +void do_something(const std::string &str);</pre> + +<p><tt>clang -Wdocumentation</tt> will emit two warnings:</p> + +<pre><b>doc-test.cc:3:6: <span class="warning">warning:</span></b> '\returns' command used in a comment that is attached to a function returning void [-Wdocumentation] +/// \returns a modified string. + <span class="caret">~^~~~~~~~~~~~~~~~~~~~~~~~~~</span> +<b>doc-test.cc:2:17: <span class="warning">warning:</span></b> parameter 'Str' not found in the function declaration [-Wdocumentation] +/// \param [in] Str the string. + <span class="caret">^~~</span> +<b>doc-test.cc:2:17: <span class="note">note:</span></b> did you mean 'str'? +/// \param [in] Str the string. + <span class="caret">^~~</span> + <span class="caret">str</span></pre> + +<p>libclang includes a new API, <tt>clang_FullComment_getAsXML</tt>, to convert +comments to XML documents. This API can be used to build documentation +extraction tools.</p> + <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <h3 id="newflags">New Compiler Flags</h3> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> |