add Doxygen documentation for error handling customization

build/Doxyfile

@@ -764,7 +764,8 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ./include/ \
+INPUT                  = ./include/rapidjson/rapidjson.h \
+                         ./include/ \
                          ./readme.md \
                          ./doc/features.md \
                          ./doc/tutorial.md \

include/rapidjson/error/en.h

@@ -27,6 +27,7 @@ namespace rapidjson {
 
 //! Maps error code of parsing into error message.
 /*!
+    \ingroup RAPIDJSON_ERRORS
     \param parseErrorCode Error code obtained in parsing.
     \return the error message.
     \note User can make a copy of this function for localization.

include/rapidjson/error/error.h

@@ -21,12 +21,17 @@
 #ifndef RAPIDJSON_ERROR_ERROR_H__
 #define RAPIDJSON_ERROR_ERROR_H__
 
+/*! \file error.h */
+
+/*! \defgroup RAPIDJSON_ERRORS RapidJSON error handling */
+
 ///////////////////////////////////////////////////////////////////////////////
 // RAPIDJSON_ERROR_CHARTYPE
 
 //! Character type of error messages.
-/*! The default charater type is char.
+/*! \ingroup RAPIDJSON_ERRORS
-    On Windows, user can define this macro as TCHAR for supporting both
+    The default character type is \c char.
+    On Windows, user can define this macro as \c TCHAR for supporting both
     unicode/non-unicode settings.
 */
 #ifndef RAPIDJSON_ERROR_CHARTYPE
@@ -36,9 +41,10 @@
 ///////////////////////////////////////////////////////////////////////////////
 // RAPIDJSON_ERROR_STRING
 
-//! Macro for converting string literial to RAPIDJSON_ERROR_CHARTYPE[].
+//! Macro for converting string literial to \ref RAPIDJSON_ERROR_CHARTYPE[].
-/*! By default this conversion macro does nothing.
+/*! \ingroup RAPIDJSON_ERRORS
-    On Windows, user can define this macro as _T(x) for supporting both 
+    By default this conversion macro does nothing.
+    On Windows, user can define this macro as \c _T(x) for supporting both
     unicode/non-unicode settings.
 */
 #ifndef RAPIDJSON_ERROR_STRING
@@ -51,7 +57,8 @@ namespace rapidjson {
 // ParseErrorCode
 
 //! Error code of parsing.
-/*! \see GenericReader::Parse, GenericReader::GetParseErrorCode
+/*! \ingroup RAPIDJSON_ERRORS
+    \see GenericReader::Parse, GenericReader::GetParseErrorCode
 */
 enum ParseErrorCode {
     kParseErrorNone = 0,                        //!< No error.
@@ -83,6 +90,7 @@ enum ParseErrorCode {
 
 //! Result of parsing (wraps ParseErrorCode)
 /*!
+    \ingroup RAPIDJSON_ERRORS
     \code
         Document doc;
         ParseResult ok = doc.Parse("[42]");
@@ -126,15 +134,15 @@ private:
 };
 
 //! Function pointer type of GetParseError().
-/*! This is the prototype for GetParseError_X(), where X is a locale.
+/*! \ingroup RAPIDJSON_ERRORS
-    User can dynamically change locale in runtime, e.g.:
 
+    This is the prototype for \c GetParseError_X(), where \c X is a locale.
+    User can dynamically change locale in runtime, e.g.:
 \code
     GetParseErrorFunc GetParseError = GetParseError_En; // or whatever
     const RAPIDJSON_ERROR_CHARTYPE* s = GetParseError(document.GetParseErrorCode());
 \endcode
 */
-
 typedef const RAPIDJSON_ERROR_CHARTYPE* (*GetParseErrorFunc)(ParseErrorCode);
 
 } // namespace rapidjson

include/rapidjson/rapidjson.h

@@ -243,6 +243,9 @@ typedef unsigned SizeType;
 /*! \ingroup RAPIDJSON_CONFIG
     By default, rapidjson uses C \c assert() for internal assertions.
     User can override it by defining RAPIDJSON_ASSERT(x) macro.
+
+    \note Parsing errors are handled and can be customized by the
+          \ref RAPIDJSON_ERRORS APIs.
 */
 #ifndef RAPIDJSON_ASSERT
 #include <cassert>
@@ -274,7 +277,7 @@ template<int x> struct StaticAssertTest {};
 //!@endcond
 
 /*! \def RAPIDJSON_STATIC_ASSERT
-    \brief (internal) macro to check for conditions at compile-time
+    \brief (Internal) macro to check for conditions at compile-time
     \param x compile-time condition
     \hideinitializer
  */

include/rapidjson/reader.h

@@ -21,8 +21,7 @@
 #ifndef RAPIDJSON_READER_H_
 #define RAPIDJSON_READER_H_
 
-// Copyright (c) 2011 Milo Yip (miloyip@gmail.com)
+/*! \file reader.h */
-// Version 0.1
 
 #include "rapidjson.h"
 #include "encodings.h"
@@ -46,6 +45,7 @@ RAPIDJSON_DIAG_OFF(4127)  // conditional expression is constant
 RAPIDJSON_DIAG_OFF(4702)  // unreachable code
 #endif
 
+//!@cond RAPIDJSON_HIDDEN_FROM_DOXYGEN
 #define RAPIDJSON_NOTHING /* deliberately empty */
 #ifndef RAPIDJSON_PARSE_ERROR_EARLY_RETURN
 #define RAPIDJSON_PARSE_ERROR_EARLY_RETURN(value) \
@@ -55,15 +55,57 @@ RAPIDJSON_DIAG_OFF(4702)  // unreachable code
 #endif
 #define RAPIDJSON_PARSE_ERROR_EARLY_RETURN_VOID \
     RAPIDJSON_PARSE_ERROR_EARLY_RETURN(RAPIDJSON_NOTHING)
+//!@endcond
 
+/*! \def RAPIDJSON_PARSE_ERROR_NORETURN
+    \ingroup RAPIDJSON_ERRORS
+    \brief Macro to indicate a parse error.
+    \param parseErrorCode \ref rapidjson::ParseErrorCode of the error
+    \param offset  position of the error in JSON input (\c size_t)
+
+    This macros can be used as a customization point for the internal
+    error handling mechanism of RapidJSON.
+
+    A common usage model is to throw an exception instead of requiring the
+    caller to explicitly check the \ref rapidjson::GenericReader::Parse's
+    return value:
+
+    \code
+    #define RAPIDJSON_PARSE_ERROR_NORETURN(parseErrorCode,offset) \
+       throw ParseException(parseErrorCode, #parseErrorCode, offset)
+
+    #include <stdexcept>               // std::runtime_error
+    #include "rapidjson/error/error.h" // rapidjson::ParseResult
+
+    struct ParseException : std::runtime_error, rapidjson::ParseResult {
+      ParseException(rapidjson::ParseErrorCode code, const char* msg, size_t offset)
+        : std::runtime_error(msg), ParseResult(code, offset) {}
+    };
+
+    #include "rapidjson/reader.h"
+    \endcode
+
+    \see RAPIDJSON_PARSE_ERROR, rapidjson::GenericReader::Parse
+ */
 #ifndef RAPIDJSON_PARSE_ERROR_NORETURN
 #define RAPIDJSON_PARSE_ERROR_NORETURN(parseErrorCode, offset) \
     RAPIDJSON_MULTILINEMACRO_BEGIN \
     RAPIDJSON_ASSERT(!HasParseError()); /* Error can only be assigned once */ \
-    parseResult_.Set(parseErrorCode,offset); \
+    SetParseError(parseErrorCode, offset); \
     RAPIDJSON_MULTILINEMACRO_END
 #endif
 
+/*! \def RAPIDJSON_PARSE_ERROR
+    \ingroup RAPIDJSON_ERRORS
+    \brief (Internal) macro to indicate and handle a parse error.
+    \param parseErrorCode \ref rapidjson::ParseErrorCode of the error
+    \param offset  position of the error in JSON input (\c size_t)
+
+    Invokes RAPIDJSON_PARSE_ERROR_NORETURN and stops the parsing.
+
+    \see RAPIDJSON_PARSE_ERROR_NORETURN
+    \hideinitializer
+ */
 #ifndef RAPIDJSON_PARSE_ERROR
 #define RAPIDJSON_PARSE_ERROR(parseErrorCode, offset) \
     RAPIDJSON_MULTILINEMACRO_BEGIN \
@@ -421,6 +463,9 @@ public:
     //! Get the position of last parsing error in input, 0 otherwise.
     size_t GetErrorOffset() const { return parseResult_.Offset(); }
 
+protected:
+    void SetParseError(ParseErrorCode code, size_t offset) { parseResult_.Set(code, offset); }
+
 private:
     // Prohibit copy constructor & assignment operator.
     GenericReader(const GenericReader&);
@@ -632,6 +677,7 @@ private:
     // This function handles the prefix/suffix double quotes, escaping, and optional encoding validation.
     template<unsigned parseFlags, typename SEncoding, typename TEncoding, typename InputStream, typename OutputStream>
     RAPIDJSON_FORCEINLINE void ParseStringToStream(InputStream& is, OutputStream& os) {
+//!@cond RAPIDJSON_HIDDEN_FROM_DOXYGEN
 #define Z16 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
         static const char escape[256] = {
             Z16, Z16, 0, 0,'\"', 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,'/', 
@@ -641,6 +687,7 @@ private:
             Z16, Z16, Z16, Z16, Z16, Z16, Z16, Z16
         };
 #undef Z16
+//!@endcond
 
         RAPIDJSON_ASSERT(is.Peek() == '\"');
         is.Take();  // Skip '\"'
@@ -933,6 +980,8 @@ private:
     };
 
     RAPIDJSON_FORCEINLINE Token Tokenize(Ch c) {
+
+//!@cond RAPIDJSON_HIDDEN_FROM_DOXYGEN
 #define N NumberToken
 #define N16 N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N
         // Maps from ASCII to Token
@@ -949,6 +998,7 @@ private:
         };
 #undef N
 #undef N16
+//!@endcond
         
         if (sizeof(Ch) == 1 || unsigned(c) < 256)
             return (Token)tokenMap[(unsigned char)c];