From 1621ba3a41c570abd7ec1010a57849d9e168a71b Mon Sep 17 00:00:00 2001 From: "Philipp A. Hartmann" Date: Tue, 19 Aug 2014 19:13:01 +0200 Subject: [PATCH] add Doxygen documentation for error handling customization --- build/Doxyfile | 3 +- include/rapidjson/error/en.h | 1 + include/rapidjson/error/error.h | 26 +++++++++------ include/rapidjson/rapidjson.h | 5 ++- include/rapidjson/reader.h | 56 +++++++++++++++++++++++++++++++-- 5 files changed, 77 insertions(+), 14 deletions(-) diff --git a/build/Doxyfile b/build/Doxyfile index d2a57d5..65de7e9 100644 --- a/build/Doxyfile +++ b/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 \ diff --git a/include/rapidjson/error/en.h b/include/rapidjson/error/en.h index c668ac7..d153e04 100644 --- a/include/rapidjson/error/en.h +++ b/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. diff --git a/include/rapidjson/error/error.h b/include/rapidjson/error/error.h index 3db6f16..1466044 100644 --- a/include/rapidjson/error/error.h +++ b/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. - On Windows, user can define this macro as TCHAR for supporting both +/*! \ingroup RAPIDJSON_ERRORS + 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[]. -/*! By default this conversion macro does nothing. - On Windows, user can define this macro as _T(x) for supporting both +//! Macro for converting string literial to \ref RAPIDJSON_ERROR_CHARTYPE[]. +/*! \ingroup RAPIDJSON_ERRORS + 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. - User can dynamically change locale in runtime, e.g.: +/*! \ingroup RAPIDJSON_ERRORS + 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 diff --git a/include/rapidjson/rapidjson.h b/include/rapidjson/rapidjson.h index e0c4e10..18924c1 100644 --- a/include/rapidjson/rapidjson.h +++ b/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 @@ -274,7 +277,7 @@ template 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 */ diff --git a/include/rapidjson/reader.h b/include/rapidjson/reader.h index 597e6f4..cd2c344 100644 --- a/include/rapidjson/reader.h +++ b/include/rapidjson/reader.h @@ -21,8 +21,7 @@ #ifndef RAPIDJSON_READER_H_ #define RAPIDJSON_READER_H_ -// Copyright (c) 2011 Milo Yip (miloyip@gmail.com) -// Version 0.1 +/*! \file reader.h */ #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 // 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 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];