Cleanup

- Added doxygen documentation to `tags.h`
- Consistency to `tags.c` header.
- Moved TY_(DeclareUserTag) to tags.c/.h for consistency with the other list
  parsing declaratory functions.
- Merged user tags parsing into the general list, eliminating a lot of redundant
  code.

include/tidy.h

@@ -584,7 +584,7 @@ TIDY_EXPORT Bool TIDY_CALL          tidySetOptionCallback(TidyDoc tdoc,
                                                           );
 
 /** This typedef represents the required signature for your provided callback
- ** function should you wish to register one with tidySetOptionCallback().
+ ** function should you wish to register one with tidySetConfigCallback().
  ** Your callback function will be provided with the following parameters.
  ** @param tdoc The document instance for which the callback was invoked.
  ** @param option The option name that was provided.
@@ -599,14 +599,33 @@ typedef Bool (TIDY_CALL *TidyConfigCallback)(TidyDoc tdoc, ctmbstr option, ctmbs
  ** configuration file options. Setting this callback allows a LibTidy
  ** application developer to examine command-line and configuration file options
  ** after LibTidy has examined them and failed to recognize them.
- ** Note that this is deprecated and you should instead migrate to
- ** tidySetConfigCallback().
  ** @result Returns `yes` upon success.
  */
 TIDY_EXPORT Bool TIDY_CALL          tidySetConfigCallback(TidyDoc tdoc,                      /**< The document to apply the callback to. */
                                                           TidyConfigCallback pConfigCallback /**< The name of a function of type TidyConfigCallback() to serve as your callback. */
                                                           );
 
+    
+/** This typedef represents the required signature for your provided callback
+ ** function should you wish to register one with tidySetConfigChangeCallback().
+ ** Your callback function will be provided with the following parameters.
+ ** @param tdoc The document instance for which the callback was invoked.
+ ** @param option The option that will be changed.
+ */
+typedef void (TIDY_CALL *TidyConfigChangeCallback)(TidyDoc tdoc, TidyOption option);
+
+/** Applications using TidyLib may want to be informed when changes to options
+ ** are made. Temporary changes made internally by Tidy are not reported, but
+ ** permanent changes made by Tidy (such as indent-spaces or output-encoding)
+ ** will be reported.
+ ** @note This callback is not currently implemented.
+ ** @result Returns `yes` upon success.
+ */
+TIDY_EXPORT Bool TIDY_CALL          tidySetConfigChangeCallback(TidyDoc tdoc,                      /**< The document to apply the callback to. */
+                                                                TidyConfigChangeCallback pCallback /**< The name of a function of type TidyConfigChangeCallback() to serve as your callback. */
+                                                                );
+
+
 /** @}
  ** @name Option ID Discovery
  ** @{

src/attrs.c

@@ -2186,8 +2186,6 @@ static
 AttVal *SortAttVal( TidyDocImpl* doc, AttVal *list, TidyAttrSortStrategy strat)
 {
     /* Get the list from the passed-in tidyDoc. */
-//    ctmbstr* priorityList = (ctmbstr*)doc->attribs.priorityAttribs.list;
-//    ctmbstr priorityList[] = { "id", NULL };
     ctmbstr* priorityList = (ctmbstr*)doc->attribs.priorityAttribs.list;
 
     ptAttValComparator ptComparator = GetAttValComparator(strat, priorityList);

src/config.c

@@ -157,7 +157,6 @@ static ParseProperty ParseList;
 static ParseProperty ParseName;
 static ParseProperty ParseCSS1Selector;
 static ParseProperty ParseString;
-static ParseProperty ParseTagNames;
 static ParseProperty ParseCharEnc;
 static ParseProperty ParseDocType;
 static ParseProperty ParseTabs;
@@ -173,13 +172,13 @@ static const TidyOptionImpl option_defs[] =
     { TidyAltText,                 MR, "alt-text",                    ST, 0,               ParseString,       NULL                },
     { TidyAnchorAsName,            MR, "anchor-as-name",              BL, yes,             ParsePickList,     &boolPicks          },
     { TidyAsciiChars,              ME, "ascii-chars",                 BL, no,              ParsePickList,     &boolPicks          },
