Added tidyErrorCodeFromKey()

Added tidyGetMessageDoc()
Improved the Public API documentation.

include/tidybuffio.h

@@ -18,15 +18,18 @@
 extern "C" {
 #endif
 
-/** TidyBuffer - A chunk of memory */
+/** A TidyBuffer is chunk of memory that can be used for multiple I/O purposes
+ ** within Tidy.
+ ** @ingroup IO
+ */
 TIDY_STRUCT
 struct _TidyBuffer 
 {
     TidyAllocator* allocator;  /**< Memory allocator */
-    byte* bp;           /**< Pointer to bytes */
-    uint  size;         /**< # bytes currently in use */
-    uint  allocated;    /**< # bytes allocated */ 
-    uint  next;         /**< Offset of current input position */
+    byte* bp;                  /**< Pointer to bytes */
+    uint  size;                /**< Number of bytes currently in use */
+    uint  allocated;           /**< Number of bytes allocated */
+    uint  next;                /**< Offset of current input position */
 };
 
 /** Initialize data structure using the default allocator */

src/message.c

@@ -8,6 +8,7 @@
 
 #include "message.h"
 #include "messageobj.h"
+#include "limits.h"
 #include "tidy-int.h"
 #include "lexer.h"
 #include "streamio.h"
@@ -958,6 +959,21 @@ ctmbstr TY_(tidyErrorCodeAsKey)(uint code)
 }
 
 
+/**
+ *  Given an error code string, return its uint.
+ */
+uint TY_(tidyErrorCodeFromKey)(ctmbstr code)
+{
+    uint i = 0;
+    while (tidyErrorFilterKeysStruct[i].key) {
+        if ( strcmp(tidyErrorFilterKeysStruct[i].key, code) == 0 )
+            return tidyErrorFilterKeysStruct[i].value;
+        i++;
+    }
+    return UINT_MAX;
+}
+
+
 /**
  *  Determines the number of error codes used by Tidy.
  */

src/message.h

@@ -103,6 +103,12 @@ void TY_(ReportNumWarnings)( TidyDocImpl* doc );
  */
 ctmbstr TY_(tidyErrorCodeAsKey)(uint code);
 
+/**
+ *  Given an error code string, return the integer value of it, or UINT_MAX
+ *  as an error flag.
+ */
+uint TY_(tidyErrorCodeFromKey)(ctmbstr code);
+
 
 /**
  *  Initializes the TidyIterator to point to the first item

src/messageobj.c

@@ -264,6 +264,11 @@ void TY_(tidyMessageRelease)( TidyMessageImpl *message )
  *********************************************************************/
 
 
+TidyDocImpl* TY_(getMessageDoc)( TidyMessageImpl message )
+{
+    return message.tidyDoc;
+}
+
 ctmbstr TY_(getMessageKey)( TidyMessageImpl message )
 {
     return message.messageKey;

src/messageobj.h

@@ -1,22 +1,28 @@
 #ifndef messageobj_h
 #define messageobj_h
 
-/******************************************************************************
+/**************************************************************************//**
+ * @file messageobj.h
  * Provides an external, extensible API for message reporting.
  *
- * This module implements the `TidyMessageImpl` structure (declared in
+ * This module implements the `_TidyMessageImpl` structure (declared in
  * `tidy-int.h`) in order to abstract the reporting of reports and dialogue
  * from the rest of Tidy, and to enable a robust and extensible API for
  * message interrogation by LibTidy users.
  *
- * (c) 2017 HTACG
- * See tidy.h for the copyright notice.
+ * @author    Jim Derry
+ * @copyright Copyright (c) 2017 HTACG. See tidy.h for license.
+ * @date      Created 2017-March-10
+ *
  ******************************************************************************/
 
 #include "forward.h"
 
+/** @addtogroup internal_api */
+/** @{ */
 
-/** @name Message Creation and Releasing */
+
+/** @defgroup messageobj_instantiation Message Creation and Releasing */
 /** @{ */
 
 
@@ -51,11 +57,14 @@ TidyMessageImpl *TY_(tidyMessageCreateWithLexer)( TidyDocImpl *doc,
 void TY_(tidyMessageRelease)( TidyMessageImpl *message );
 
 
-/** @} */
-/** @name Report and Dialogue API */
+/** @} end messageobj_instantiation group */
+/** @defgroup messageobj_message_api Report and Dialogue API */
 /** @{ */
 
 
+/** get the document the message came from. */
+TidyDocImpl* TY_(getMessageDoc)( TidyMessageImpl message );
+
 /** get the message key string. */
 ctmbstr TY_(getMessageKey)( TidyMessageImpl message );
 
@@ -99,8 +108,8 @@ ctmbstr TY_(getMessageOutputDefault)( TidyMessageImpl message );
 ctmbstr TY_(getMessageOutput)( TidyMessageImpl message );
 
 
-/** @} */
-/** @name Report Arguments Interrogation API */
+/** @} end messageobj_message_api group */
+/** @defgroup messageobj_args_api Report Arguments Interrogation API */
 /** @{ */
 
 /**
@@ -160,7 +169,7 @@ int TY_(getArgValueInt)( TidyMessageImpl message, TidyMessageArgument* arg );
 double TY_(getArgValueDouble)( TidyMessageImpl message, TidyMessageArgument* arg );
 
 
-
-/** @} */
+/** @} end messageobj_args_api group */
+/** @} end internal_api group */
 
 #endif /* messageobj_h */

src/tidylib.c

@@ -701,6 +701,13 @@ Bool TIDY_CALL tidySetMessageCallback( TidyDoc tdoc, TidyMessageCallback filt )
     return no;
 }
 
+TidyDoc TIDY_CALL tidyGetMessageDoc( TidyMessage tmessage )
+{
+    TidyMessageImpl *message = tidyMessageToImpl(tmessage);
+    TidyDocImpl* doc = TY_(getMessageDoc)(*message);
+    return tidyImplToDoc(doc);
+}
+
 ctmbstr TIDY_CALL tidyGetMessageKey( TidyMessage tmessage )
 {
     TidyMessageImpl *message = tidyMessageToImpl(tmessage);
@@ -2490,6 +2497,11 @@ ctmbstr TIDY_CALL tidyErrorCodeAsKey(uint code)
     return TY_(tidyErrorCodeAsKey)( code );
 }
 
+uint TIDY_CALL tidyErrorCodeFromKey(ctmbstr code)
+{
+    return TY_(tidyErrorCodeFromKey)( code );
+}
+
 TidyIterator TIDY_CALL getErrorCodeList()
 {
     return TY_(getErrorCodeList)();