warn-no-paramdoc option

#feat

Author: alandefreitas

docs/mrdocs.schema.json

@@ -462,14 +462,24 @@
     },
     "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`.",
+      "description": "When set to `true`, MrDocs outputs a warning message if a symbol that passes all filters is not documented.",
       "enum": [
         true,
         false
       ],
       "title": "Warn if symbols are not documented",
       "type": "boolean"
     },
+    "warn-no-paramdoc": {
+      "default": true,
+      "description": "When set to `true`, MrDocs outputs a warning message if a named function parameter is not documented.",
+      "enum": [
+        true,
+        false
+      ],
+      "title": "Warn if parameters are not documented",
+      "type": "boolean"
+    },
     "warnings": {
       "default": true,
       "description": "When set to `true`, MrDocs outputs warning messages during the generation of the documentation. It is usually recommended to enable warnings while writing the documentation.",

src/lib/Lib/ConfigOptions.json

@@ -482,7 +482,7 @@
       {
         "name": "warn-if-undocumented",
         "brief": "Warn if symbols are not documented",
-        "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`.",
+        "details": "When set to `true`, MrDocs outputs a warning message if a symbol that passes all filters is not documented.",
         "type": "bool",
         "default": true
       },
@@ -492,6 +492,13 @@
         "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
+      },
+      {
+        "name": "warn-no-paramdoc",
+        "brief": "Warn if parameters are not documented",
+        "details": "When set to `true`, MrDocs outputs a warning message if a named function parameter is not documented.",
+        "type": "bool",
+        "default": true
       }
     ]
   },

src/lib/Metadata/Finalizers/JavadocFinalizer.cpp

@@ -105,7 +105,7 @@ operator()(InfoTy& I)
     }
 }
 
-#define INFO(T) template void JavadocFinalizer::operator()<T##Info>(T##Info&);
+#define INFO(T) template void JavadocFinalizer::operator()<T## Info>(T## Info&);
 #include <mrdocs/Metadata/InfoNodesPascal.inc>
 
 void
@@ -516,13 +516,13 @@ emitWarnings() const
     MRDOCS_CHECK_OR(corpus_.config->warnings);
     warnUndocumented();
     warnDocErrors();
+    warnNoParamDocs();
 }
 
 void
 JavadocFinalizer::
 warnUndocumented() const
 {
-    MRDOCS_CHECK_OR(!corpus_.config->extractAll);
     MRDOCS_CHECK_OR(corpus_.config->warnIfUndocumented);
     for (auto& [id, name] : corpus_.undocumented_)
     {
@@ -599,10 +599,49 @@ warnParamErrors(FunctionInfo const& I) const
     }
     javadocParamNames.erase(lastUnique, javadocParamNames.end());
 
+    // Check for documented parameters that don't exist in the function
+    auto paramNames =
+        std::views::transform(I.Params, &Param::Name) |
+        std::views::filter([](std::string_view const& name) { return !name.empty(); });
+    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);
+        }
+    }
+
+}
+
+void
+JavadocFinalizer::
+warnNoParamDocs() const
+{
+    MRDOCS_CHECK_OR(corpus_.config->warnNoParamdoc);
+    for (auto const& I : corpus_.info_)
+    {
+        MRDOCS_CHECK_OR_CONTINUE(I->Extraction == ExtractionMode::Regular);
+        MRDOCS_CHECK_OR_CONTINUE(I->isFunction());
+        MRDOCS_CHECK_OR_CONTINUE(I->javadoc);
+        warnNoParamDocs(dynamic_cast<FunctionInfo const&>(*I));
+    }
+}
+
+void
+JavadocFinalizer::
+warnNoParamDocs(FunctionInfo const& I) const
+{
     // Check for function parameters that are not documented in javadoc
+    auto javadocParamNames = getJavadocParamNames(*I.javadoc);
     auto paramNames =
-        I.Params |
-        std::views::transform(&Param::Name) |
+        std::views::transform(I.Params, &Param::Name) |
         std::views::filter([](std::string_view const& name) { return !name.empty(); });
     for (auto const& paramName: paramNames)
     {
@@ -619,21 +658,30 @@ warnParamErrors(FunctionInfo const& I) const
         }
     }
 
-    // Check for documented parameters that don't exist in the function
-    for (std::string_view javadocParamName: javadocParamNames)
+    // Check for undocumented return type
+    if (I.javadoc->returns.empty() && I.ReturnType)
     {
-        if (std::ranges::find(paramNames, javadocParamName) == paramNames.end())
+        auto isVoid = [](TypeInfo const& returnType) -> bool
+        {
+            if (returnType.isNamed())
+            {
+                auto const& namedReturnType = dynamic_cast<NamedTypeInfo const&>(returnType);
+                return namedReturnType.Name->Name == "void";
+            }
+            return false;
+        };
+        if (!isVoid(*I.ReturnType))
         {
             auto primaryLoc = getPrimaryLocation(I);
             warn(
                 "{}:{}\n"
-                "{}: Documented parameter '{}' does not exist",
+                "{}: Missing documentation for return type",
                 primaryLoc->FullPath,
                 primaryLoc->LineNumber,
-                corpus_.Corpus::qualifiedName(I),
-                javadocParamName);
+                corpus_.Corpus::qualifiedName(I));
         }
     }
 }
 
+
 } // clang::mrdocs

src/lib/Metadata/Finalizers/JavadocFinalizer.hpp

@@ -181,6 +181,12 @@ class JavadocFinalizer
 
     void
     warnParamErrors(FunctionInfo const& I) const;
+
+    void
+    warnNoParamDocs() const;
+
+    void
+    warnNoParamDocs(FunctionInfo const& I) const;
 };
 
 } // clang::mrdocs

test-files/golden-tests/config/inherit-base-members/copy-dependencies.yml

@@ -1,3 +1,4 @@
 inherit-base-members: copy-dependencies
 exclude-symbols:
-  - excluded_base
+  - excluded_base
+warn-no-paramdoc: false

test-files/golden-tests/config/inherit-base-members/copy.yml

@@ -1,3 +1,4 @@
 inherit-base-members: copy-all
 exclude-symbols:
-  - excluded_base
+  - excluded_base
+warn-no-paramdoc: false

test-files/golden-tests/config/inherit-base-members/never.yml

@@ -1,3 +1,4 @@
 inherit-base-members: never
 exclude-symbols:
-  - excluded_base
+  - excluded_base
+warn-no-paramdoc: false

test-files/golden-tests/config/inherit-base-members/reference.yml

@@ -1,3 +1,4 @@
 inherit-base-members: reference
 exclude-symbols:
-  - excluded_base
+  - excluded_base
+warn-no-paramdoc: false

test-files/golden-tests/filters/symbol-name/extraction-mode.yml

@@ -29,3 +29,4 @@ implementation-defined:
   - 'excluded_ns::implementation_defined'
   - 'implementation_defined_ns'
   - 'implementation_defined'
+warn-no-paramdoc: false

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

@@ -93,6 +93,11 @@ bool
 operator()(char ch) const noexcept;
 ----
 
+=== Return Value
+
+
+True if ch is in the set, otherwise false.
+
 === Parameters
 
 
@@ -129,6 +134,11 @@ This function returns true if the        character is in the set, otherwise
 
 
 
+=== Return Value
+
+
+True if ch is in the set, otherwise false.
+
 === Parameters