Add WARN_LAYOUT_FILE option to toggle warnings in layout file

Also update the documentation regarding new layout behavior when
information is missing.

Author: doxygen

doc/customize.dox

@@ -420,6 +420,11 @@ this attribute can be used anyway (the default is `visible="yes"`).
 Some elements have a \c title attribute. This attribute can be used
 to customize the title Doxygen will use as a header for the piece.
 
+Note that as of doxygen version 1.13.1 and layout version 2.0, Doxygen
+will insert defaults for elements that are missing in
+the user defined layout file. This allows for the introduction of new elements, without having
+to update the user defined layout files to make them appear.
+For older Doxygen or layout versions, missing elements are treated as being invisible.
 
 \section xmlgenerator Using the XML output
 

src/config.xml

@@ -1458,6 +1458,16 @@ PATH=/Library/TeX/texbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
  If set to \c NO, Doxygen will accept undocumented enumeration values.
  If \ref cfg_extract_all "EXTRACT_ALL" is set to \c YES then this flag will
  automatically be disabled.
+]]>
+      </docs>
+    </option>
+    <option type='bool' id='WARN_LAYOUT_FILE' defval='1'>
+      <docs>
+<![CDATA[
+ If \c WARN_LAYOUT_FILE option is set to \c YES, Doxygen will warn
+ about issues found while parsing the user defined layout file, such as missing
+ or wrong elements. See also \ref cfg_layout_file "LAYOUT_FILE" for details.
+ If set to \c NO, problems with the layout file will be suppressed.
 ]]>
       </docs>
     </option>

src/layout.cpp

@@ -203,7 +203,7 @@ class LayoutParser
     }
     void error( const std::string &fileName,int lineNr,const std::string &msg)
     {
-      warn(fileName.c_str(),lineNr,"%s",msg.c_str());
+      warn_layout_(fileName.c_str(),lineNr,"%s",msg.c_str());
     }
     void startElement( const std::string &name, const XMLHandlers::Attributes& attrib );
     void endElement( const std::string &name );
@@ -559,11 +559,11 @@ class LayoutParser
         std::string fileName = m_locator->fileName();
         if (type.isEmpty())
         {
-          warn(fileName.c_str(),m_locator->lineNr(),"an entry tag within a navindex has no type attribute! Check your layout file!");
+          warn_layout_(fileName.c_str(),m_locator->lineNr(),"an entry tag within a navindex has no type attribute! Check your layout file!");
         }
         else
         {
-          warn(fileName.c_str(),m_locator->lineNr(),"the type '%s' is not supported for the entry tag within a navindex! Check your layout file!",qPrint(type));
+          warn_layout_(fileName.c_str(),m_locator->lineNr(),"the type '%s' is not supported for the entry tag within a navindex! Check your layout file!",qPrint(type));
         }
         m_invalidEntry=TRUE;
         return;
@@ -1365,7 +1365,7 @@ void LayoutParser::startElement( const std::string &name, const XMLHandlers::Att
   else
   {
     std::string fileName = m_locator->fileName();
-    warn(fileName.c_str(),m_locator->lineNr(),"Unexpected start tag '%s' found in scope='%s'!",
+    warn_layout_(fileName.c_str(),m_locator->lineNr(),"Unexpected start tag '%s' found in scope='%s'!",
         qPrint(name),qPrint(m_scope));
   }
 }
@@ -1711,7 +1711,7 @@ static void mergeDocEntryLists(const QCString &fileName,LayoutDocEntryList &targ
     {
       // for efficiency we move the elements from the source list to the target list, thus modifying the source list!
       //printf("--> insert at %zu before %s\n",*it,qPrint(*it<targetList.size()?targetList[*it]->id():"none"));
-      warn(fileName,1,"User defined layout misses entry '%s'. Using default value.",qPrint(id));
+      warn_layout_(fileName,1,"User defined layout misses entry '%s'. Using default value.",qPrint(id));
       targetList.insert(targetList.begin()+*it, std::move(sourceList[idx]));
     }
   }

src/message.cpp

@@ -251,6 +251,14 @@ void warn_doc_error_(const QCString &file,int line,const char *fmt, ...)
   va_end(args);
 }
 
+void warn_layout_(const QCString &file,int line,const char *fmt, ...)
+{
+  va_list args;
+  va_start(args, fmt);
+  do_warn(Config_getBool(WARN_LAYOUT_FILE), file, line, g_warningStr, fmt, args);
+  va_end(args);
+}
+
 void warn_uncond_(const char *fmt, ...)
 {
   va_list args;

src/message.h

@@ -32,6 +32,7 @@ extern void va_warn(const QCString &file, int line, const char* fmt, va_list arg
 extern void warn_undoc_(const QCString &file,int line,const char *fmt, ...) PRINTFLIKE(3, 4);
 extern void warn_incomplete_doc_(const QCString &file,int line,const char *fmt, ...) PRINTFLIKE(3, 4);
 extern void warn_doc_error_(const QCString &file,int line,const char *fmt, ...) PRINTFLIKE(3, 4);
+extern void warn_layout_(const QCString &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);
 extern void err_full_(const QCString &file,int line,const char *fmt, ...) PRINTFLIKE(3, 4);