-    { TidyBlockTags,               MT, "new-blocklevel-tags",         ST, 0,               ParseTagNames,     NULL                },
+    { TidyBlockTags,               MT, "new-blocklevel-tags",         ST, 0,               ParseList,         NULL                },
     { TidyBodyOnly,                DD, "show-body-only",              IN, no,              ParsePickList,     &autoBoolPicks      },
     { TidyBreakBeforeBR,           PP, "break-before-br",             BL, no,              ParsePickList,     &boolPicks          },
     { TidyCharEncoding,            CE, "char-encoding",               IN, UTF8,            ParseCharEnc,      &charEncPicks       },
     { TidyCoerceEndTags,           MR, "coerce-endtags",              BL, yes,             ParsePickList,     &boolPicks          },
     { TidyCSSPrefix,               MR, "css-prefix",                  ST, 0,               ParseCSS1Selector, NULL,           "c" },
-    { TidyCustomTags,              IR, "new-custom-tags",             ST, 0,               ParseTagNames,     NULL                }, /* 20170309 - Issue #119 */
+    { TidyCustomTags,              IR, "new-custom-tags",             ST, 0,               ParseList,         NULL                }, /* 20170309 - Issue #119 */
     { TidyDecorateInferredUL,      MX, "decorate-inferred-ul",        BL, no,              ParsePickList,     &boolPicks          },
     { TidyDoctype,                 DT, "doctype",                     ST, 0,               ParseDocType,      &doctypePicks       },
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
@@ -193,7 +192,7 @@ static const TidyOptionImpl option_defs[] =
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
     { TidyEmacsFile,               IR, "gnu-emacs-file",              ST, 0,               ParseString,       NULL                },
 #endif
-    { TidyEmptyTags,               MT, "new-empty-tags",              ST, 0,               ParseTagNames,     NULL                },
+    { TidyEmptyTags,               MT, "new-empty-tags",              ST, 0,               ParseList,         NULL                },
     { TidyEncloseBlockText,        MR, "enclose-block-text",          BL, no,              ParsePickList,     &boolPicks          },
     { TidyEncloseBodyText,         MR, "enclose-text",                BL, no,              ParsePickList,     &boolPicks          },
     { TidyErrFile,                 IO, "error-file",                  ST, 0,               ParseString,       NULL                },
@@ -211,7 +210,7 @@ static const TidyOptionImpl option_defs[] =
     { TidyIndentCdata,             PP, "indent-cdata",                BL, no,              ParsePickList,     &boolPicks          },
     { TidyIndentContent,           PP, "indent",                      IN, TidyNoState,     ParsePickList,     &autoBoolPicks      },
     { TidyIndentSpaces,            PP, "indent-spaces",               IN, 2,               ParseInt,          NULL                },
-    { TidyInlineTags,              MT, "new-inline-tags",             ST, 0,               ParseTagNames,     NULL                },
+    { TidyInlineTags,              MT, "new-inline-tags",             ST, 0,               ParseList,         NULL                },
     { TidyJoinClasses,             MX, "join-classes",                BL, no,              ParsePickList,     &boolPicks          },
     { TidyJoinStyles,              MX, "join-styles",                 BL, yes,             ParsePickList,     &boolPicks          },
     { TidyKeepFileTimes,           IO, "keep-time",                   BL, no,              ParsePickList,     &boolPicks          },
@@ -234,7 +233,7 @@ static const TidyOptionImpl option_defs[] =
     { TidyOutputBOM,               CE, "output-bom",                  IN, TidyAutoState,   ParsePickList,     &autoBoolPicks      },
     { TidyPPrintTabs,              PP, "indent-with-tabs",            BL, no,              ParseTabs,         &boolPicks          }, /* 20150515 - Issue #108 */
     { TidyPreserveEntities,        ME, "preserve-entities",           BL, no,              ParsePickList,     &boolPicks          },
-    { TidyPreTags,                 MT, "new-pre-tags",                ST, 0,               ParseTagNames,     NULL                },
+    { TidyPreTags,                 MT, "new-pre-tags",                ST, 0,               ParseList,         NULL                },
     { TidyPriorityAttributes,      PP, "priority-attributes",         ST, 0,               ParseList,         NULL                },
     { TidyPunctWrap,               PP, "punctuation-wrap",            BL, no,              ParsePickList,     &boolPicks          },
     { TidyQuiet,                   DD, "quiet",                       BL, no,              ParsePickList,     &boolPicks          },
@@ -292,7 +291,7 @@ static const struct {
     ctmbstr name;                /**< name of the deprecated option */
     TidyOptionId replacementId;  /**< Id of the replacement option, or 0 if none. */
 } deprecatedOptions[] = {
-//    { "show-body-only", TidyBodyOnly },
+/*    { "show-body-only", TidyBodyOnly }, */
     { NULL }
 };
 
