warn-if-doc-error option

#feat

Author: alandefreitas

docs/mrdocs.schema.json

@@ -450,6 +450,16 @@
       "title": "Verbose output",
       "type": "boolean"
     },
+    "warn-if-doc-error": {
+      "default": true,
+      "description": "When set to `true`, MrDocs outputs a warning message if the documentation of a symbol has errors such as duplicate parameters and parameters that don't exist.",
+      "enum": [
+        true,
+        false
+      ],
+      "title": "Warn if documentation has errors",
+      "type": "boolean"
+    },
     "warn-if-undocumented": {
       "default": true,
       "description": "When set to `true`, MrDocs outputs a warning message if a symbol that passes all filters is not documented. This option is only effective when `extract-all` is set to `false`.",

src/lib/AST/ASTVisitor.cpp

@@ -3334,7 +3334,8 @@ checkUndocumented(
     {
         if (config_->warnIfUndocumented)
         {
-            undocumented_.erase({id, extractName(D)});
+            auto const it = undocumented_.find(id);
+            undocumented_.erase(it);
         }
         return {};
     }

src/lib/Lib/ConfigOptions.json

@@ -485,6 +485,13 @@
         "details": "When set to `true`, MrDocs outputs a warning message if a symbol that passes all filters is not documented. This option is only effective when `extract-all` is set to `false`.",
         "type": "bool",
         "default": true
+      },
+      {
+        "name": "warn-if-doc-error",
+        "brief": "Warn if documentation has errors",
+        "details": "When set to `true`, MrDocs outputs a warning message if the documentation of a symbol has errors such as duplicate parameters and parameters that don't exist.",
+        "type": "bool",
+        "default": true
       }
     ]
   },

src/lib/Lib/CorpusImpl.cpp

@@ -600,12 +600,7 @@ CorpusImpl::finalize()
     report::debug("Finalizing javadoc");
     JavadocFinalizer finalizer(*this);
     finalizer.build();
-
-    if (!config->extractAll && config->warnIfUndocumented)
-    {
-        finalizer.warnUndocumented();
-    }
-    undocumented_.clear();
+    finalizer.emitWarnings();
 }
 
 

src/lib/Metadata/Finalizers/JavadocFinalizer.cpp

@@ -509,4 +509,131 @@ checkExists(SymbolID const& id) const
     MRDOCS_ASSERT(corpus_.info_.contains(id));
 }
 
