From 2d1fa58fa958d603d1b29957fe846ec2702e3f7a Mon Sep 17 00:00:00 2001 From: Dmitri Gribenko Date: Sun, 16 Dec 2012 17:38:09 +0000 Subject: [PATCH] Clang ReleaseNotes: add information about documentation comments support llvm-svn: 170294 --- clang/docs/ReleaseNotes.html | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/clang/docs/ReleaseNotes.html b/clang/docs/ReleaseNotes.html index 8a195f0b83e5..f1f70c77f7e3 100644 --- a/clang/docs/ReleaseNotes.html +++ b/clang/docs/ReleaseNotes.html @@ -174,6 +174,10 @@ int f(vector<map<int, double>>); -fsanitize=undefined and has grown the ability to check for several new types of undefined behavior. See the Users Manual for more information. + +
  • -Wdocumentation enables warnings about documentation comments. + See section "Documentation comment support" for an example.
    • + @@ -215,6 +219,35 @@ function call.

    pointer_with_type_tag and type_tag_for_datatype attributes in Clang language extensions documentation.

    +

    Documentation comment support

    +

    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 -Wdocumentation +flag to enable warnings about documentation comments.

    + +

    For example, given:

    + +
    /// \param [in] Str the string.
+/// \returns a modified string.
+void do_something(const std::string &str);
    + +

    clang -Wdocumentation will emit two warnings:

    + +
    doc-test.cc:3:6: warning: '\returns' command used in a comment that is attached to a function returning void [-Wdocumentation]
+/// \returns a modified string.
+    ~^~~~~~~~~~~~~~~~~~~~~~~~~~
+doc-test.cc:2:17: warning: parameter 'Str' not found in the function declaration [-Wdocumentation]
+/// \param [in] Str the string.
+                ^~~
+doc-test.cc:2:17: note: did you mean 'str'?
+/// \param [in] Str the string.
+                ^~~
+                str
    + +

    libclang includes a new API, clang_FullComment_getAsXML, to convert +comments to XML documents. This API can be used to build documentation +extraction tools.

    +

    New Compiler Flags