maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity

Clang ReleaseNotes: add information about documentation comments support 

llvm-svn: 170294
This commit is contained in:
Dmitri Gribenko 2012-12-16 17:38:09 +00:00
parent 1b5562ad8e
commit 2d1fa58fa9
1 changed files with 33 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
clang/docs/ReleaseNotes.html
View File

@ -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 &amp;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>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->