From af06f361f3d0ae240de63ce6bf5137dab247cc46 Mon Sep 17 00:00:00 2001
From: James Wilcox <wilcoxjay@gmail.com>
Date: Sun, 11 Aug 2013 13:30:38 -0400
Subject: add config option WARN_IF_INCOMPLETE_DOC

Add a new warning class, "INCOMPLETE_DOC", and warning option
"WARN_IF_INCOMPLETE_DOC", to control whether you get a warning
for only documenting some of your function parameters.

All users who want to retain the current behavior set
WARN_IF_INCOMPLETE_DOC to the value of WARN_IF_DOC_ERROR.
---
 src/config.xml    | 17 ++++++++++++++---
 src/docparser.cpp | 14 +++++++-------
 src/message.cpp   |  8 ++++++++
 src/message.h     |  1 +
 4 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/src/config.xml b/src/config.xml
index d9b29aa..c704916 100644
--- a/src/config.xml
+++ b/src/config.xml
@@ -1316,22 +1316,33 @@ FILE_VERSION_FILTER = "cleartool desc -fmt \%Vn"
       <docs>
 <![CDATA[
  If the \c WARN_IF_DOC_ERROR tag is set to \c YES, doxygen will generate warnings for
- potential errors in the documentation, such as not documenting some
- parameters in a documented function, or documenting parameters that
+ potential errors in the documentation, such as documenting some
+ parameters in a documented function twice, or documenting parameters that
  don't exist or using markup commands wrongly.
 ]]>
       </docs>
     </option>
+    <option type='bool' id='WARN_IF_INCOMPLETE_DOC' defval='1'>
+      <docs>
+<![CDATA[
+ If \c WARN_IF_INCOMPLETE_DOC is set to \c YES, doxygen will warn about
+ incomplete function parameter documentation.
+ If set to \c NO, doxygen will accept that some parameters have no
+ documentation without warning.
+]]>
+      </docs>
+    </option>
     <option type='bool' id='WARN_NO_PARAMDOC' defval='0'>
       <docs>
 <![CDATA[
  This \c WARN_NO_PARAMDOC option can be enabled to get warnings for
  functions that are documented, but have no documentation for their parameters
  or return value. If set to \c NO, doxygen will only warn about
- wrong or incomplete parameter documentation, but not about the absence of
+ wrong parameter documentation, but not about the absence of
  documentation.
  If \ref cfg_extract_all "EXTRACT_ALL" is set to \c YES then this flag will
  automatically be disabled.
+ See also \ref cfg_warn_if_incomplete_paramdoc "WARN_IF_INCOMPLETE_PARAMDOC"
 ]]>
       </docs>
     </option>
diff --git a/src/docparser.cpp b/src/docparser.cpp
index 5e68c52..b63674a 100644
--- a/src/docparser.cpp
+++ b/src/docparser.cpp
@@ -512,7 +512,7 @@ static void checkRetvalName(const QCString &name)
  */
 static void checkUnOrMultipleDocumentedParams()
 {
-  if (g_memberDef && g_hasParamCommand && Config_getBool(WARN_IF_DOC_ERROR))
+  if (g_memberDef && g_hasParamCommand)
   {
     const ArgumentList &al=g_memberDef->isDocsForDefinition() ?
       g_memberDef->argumentList() :
@@ -544,7 +544,7 @@ static void checkUnOrMultipleDocumentedParams()
             if (argName == par) count++;
           }
         }
-        if (count > 1)
+        if ((count > 1) &&  Config_getBool(WARN_IF_DOC_ERROR))
         {
           warn_doc_error(g_memberDef->getDefFileName(),
                          g_memberDef->getDefLine(),
@@ -555,7 +555,7 @@ static void checkUnOrMultipleDocumentedParams()
                          " has multiple @param documentation sections").data());
         }
       }
-      if (notArgCnt>0)
+      if ((notArgCnt>0) && Config_getBool(WARN_IF_INCOMPLETE_DOC))
       {
         bool first=TRUE;
         QCString errMsg=
@@ -587,10 +587,10 @@ static void checkUnOrMultipleDocumentedParams()
             errMsg+="  parameter '"+argName+"'";
           }
         }
-        warn_doc_error(g_memberDef->getDefFileName(),
-                       g_memberDef->getDefLine(),
-                       "%s",
-                       substitute(errMsg,"%","%%").data());
+        warn_incomplete_doc(g_memberDef->getDefFileName(),
+                            g_memberDef->getDefLine(),
+                            "%s",
+                            substitute(errMsg,"%","%%").data());
       }
     }
   }
diff --git a/src/message.cpp b/src/message.cpp
index 95a7553..5f06984 100644
--- a/src/message.cpp
+++ b/src/message.cpp
@@ -240,6 +240,14 @@ void warn_undoc(const char *file,int line,const char *fmt, ...)
   va_end(args);
 }
 
+void warn_incomplete_doc(const char *file,int line,const char *fmt, ...)
+{
+  va_list args;
+  va_start(args, fmt);
+  do_warn(Config_getBool(WARN_IF_INCOMPLETE_DOC), file, line, warning_str, fmt, args);
+  va_end(args);
+}
+
 void warn_doc_error(const char *file,int line,const char *fmt, ...)
 {
   va_list args;
diff --git a/src/message.h b/src/message.h
index af49632..aa63ecb 100644
--- a/src/message.h
+++ b/src/message.h
@@ -29,6 +29,7 @@ extern void warn(const char *file,int line,const char *fmt, ...) PRINTFLIKE(3, 4
 extern void va_warn(const char* file, int line, const char* fmt, va_list args);
 extern void warn_simple(const char *file,int line,const char *text);
 extern void warn_undoc(const char *file,int line,const char *fmt, ...) PRINTFLIKE(3, 4);
+extern void warn_incomplete_doc(const char *file,int line,const char *fmt, ...) PRINTFLIKE(3, 4);
 extern void warn_doc_error(const char *file,int line,const char *fmt, ...) PRINTFLIKE(3, 4);
 extern void warn_uncond(const char *fmt, ...) PRINTFLIKE(1, 2);
 extern void err(const char *fmt, ...) PRINTFLIKE(1, 2);
-- 
cgit v0.12


From 46ac1937a1bce5a163b78dff53408ad61db4d100 Mon Sep 17 00:00:00 2001
From: arwedus <70707249+arwedus@users.noreply.github.com>
Date: Sat, 13 Feb 2021 22:00:38 +0100
Subject: fix typo in config.xml

make docs failed because of outdated ref (I renamed the parameter to
WARN_IF_INCOMPLETE_DOC to support generalizing the idea of "do not warn
on incomplete doc of x".
---
 src/config.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/config.xml b/src/config.xml
index c704916..7d5808a 100644
--- a/src/config.xml
+++ b/src/config.xml
@@ -1342,7 +1342,7 @@ FILE_VERSION_FILTER = "cleartool desc -fmt \%Vn"
  documentation.
  If \ref cfg_extract_all "EXTRACT_ALL" is set to \c YES then this flag will
  automatically be disabled.
- See also \ref cfg_warn_if_incomplete_paramdoc "WARN_IF_INCOMPLETE_PARAMDOC"
+ See also \ref cfg_warn_if_incomplete_doc "WARN_IF_INCOMPLETE_DOC"
 ]]>
       </docs>
     </option>
-- 
cgit v0.12