Merge pull request #8382 from arwedus/feature/config-warn-if-incomplete-doc

add config option WARN_IF_INCOMPLETE_DOC

4 files changed, 30 insertions, 10 deletions

diff --git a/src/config.xml b/src/config.xml
index d9b29aa..7d5808a 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_doc "WARN_IF_INCOMPLETE_DOC"
 ]]>
       </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);