@@ -980,7 +979,7 @@ Bool TY_(ParseConfigOption)( TidyDocImpl* doc, ctmbstr optnam, ctmbstr optval )
         if (NULL != doc->pOptCallback)
             status = (*doc->pOptCallback)( optnam, optval );
         if (NULL != doc->pConfigCallback )
-            status = status && (*doc->pConfigCallback)( tidyImplToDoc(doc), optnam, optval );
+        status = status || (*doc->pConfigCallback)( tidyImplToDoc(doc), optnam, optval );
         if (!status && isDeprecated)
             status = subDeprecatedOption( doc, optnam, optval);
         if (!status)
@@ -1195,6 +1194,14 @@ void TY_(DeclareListItem)( TidyDocImpl* doc, const TidyOptionImpl* opt, ctmbstr
             TY_(DefineMutedMessage)( doc, opt, name );
             break;
 
+        case TidyInlineTags:
+        case TidyBlockTags:
+        case TidyEmptyTags:
+        case TidyPreTags:
+        case TidyCustomTags:
+            TY_(DeclareUserTag)( doc, opt, name );
+            break;
+
         default:
             break;
     }
@@ -1438,115 +1445,6 @@ Bool ParseTabs( TidyDocImpl* doc, const TidyOptionImpl* entry )
 }
 
 
-/* Coordinates Config update and Tags data */
-void TY_(DeclareUserTag)( TidyDocImpl* doc, TidyOptionId optId,
-                            UserTagType tagType, ctmbstr name )
-{
-  ctmbstr prvval = cfgStr( doc, optId );
-  tmbstr catval = NULL;
-  ctmbstr theval = name;
-  if ( prvval )
-  {
-    uint len = TY_(tmbstrlen)(name) + TY_(tmbstrlen)(prvval) + 3;
-    catval = TY_(tmbstrndup)( doc->allocator, prvval, len );
-    TY_(tmbstrcat)( catval, ", " );
-    TY_(tmbstrcat)( catval, name );
-    theval = catval;
-  }
-  TY_(DefineTag)( doc, tagType, name );
-  SetOptionValue( doc, optId, theval );
-  if ( catval )
-    TidyDocFree( doc, catval );
-}
-
-
-/* a space or comma separated list of tag names */
-Bool ParseTagNames( TidyDocImpl* doc, const TidyOptionImpl* option )
-{
-    TidyConfigImpl* cfg = &doc->config;
-    tmbchar buf[1024];
-    uint i = 0, nTags = 0;
-    uint c = SkipWhite( cfg );
-    UserTagType ttyp = tagtype_null;
-
-    switch ( option->id )
-    {
-        case TidyInlineTags:  ttyp = tagtype_inline;              break;
-        case TidyBlockTags:   ttyp = tagtype_block;               break;
-        case TidyEmptyTags:   ttyp = tagtype_empty;               break;
-        case TidyPreTags:     ttyp = tagtype_pre;                 break;
-        case TidyCustomTags:  ttyp = cfg(doc, TidyUseCustomTags); break;
-        default:
-            TY_(ReportUnknownOption)( doc, option->name );
-            return no;
-    }
-
-    SetOptionValue( doc, option->id, NULL );
-    TY_(FreeDeclaredTags)( doc, ttyp );
-    cfg->defined_tags |= ttyp;
-
-    do
-    {
-        if (c == ' ' || c == '\t' || c == ',')
-        {
-            c = AdvanceChar( cfg );
-            continue;
-        }
-
-        if ( c == '\r' || c == '\n' )
-        {
-            uint c2 = AdvanceChar( cfg );
-            if ( c == '\r' && c2 == '\n' )
-                c = AdvanceChar( cfg );
-            else
-                c = c2;
-
-            if ( !TY_(IsWhite)(c) )
-            {
-                buf[i] = 0;
-                TY_(UngetChar)( c, cfg->cfgIn );
-                TY_(UngetChar)( '\n', cfg->cfgIn );
-                break;
-            }
-        }
-
-        /*
-        if ( c == '\n' )
-        {
-            c = AdvanceChar( cfg );
-            if ( !TY_(IsWhite)(c) )
-            {
-                buf[i] = 0;
-                TY_(UngetChar)( c, cfg->cfgIn );
-                TY_(UngetChar)( '\n', cfg->cfgIn );
-                break;
-            }
-        }
-        */
-
-        while ( i < sizeof(buf)-2 && c != EndOfStream && !TY_(IsWhite)(c) && c != ',' )
-        {
-            buf[i++] = (tmbchar) c;
-            c = AdvanceChar( cfg );
-        }
-
-        buf[i] = '\0';
-        if (i == 0)          /* Skip empty tag definition.  Possible when */
-            continue;        /* there is a trailing space on the line. */
-            
-        /* add tag to dictionary */
-        TY_(DeclareUserTag)( doc, option->id, ttyp, buf );
-        i = 0;
-        ++nTags;
-    }
-    while ( c != EndOfStream );
-
-    if ( i > 0 )
-      TY_(DeclareUserTag)( doc, option->id, ttyp, buf );
-    return ( nTags > 0 );
-}
-
-
 /* a string including whitespace */
 /* munges whitespace sequences */
 Bool ParseString( TidyDocImpl* doc, const TidyOptionImpl* option )

