Updated documentation in file.

Simplified the update counting.

src/message.c

@@ -40,45 +40,6 @@ ctmbstr TY_(tidyLibraryVersion)(void)
  * General Message Utility Functions
  *********************************************************************/
 
-/* Updates document message counts and compares counts to options to
-** see if message display should go forward.
-*/
-static Bool UpdateCount( TidyDocImpl* doc, TidyReportLevel level )
-{
-  /* keep quiet after <ShowErrors> errors */
-  Bool go = ( doc->errors < cfg(doc, TidyShowErrors) );
-
-  switch ( level )
-  {
-      case TidyInfo:
-          doc->infoMessages++;
-          break;
-      case TidyWarning:
-          doc->warnings++;
-          break;
-      case TidyConfig:
-          doc->optionErrors++;
-          break;
-      case TidyAccess:
-          doc->accessErrors++;
-          break;
-      case TidyError:
-          doc->errors++;
-          break;
-      case TidyBadDocument:
-          doc->docErrors++;
-          break;
-      case TidyFatal:
-          /* Ack! */
-          break;
-      default:
-          break;
-  }
-
-  return go;
-}
-
-
 /* Returns the given node's tag as a string. */
 static char* TagToString(Node* tag, char* buf, size_t count)
 {
@@ -157,7 +118,7 @@ static ctmbstr HTMLVersion( TidyDocImpl* doc )
 static void messageOut( TidyMessageImpl *message )
 {
     TidyDocImpl *doc;
-    Bool go;
+    Bool go = yes;
 
     if ( !message )
         return;
@@ -167,10 +128,38 @@ static void messageOut( TidyMessageImpl *message )
     /* The filter has had a chance to suppress *any* message from output. */
     go = message->allowMessage;
 
-    /* Allow UpdateCount a chance to suppress further report messages. */
+    /* Update the count of each report type. */
+    switch ( message->level )
+    {
+        case TidyInfo:
+            doc->infoMessages++;
+            break;
+        case TidyWarning:
+            doc->warnings++;
+            break;
+        case TidyConfig:
+            doc->optionErrors++;
+            break;
+        case TidyAccess:
+            doc->accessErrors++;
+            break;
+        case TidyError:
+            doc->errors++;
+            break;
+        case TidyBadDocument:
+            doc->docErrors++;
+            break;
+        case TidyFatal:
+            /* Ack! */
+            break;
+        default:
+            break;
+    }
+
+    /* Suppress report messages if we've already reached the reporting limit. */
     if ( message->level <= TidyFatal )
     {
-        go = go & UpdateCount( doc, message->level );
+        go = go & ( doc->errors < cfg(doc, TidyShowErrors) );
     }
     
     /* If suppressing TidyInfo/TidyDialogueInfo on Reports, suppress them. */
@@ -229,7 +218,11 @@ static void messageOut( TidyMessageImpl *message )
 
 /* Functions of this type will create new instances of TidyMessage specific to
 ** the type of report being emitted. Many messages share the same fomatter for
-** messages, but new ones can be written as required.
+** messages, but new ones can be written as required. Please have a look at
+** the existing formatters in order to determine if an existing signature is
+** compatible with the report you wish to output before adding a new formatter.
+** In particular, if an existing formatter provides most of the local variables
+** required to populate your format string, try to use it.
 */
 typedef TidyMessageImpl*(messageFormatter)(TidyDocImpl* doc, Node *element, Node *node, uint code, uint level, va_list args);
 
@@ -244,7 +237,7 @@ static messageFormatter formatStandardDynamic;
 
 /* This structure ties together for each report Code the default 
 ** TidyReportLevel, the Formatter to be used to construct the message, and the
-** Next code to output, if applicable. Assuming an existing formatter can, 
+** next code to output, if applicable. Assuming an existing formatter can,
 ** this it makes it simple to output new reports, or to change report level by
 ** modifying this array.
 */
@@ -485,14 +478,30 @@ static struct _dispatchTable {
  *********************************************************************/
 
 
-/* Provides formatting for the Attribute-related reports. */
+/* Provides formatting for the Attribute-related reports. This formatter
+** should be reserved for messages generated by Tidy's accessibility module,
+** even if the signature matches some unrelated report that you wish to
+** generate.
+*/
 TidyMessageImpl *formatAccessReport(TidyDocImpl* doc, Node *element, Node *node, uint code, uint level, va_list args)
 {
     doc->badAccess |= BA_WAI;
+
+    /* Currently *all* cases are handled in the default, but maintain this
+       structure for possible future cases. */
+    switch (code)
+    {
+        default:
             return TY_(tidyMessageCreateWithNode)(doc, node, code, level );
     }
 
-/* Provides formatting for the Attribute-related reports. */
+    return NULL;
+}
+
+/* Provides formatting for the Attribute-related reports. This formatter
+** provides local variables that are used principally in the formats used for
+** the attribute related reports.
+*/
 TidyMessageImpl *formatAttributeReport(TidyDocImpl* doc, Node *element, Node *node, uint code, uint level, va_list args)
 {
     AttVal *av = NULL;
@@ -573,7 +582,8 @@ TidyMessageImpl *formatAttributeReport(TidyDocImpl* doc, Node *element, Node *no
 
 
 /* Provides report formatting *and* additional status settings for Tidy's
-** encoding reports.
+** encoding reports. Provides the local variables typically used for this type
+** of report.
 ** @todo: These status changes probably SHOULD be made in the calling code;
 **   however these states are captured to generate future output, which may be
 **   useful here in the long run.
@@ -633,6 +643,9 @@ TidyMessageImpl *formatEncodingReport(TidyDocImpl* doc, Node *element, Node *nod
 ** reports use the same basic data derived from the element and node, this
 ** formatter covers the vast majority of Tidy's report messages. Note that this
 ** formatter guarantees the values of TidyReportLevel in the dispatchTable[].
+** Some of the cases in this formatter start new contexts from the va_list
+** when the required data is simple. For complex local variable needs, it may
+** be preferred to write a new formatter.
 */
 TidyMessageImpl *formatStandard(TidyDocImpl* doc, Node *element, Node *node, uint code, uint level, va_list args)
 {
@@ -880,7 +893,9 @@ static void vReport(TidyDocImpl* doc, Node *element, Node *node, uint code, va_l
 ** possible, relevant data that can be reported. The only real drawbacks are
 ** having to pass NULL when some of the values aren't used, and the lack of
 ** type safety by using the variable arguments. To counter this some convenience
-** report output functions exist, too.
+** report output functions exist, too. Any new reports you wish to create must
+** be able to use this function signature, although convenience functions should
+** be added to abstract the full fuction signature and to preserve type safety.
 */
 void TY_(Report)(TidyDocImpl* doc, Node *element, Node *node, uint code, ...)
 {
@@ -894,7 +909,8 @@ void TY_(Report)(TidyDocImpl* doc, Node *element, Node *node, uint code, ...)
 /*********************************************************************
  * Convenience Reporting Functions
  * Functions that don't require the full signature of TY_(Report),
- * and help protect type safety by avoiding variable arguments.
+ * and help protect type safety by avoiding variable arguments in the
+ * rest of Tidy's code.
  *********************************************************************/
 
 #if SUPPORT_ACCESSIBILITY_CHECKS