+void
+JavadocFinalizer::
+emitWarnings() const
+{
+    MRDOCS_CHECK_OR(corpus_.config->warnings);
+    warnUndocumented();
+    warnDocErrors();
+}
+
+void
+JavadocFinalizer::
+warnUndocumented() const
+{
+    MRDOCS_CHECK_OR(!corpus_.config->extractAll);
+    MRDOCS_CHECK_OR(corpus_.config->warnIfUndocumented);
+    for (auto& [id, name] : corpus_.undocumented_)
+    {
+        if (Info const* I = corpus_.find(id))
+        {
+            MRDOCS_CHECK_OR(!I->javadoc || I->Extraction == ExtractionMode::Regular);
+        }
+        warn("{}: Symbol is undocumented", name);
+    }
+    corpus_.undocumented_.clear();
+}
+
+void
+JavadocFinalizer::
+warnDocErrors() const
+{
+    MRDOCS_CHECK_OR(corpus_.config->warnIfDocError);
+    for (auto const& I : corpus_.info_)
+    {
+        MRDOCS_CHECK_OR_CONTINUE(I->Extraction == ExtractionMode::Regular);
+        MRDOCS_CHECK_OR_CONTINUE(I->isFunction());
+        warnParamErrors(dynamic_cast<FunctionInfo const&>(*I));
+    }
+}
+
+namespace {
+/* Get a list of all parameter names in javadoc
+
+    The javadoc parameter names can contain a single parameter or
+    a list of parameters separated by commas. This function
+    returns a list of all parameter names in the javadoc.
+ */
+SmallVector<std::string_view, 32>
+getJavadocParamNames(Javadoc const& javadoc)
+{
+    SmallVector<std::string_view, 32> result;
+    for (auto const& javadocParam: javadoc.params)
+    {
+        auto const& paramNamesStr = javadocParam.name;
+        for (auto paramNames = std::views::split(paramNamesStr, ',');
+             auto const& paramName: paramNames)
+        {
+            result.push_back(trim(std::string_view(paramName.begin(), paramName.end())));
+        }
+    }
+    return result;
+}
+
+}
+
+void
+JavadocFinalizer::
+warnParamErrors(FunctionInfo const& I) const
+{
+    MRDOCS_CHECK_OR(I.javadoc);
+
+    // Check for duplicate javadoc parameters
+    auto javadocParamNames = getJavadocParamNames(*I.javadoc);
+    std::ranges::sort(javadocParamNames);
+    auto [firstDup, lastUnique] = std::ranges::unique(javadocParamNames);
+    auto duplicateParamNames = std::ranges::subrange(firstDup, lastUnique);
+    auto [firstDupDup, _] = std::ranges::unique(duplicateParamNames);
+    for (auto uniqueDuplicateParamNames = std::ranges::subrange(firstDup, firstDupDup);
+         std::string_view duplicateParamName: uniqueDuplicateParamNames)
+    {
+        auto primaryLoc = getPrimaryLocation(I);
+        warn(
+            "{}:{}\n"
+            "{}: Duplicate parameter documentation for '{}'",
+            primaryLoc->FullPath,
+            primaryLoc->LineNumber,
+            corpus_.Corpus::qualifiedName(I),
+            duplicateParamName);
+    }
+    javadocParamNames.erase(lastUnique, javadocParamNames.end());
+
+    // Check for function parameters that are not documented in javadoc
+    auto paramNames =
+        I.Params |
+        std::views::transform(&Param::Name) |
+        std::views::filter([](std::string_view const& name) { return !name.empty(); });
+    for (auto const& paramName: paramNames)
+    {
+        if (std::ranges::find(javadocParamNames, paramName) == javadocParamNames.end())
+        {
+            auto primaryLoc = getPrimaryLocation(I);
+            warn(
+                "{}:{}\n"
+                "{}: Missing documentation for parameter '{}'",
+                primaryLoc->FullPath,
+                primaryLoc->LineNumber,
+                corpus_.Corpus::qualifiedName(I),
+                paramName);
+        }
+    }
+
+    // Check for documented parameters that don't exist in the function
+    for (std::string_view javadocParamName: javadocParamNames)
+    {
+        if (std::ranges::find(paramNames, javadocParamName) == paramNames.end())
+        {
+            auto primaryLoc = getPrimaryLocation(I);
+            warn(
+                "{}:{}\n"
+                "{}: Documented parameter '{}' does not exist",
+                primaryLoc->FullPath,
+                primaryLoc->LineNumber,
+                corpus_.Corpus::qualifiedName(I),
+                javadocParamName);
+        }
+    }
+}
+
 } // clang::mrdocs

src/lib/Metadata/Finalizers/JavadocFinalizer.hpp

@@ -53,17 +53,7 @@ class JavadocFinalizer
     }
 
     void
-    warnUndocumented() const
-    {
-        for (auto& [id, name] : corpus_.undocumented_)
-        {
-            if (Info const* I = corpus_.find(id))
-            {
-                MRDOCS_CHECK_OR(!I->javadoc || I->Extraction == ExtractionMode::Regular);
-            }
-            warn("{}: Symbol is undocumented", name);
-        }
-    }
+    emitWarnings() const;
 
     void
     operator()(Info& I)
@@ -182,6 +172,15 @@ class JavadocFinalizer
         MRDOCS_CHECK_OR(corpus_.config->warnings);
         return log(report::Level::warn, format, std::forward<Args>(args)...);
     }
+
+    void
+    warnUndocumented() const;
+
+    void
+    warnDocErrors() const;
+
+    void
+    warnParamErrors(FunctionInfo const& I) const;
 };
 
 } // clang::mrdocs

test-files/golden-tests/javadoc/inline/styled.adoc