src/config.h

@@ -366,15 +366,6 @@ ctmbstr TY_(CharEncodingName)( int encoding );
 ctmbstr TY_(CharEncodingOptName)( int encoding );
 
 
-/** Coordinates Config update and Tags data.
- ** @param doc The Tidy document.
- ** @param optId The option ID the tag is intended for.
- ** @param tagType The type of tag (pre, inline, etc.).
- ** @param name The name of the new tag.
- */
-void TY_(DeclareUserTag)( TidyDocImpl* doc, TidyOptionId optId,
-                         uint tagType, ctmbstr name );
-
 /** Coordinates Config update and list data.
  ** @param doc The Tidy document.
  ** @param opt The option the list item is intended for.

src/forward.h

@@ -34,6 +34,7 @@ typedef struct _TidyDocImpl TidyDocImpl;
 struct _TidyMessageImpl;
 typedef struct _TidyMessageImpl TidyMessageImpl;
 
+/* @todo: this name isn't very instructive! */
 struct _Dict;
 typedef struct _Dict Dict;
 

src/tags.c

@@ -1,10 +1,11 @@
-/* tags.c -- recognize HTML tags
+/* tags.c
-
+ * Recognize HTML tags.
-  (c) 1998-2008 (W3C) MIT, ERCIM, Keio University
+ *
-  See tidy.h for the copyright notice.
+ * Copyright (c) 1998-2017 World Wide Web Consortium (Massachusetts
-
+ * Institute of Technology, European Research Consortium for Informatics
-  The HTML tags are stored as 8 bit ASCII strings.
+ * and Mathematics, Keio University) and HTACG.
-
+ *
+ * See tidy.h for the copyright notice.
  */
 
 #include "tidy-int.h"
@@ -475,6 +476,38 @@ static void declare( TidyDocImpl* doc, TidyTagImpl* tags,
     }
 }
 
+
+/* Coordinates Config update and Tags data */
+void TY_(DeclareUserTag)( TidyDocImpl* doc, const TidyOptionImpl* opt, ctmbstr name )
+{
+    UserTagType tagType;
+
+    switch ( opt->id )
+    {
+        case TidyInlineTags:  tagType = tagtype_inline;              break;
+        case TidyBlockTags:   tagType = tagtype_block;               break;
+        case TidyEmptyTags:   tagType = tagtype_empty;               break;
+        case TidyPreTags:     tagType = tagtype_pre;                 break;
+        case TidyCustomTags:
+        {
+            switch (cfg( doc, TidyUseCustomTags ))
+            {
+                case TidyCustomBlocklevel: tagType = tagtype_block;  break;
+                case TidyCustomEmpty:      tagType = tagtype_empty;  break;
+                case TidyCustomInline:     tagType = tagtype_inline; break;
+                case TidyCustomPre:        tagType = tagtype_pre;    break;
+                default: TY_(ReportUnknownOption)( doc, opt->name ); return;
+            }
+        } break;
+        default:
+        TY_(ReportUnknownOption)( doc, opt->name );
+        return;
+    }
+
+    TY_(DefineTag)( doc, tagType, name );
+}
+
+
 #if defined(ENABLE_DEBUG_LOG)
 void ListElementsPerVersion( uint vers, Bool has )
 {
@@ -526,7 +559,6 @@ void show_have_html5(void)
 /* public interface for finding tag by name */
 Bool TY_(FindTag)( TidyDocImpl* doc, Node *node )
 {
-    TidyUseCustomTagsState configtype = cfg( doc, TidyUseCustomTags );
     const Dict *np = NULL;
 
     if ( cfgBool(doc, TidyXmlTags) )
@@ -545,18 +577,9 @@ Bool TY_(FindTag)( TidyDocImpl* doc, Node *node )
        earlier, although if it's earlier we will complain about it elsewhere. */
     if ( TY_(nodeIsAutonomousCustomTag)( doc, node) )
     {
-        UserTagType type;
+        const TidyOptionImpl* opt = TY_(getOption)( TidyCustomTags );
 
-        if ( configtype == TidyCustomEmpty )
+        TY_(DeclareUserTag)( doc, opt, node->element );
-            type = tagtype_empty;
-        else if ( configtype == TidyCustomInline )
-            type = tagtype_inline;
-        else if ( configtype == TidyCustomPre )
-            type = tagtype_pre;
-        else
-            type = tagtype_block;
-        
-        TY_(DeclareUserTag)( doc, TidyCustomTags, type, node->element );
         node->tag = tagsLookup(doc, &doc->tags, node->element);
 
         /* Output a message the first time we encounter an autonomous custom 

src/tags.h

@@ -1,88 +1,231 @@
 #ifndef __TAGS_H__
 #define __TAGS_H__
 
-/* tags.h -- recognize HTML tags
+/**************************************************************************//**
-
+ * @file
-  (c) 1998-2006 (W3C) MIT, ERCIM, Keio University
+ * Recognize HTML Tags.
-  See tidy.h for the copyright notice.
+ *
-
+ * The HTML tags are stored as 8 bit ASCII strings.
-  The HTML tags are stored as 8 bit ASCII strings.
+ * Use lookupw() to find a tag given a wide char string.
-  Use lookupw() to find a tag given a wide char string.
+ *
-
+ * @author  HTACG, et al (consult git log)
-*/
+ *
+ * @copyright
+ *     Copyright (c) 1998-2017 World Wide Web Consortium (Massachusetts
+ *     Institute of Technology, European Research Consortium for Informatics
+ *     and Mathematics, Keio University) and HTACG.
+ * @par
+ *     All Rights Reserved.
+ * @par
+ *     See `tidy.h` for the complete license.
+ *
+ * @date Additional updates: consult git log
+ *
+ ******************************************************************************/
 
 #include "forward.h"
 #include "attrdict.h"
 
-typedef void (Parser)( TidyDocImpl* doc, Node *node, GetTokenMode mode );
+/** @addtogroup internal_api */
-typedef void (CheckAttribs)( TidyDocImpl* doc, Node *node );
+/** @{ */
 
-/*
+
- Tag dictionary node
+/***************************************************************************//**
+ ** @defgroup tags_h HTML Tags
+ **
+ ** This module organizes all of Tidy's HTML tag operations, such as parsing
+ ** tags, defining tags, and user-defined tags.
+ **
+ ** @{
+ ******************************************************************************/
+
+
+/** @name Basic Structures and Tag Operations.
+ ** These structures form the backbone of Tidy tag processing, and the
+ ** functions in this group provide basic operations with tags and nodes.
  */
+/** @{ */
 
-/* types of tags that the user can define */
+
+/** This enumeration defines the types of user-defined tags that can be
+ ** created.
+ */
 typedef enum
 {
-    tagtype_null = 0,
+    tagtype_null = 0,   /**< First item marker. */
-    tagtype_empty = 1,
+    tagtype_empty = 1,  /**< Tag is an empty element. */
-    tagtype_inline = 2,
+    tagtype_inline = 2, /**< Tag is an inline element. */
-    tagtype_block = 4,
+    tagtype_block = 4,  /**< Tag is a block level element. */
-    tagtype_pre = 8
+    tagtype_pre = 8     /**< Tag is a preformatted tag. */
 } UserTagType;
 
+
+/** This typedef describes a function to be used to parse HTML of a Tidy tag.
+ */
+typedef void (Parser)( TidyDocImpl* doc, Node *node, GetTokenMode mode );
+
+
+/** This typedef describes a function be be used to check the attributes
+ ** of a Tidy tag.
+ */
+typedef void (CheckAttribs)( TidyDocImpl* doc, Node *node );
+
+
+/** Defines a dictionary entry for a single Tidy tag, including all of the
+ ** relevant information that it requires.
+ */
 struct _Dict
 {
-    TidyTagId       id;
+    TidyTagId           id;       /**< Identifier for this tag. */
-    tmbstr          name;
+    tmbstr              name;     /**< The tag name. */
-    uint            versions;
+    uint                versions; /**< Accumulates potential HTML versions. See TY_(ConstrainVersion). */
-    AttrVersion const *    attrvers;
+    AttrVersion const * attrvers; /**< Accumulates potential HTML versions for attributes. */
-    uint            model;
+    uint                model;    /**< Indicates the relevant content models for the tag. See lexer.h; there is no enum. */
-    Parser*         parser;
+    Parser*             parser;   /**< Specifies the parser to use for this tag. */
-    CheckAttribs*   chkattrs;
+    CheckAttribs*       chkattrs; /**< Specifies the function to check this tag's attributes. */
-    Dict*           next;
+    Dict*               next;     /**< Link to next tag. */
 };
 
+
+/** This enum indicates the maximum size of the has table for tag hash lookup.
+ */
 enum
 {
-    ELEMENT_HASH_SIZE=178u
+    ELEMENT_HASH_SIZE=178u  /**< Maximum number of tags in the hash table. */
 };
 
-struct _DictHash
+
+/** This structure provide hash lookup for Tidy tags.
+ */
+typedef struct _DictHash
 {
-    Dict const*         tag;
+    Dict const*         tag;   /**< The current tag. */
-    struct _DictHash*   next;
+    struct _DictHash*   next;  /**< The next tag. */
-};
+} DictHash;
 
-typedef struct _DictHash DictHash;
 
-struct _TidyTagImpl
+/** This structure consists of the lists of all tags known to Tidy.
+ */
+typedef struct _TidyTagImpl
 {
-    Dict* xml_tags;                /* placeholder for all xml tags */
+    Dict* xml_tags;                        /**< Placeholder for all xml tags. */
-    Dict* declared_tag_list;       /* User declared tags */
+    Dict* declared_tag_list;               /**< User-declared tags. */
-    DictHash* hashtab[ELEMENT_HASH_SIZE];
+    DictHash* hashtab[ELEMENT_HASH_SIZE];  /**< All of Tidy's built-in tags. */
-};
+} TidyTagImpl;
 
-typedef struct _TidyTagImpl TidyTagImpl;
 
-/* interface for finding tag by name */
+/** Coordinates Config update and Tags data.
+ ** @param doc The Tidy document.
+ ** @param opt The option the tag is intended for.
+ ** @param name The name of the new tag.
+ */
+void TY_(DeclareUserTag)( TidyDocImpl* doc, const TidyOptionImpl* opt, ctmbstr name );
+
+
+/** Interface for finding a tag by TidyTagId.
+ ** @param tid The TidyTagId to search for.
+ ** @returns An instance of a Tidy tag.
+ */
 const Dict* TY_(LookupTagDef)( TidyTagId tid );
-Bool    TY_(FindTag)( TidyDocImpl* doc, Node *node );
-Parser* TY_(FindParser)( TidyDocImpl* doc, Node *node );
-void    TY_(DefineTag)( TidyDocImpl* doc, UserTagType tagType, ctmbstr name );
-void    TY_(FreeDeclaredTags)( TidyDocImpl* doc, UserTagType tagType ); /* tagtype_null to free all */
 
+/** Assigns the node's tag.
+ ** @param doc The Tidy document.
+ ** @param node The node to assign the tag to.
+ ** @returns Returns a bool indicating whether or not the tag was assigned.
+ */
+Bool    TY_(FindTag)( TidyDocImpl* doc, Node *node );
+
+
+/** Finds the parser function for a given node.
+ ** @param doc The Tidy document.
+ ** @param node The node to lookup.
+ ** @returns The parser for the given node.
+ */
+Parser* TY_(FindParser)( TidyDocImpl* doc, Node *node );
+
+
+/** Defines a new user-defined tag.
+ ** @param doc The Tidy document.
+ ** @param tagType The type of user-defined tag to define.
+ ** @param name The name of the new tag.
+ */
+void    TY_(DefineTag)( TidyDocImpl* doc, UserTagType tagType, ctmbstr name );
+
+
+/** Frees user-defined tags of the given type, or all user tags in given
+ ** `tagtype_null`.
+ ** @param doc The Tidy document.
+ ** @param tagType The type of tag to free, or `tagtype_null` to free all
+ **        user-defined tags.
+ */
+void    TY_(FreeDeclaredTags)( TidyDocImpl* doc, UserTagType tagType );
+
+
+/** Initiates an iterator for a list of user-declared tags, including autonomous
+ ** custom tags detected in the document if @ref TidyUseCustomTags is not set to
+ ** **no**.
+ ** @param doc An instance of a TidyDocImp to query.
+ ** @result Returns a TidyIterator, which is a token used to represent the
+ **         current position in a list within LibTidy.
+ */
 TidyIterator   TY_(GetDeclaredTagList)( TidyDocImpl* doc );
+
+
+/** Given a valid TidyIterator initiated with TY_(GetDeclaredTagList)(),
+ ** returns a string representing a user-declared or autonomous custom tag.
+ ** @remark Specifying tagType limits the scope of the tags to one of
+ **         @ref UserTagType types. Note that autonomous custom tags (if used)
+ **         are added to one of these option types, depending on the value of
+ **         @ref TidyUseCustomTags.
+ ** @param doc The Tidy document.
+ ** @param tagType The type of tag to iterate through.
+ ** @param iter The iterator token provided initially by
+ **        TY_(GetDeclaredTagList)().
+ ** @result A string containing the next tag.
+ */
 ctmbstr        TY_(GetNextDeclaredTag)( TidyDocImpl* doc, UserTagType tagType,
                                         TidyIterator* iter );
 
+
+/** Initializes tags and tag structures for the given Tidy document.
+ ** @param doc The Tidy document.
+ */
 void TY_(InitTags)( TidyDocImpl* doc );
+
+
+/** Frees the tags and structures used by Tidy for tags.
+ ** @param doc The Tidy document.
+ */
 void TY_(FreeTags)( TidyDocImpl* doc );
-void TY_(AdjustTags)( TidyDocImpl *doc ); /* if NOT HTML5 DOCTYPE, fall back to HTML4 legacy mode */
+
-void TY_(ResetTags)( TidyDocImpl *doc ); /* set table to HTML5 mode */
+
+/** Tidy defaults to HTML5 mode. If the <!DOCTYPE ...> is found to NOT be
+ ** HTML5, then adjust the tags table to HTML4 mode.
+ ** @param doc The Tidy document.
+ */
+void TY_(AdjustTags)( TidyDocImpl *doc );
+
+
+/** Reset the tags table back to default HTML5 mode.
+ ** @param doc The Tidy document.
+ */
+void TY_(ResetTags)( TidyDocImpl *doc );
+
+
+/** Indicates whether or not the Tidy is procesing in HTML5 mode.
+ ** @param doc The Tidy document.
+ ** @returns Returns `yes` if processing in HTML5 mode.
+ */
 Bool TY_(IsHTML5Mode)( TidyDocImpl *doc );
 
-/* Parser methods for tags */
+
+/** @} */
+/** @name Parser Methods And Attribute Checker Functions for Tags
+ ** These functions define the parsers and attribute checking functions for
+ ** each of Tidy's tags.
+ */
+/** @{ */
+
 
 Parser TY_(ParseHTML);
 Parser TY_(ParseHead);
@@ -109,39 +252,115 @@ Parser TY_(ParseNamespace);
 
 CheckAttribs TY_(CheckAttributes);
 
-/* 0 == TidyTag_UNKNOWN */
+
+/** @} */
+/** @name Other Tag and Node Lookup Functions
+ ** These functions perform additional lookup on tags and nodes.
+ */
+/** @{ */
+
+
+/** Gets the TidyTagId of the given node. 0 == TidyTag_UNKNOWN.
+ */
 #define TagId(node)        ((node) && (node)->tag ? (node)->tag->id : TidyTag_UNKNOWN)
+
+
+/** Determines if the given node is of the given tag id type.
+ */
 #define TagIsId(node, tid) ((node) && (node)->tag && (node)->tag->id == tid)
 
+
+/** Inquires whether or not the given node is a text node.
+ ** @param node The node being interrogated.
+ ** @returns The status of the inquiry.
+ */
 Bool TY_(nodeIsText)( Node* node );
+
+
+/** Inquires whether or not the given node is an element node.
+ ** @param node The node being interrogated.
+ ** @returns The status of the inquiry.
+ */
 Bool TY_(nodeIsElement)( Node* node );
 
+
+/** Inquires whether or not the given node has any text.
+ ** @param doc The Tidy document.
+ ** @param node The node being interrogated.
+ ** @returns The status of the inquiry.
+ */
 Bool TY_(nodeHasText)( TidyDocImpl* doc, Node* node );
 
-/* True if the element looks like it's an autonomous custom element tag. */
+
+/** Inquires whether the given element looks like it's an autonomous custom
+ ** element tag.
+ ** @param element A string to be checked.
+ ** @returns The status of the inquiry.
+ */
 Bool TY_(elementIsAutonomousCustomFormat)( ctmbstr element );
 
-/* True if the node looks like it's an autonomous custom element tag. */
+
+/** Inquires whether the given node looks like it's an autonomous custom
+ ** element tag.
+ ** @param node The node being interrogated.
+ ** @returns The status of the inquiry.
+ */
 Bool TY_(nodeIsAutonomousCustomFormat)( Node* node );
 
-/* True if the node looks like it's an autonomous custom element tag, and
+
-   TidyCustomTags is not disabled, and we're in HTML5 mode, which are all
+/** True if the node looks like it's an autonomous custom element tag, and
-   requirements for valid autonomous custom tags.
+ ** TidyCustomTags is not disabled, and we're in HTML5 mode, which are all
+ ** requirements for valid autonomous custom tags.
+ ** @param doc The Tidy document.
+ ** @param node The node being interrogated.
+ ** @returns The status of the inquiry.
  */
 Bool TY_(nodeIsAutonomousCustomTag)( TidyDocImpl* doc, Node* node );
 
 
-/* True if any of the bits requested are set.
+/** Does the node have the indicated content model? True if any of the bits
+ ** requested are set.
+ ** @param node The node being interrogated.
+ ** @param contentModel The content model to check against.
+ ** @returns The status of the inquiry.
  */
 Bool TY_(nodeHasCM)( Node* node, uint contentModel );
 
+
+/** Does the content model of the node include block?
+ ** @param node The node being interrogated.
+ ** @returns The status of the inquiry.
+ */
 Bool TY_(nodeCMIsBlock)( Node* node );
+
+
+/** Does the content model of the node include inline?
+ ** @param node The node being interrogated.
+ ** @returns The status of the inquiry.
+ */
 Bool TY_(nodeCMIsInline)( Node* node );
+
+
+/** Does the content model of the node include empty?
+ ** @param node The node being interrogated.
+ ** @returns The status of the inquiry.
+ */
 Bool TY_(nodeCMIsEmpty)( Node* node );
 
 
-Bool TY_(nodeIsHeader)( Node* node );     /* H1, H2, ..., H6 */
+/** Is the node a header, such as H1, H2, ..., H6?
-uint TY_(nodeHeaderLevel)( Node* node );  /* 1, 2, ..., 6 */
+ ** @param node The node being interrogated.
+ ** @returns The status of the inquiry.
+ */
+Bool TY_(nodeIsHeader)( Node* node );
+
+
+/** Inquires as to the header level of the given node: 1, 2, ..., 6.
+ ** @param node The node being interrogated.
+ ** @returns The header level.
+ */
+uint TY_(nodeHeaderLevel)( Node* node );
+
 
 #define nodeIsHTML( node )       TagIsId( node, TidyTag_HTML )
 #define nodeIsHEAD( node )       TagIsId( node, TidyTag_HEAD )
@@ -242,4 +461,10 @@ uint TY_(nodeHeaderLevel)( Node* node );  /* 1, 2, ..., 6 */
 #define nodesIsFRAME( node )     TagIsId( node, TidyTag_FRAME )
 #define nodeIsTT( node )         TagIsId( node, TidyTag_TT )
 
+
+/** @} name */
+/** @} tags_h group */
+/** @} internal_api addtogroup */
+
+
 #endif /* __TAGS_H__ */

src/tidy-int.h

@@ -59,6 +59,7 @@ struct _TidyDocImpl
     TidyMessageCallback      messageCallback;
     TidyOptCallback          pOptCallback;
     TidyConfigCallback       pConfigCallback;
+    TidyConfigChangeCallback pConfigChangeCallback;
     TidyPPProgress           progressCallback;
 
     /* Parse + Repair Results */

src/tidylib.c

@@ -211,6 +211,18 @@ Bool TIDY_CALL         tidySetConfigCallback(TidyDoc tdoc, TidyConfigCallback pC
   return no;
 }
 
+Bool TIDY_CALL    tidySetConfigChangeCallback(TidyDoc tdoc, TidyConfigChangeCallback pCallback)
+{
+  TidyDocImpl* impl = tidyDocToImpl( tdoc );
+  if ( impl )
+  {
+    impl->pConfigChangeCallback = pCallback;
+    return yes;
+  }
+  return no;
+}
+
+
 
 int TIDY_CALL     tidyLoadConfig( TidyDoc tdoc, ctmbstr cfgfil )
 {