@@ -76,6 +76,17 @@ compare(<<A,A>> const& other) const noexcept;
 
 `&hyphen;1` if `&ast;this &lt; other`, `0` if        `this &equals;&equals; other`, and 1 if `this &gt; other`&period;
 
+=== Parameters
+
+
+|===
+| Name | Description
+
+| *other*
+| The other object to compare against&period;
+
+|===
+
 
 
 [.small]#Created with https://www.mrdocs.com[MrDocs]#

test-files/golden-tests/javadoc/inline/styled.cpp

@@ -2,15 +2,17 @@
 
     Paragraph with `code`, *bold* text, and _italic_ text.
 
-	We can also escape these markers: \`, \*, and \_.
+    We can also escape these markers: \`, \*, and \_.
 
  */
 struct A {
     /** Compare function
 
-	    @return `-1` if `*this < other`, `0` if
+        @param other The other object to compare against.
+
+	@return `-1` if `*this < other`, `0` if
         `this == other`, and 1 if `this > other`.
-	 */
+     */
     int compare(A const& other) const noexcept;
 };
 

test-files/golden-tests/javadoc/inline/styled.html

@@ -91,6 +91,24 @@ <h3>Synopsis</h3>
 <h3>Return Value</h3>
 <p><code>-1</code><span> if </span><code>*this &lt; other</code> <span>, </span><code>0</code><span> if        </span><code>this &#x3D;&#x3D; other</code> <span>, and 1 if </span><code>this &gt; other</code> <span>.</span></p>
 
+</div>
+<div>
+<h3>Parameters</h3>
+<table>
+<thead>
+<tr>
+<th>Name</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>other</strong></td>
+<td><p><span>The other object to compare against.</span></p>
+</td>
+</tr>
+</tbody>
+</table>
 </div>
 </div>
 

test-files/golden-tests/javadoc/inline/styled.xml

@@ -22,7 +22,7 @@
       </para>
     </doc>
     <function name="compare" exception-spec="noexcept" id="CKPqawUTt6FNIN9qEFTMcdnvPkI=">
-      <file short-path="styled.cpp" source-path="styled.cpp" line="14"/>
+      <file short-path="styled.cpp" source-path="styled.cpp" line="16"/>
       <attr id="is-const"/>
       <return>
         <type name="int"/>
@@ -48,6 +48,9 @@
           <mono>this &gt; other</mono>
           <text>.</text>
         </returns>
+        <param name="other">
+          <text>The other object to compare against.</text>
+        </param>
       </doc>
     </function>
   </struct>

test-files/golden-tests/javadoc/param/param-direction.yml

@@ -0,0 +1 @@
+warn-if-doc-error: false

test-files/golden-tests/javadoc/param/param-duplicate.yml

@@ -0,0 +1 @@
+warn-if-doc-error: false

test-files/golden-tests/javadoc/ref/operator-param.adoc

@@ -73,7 +73,7 @@ bool
 | Name | Description
 
 | *ch*
-| The character to test.
+| The signed character to test.
 
 |===
 
@@ -93,6 +93,17 @@ bool
 operator()(char ch) const noexcept;
 ----
 
+=== Parameters
+
+
+|===
+| Name | Description
+
+| *ch*
+| The signed character to test.
+
+|===
+
 [#A-operator_call-0b]
 == <<A,A>>::operator()
 
@@ -125,7 +136,7 @@ This function returns true if the        character is in the set, otherwise
 | Name | Description
 
 | *ch*
-| The character to test&period;
+| The unsigned character to test&period;
 
 |===
 

test-files/golden-tests/javadoc/ref/operator-param.cpp

@@ -5,13 +5,17 @@ struct A {
         character is in the set, otherwise
         it returns false.
 
-        @param ch The character to test.
+        @param ch The unsigned character to test.
     */
     constexpr
     bool
     operator()(unsigned char ch) const noexcept;
 
-    /// @copydoc A::operator()(unsigned char) const
+    /**
+        @copydoc A::operator()(unsigned char) const
+
+        @param ch The signed character to test.
+     */
     constexpr
     bool
     operator()(char ch) const noexcept;