gvsafronov/rapidjson
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

rapidjson.h: add some file-level doxygen documentation

Browse Source 
Although not yet complete, the rapidjson.h header contains most of
the customisation macro definitions.  These should be documented via
Doxygen as well.  This requires adding file-level documentation.

Some parts are excluded via `@cond` to avoid cluttering the documentation
with internals too much.

Secondly, a brief description is added to the 'rapidjson' namespace to
include the namespace-level elements (enums, typedefs, functions) to
the generated documentation.
This commit is contained in:
Philipp A. Hartmann 2014-07-05 17:09:35 +02:00
parent 252e282dc6
commit 5174fe4f65
1 changed files with 20 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
include/rapidjson/rapidjson.h
View File

@ -4,6 +4,12 @@
// Copyright (c) 2011 Milo Yip (miloyip@gmail.com) // Copyright (c) 2011 Milo Yip (miloyip@gmail.com)
// Version 0.1 // Version 0.1
/*!\file rapidjson.h
\brief common definitions and configuration
\todo Complete Doxygen documentation for configure macros.
*/
#include <cstdlib> // malloc(), realloc(), free() #include <cstdlib> // malloc(), realloc(), free()
#include <cstring> // memcpy() #include <cstring> // memcpy()
@ -14,6 +20,7 @@
// (U)INT64_C constant macros. // (U)INT64_C constant macros.
// If user have their own definition, can define RAPIDJSON_NO_INT64DEFINE to disable this. // If user have their own definition, can define RAPIDJSON_NO_INT64DEFINE to disable this.
#ifndef RAPIDJSON_NO_INT64DEFINE #ifndef RAPIDJSON_NO_INT64DEFINE
//!@cond RAPIDJSON_HIDDEN_FROM_DOXYGEN
#ifndef __STDC_CONSTANT_MACROS #ifndef __STDC_CONSTANT_MACROS
# define __STDC_CONSTANT_MACROS 1 // required by C++ standard # define __STDC_CONSTANT_MACROS 1 // required by C++ standard
#endif #endif
@ -25,6 +32,7 @@
#include <stdint.h> #include <stdint.h>
#include <inttypes.h> #include <inttypes.h>
#endif #endif
//!@endcond
#endif // RAPIDJSON_NO_INT64TYPEDEF #endif // RAPIDJSON_NO_INT64TYPEDEF
/////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
@ -46,7 +54,7 @@
//! Endianness of the machine. //! Endianness of the machine.
/*! GCC provided macro for detecting endianness of the target machine. But other /*! GCC provided macro for detecting endianness of the target machine. But other
compilers may not have this. User can define RAPIDJSON_ENDIAN to either compilers may not have this. User can define RAPIDJSON_ENDIAN to either
RAPIDJSON_LITTLEENDIAN or RAPIDJSON_BIGENDIAN. \ref RAPIDJSON_LITTLEENDIAN or \ref RAPIDJSON_BIGENDIAN.
*/ */
#ifndef RAPIDJSON_ENDIAN #ifndef RAPIDJSON_ENDIAN
#ifdef __BYTE_ORDER__ #ifdef __BYTE_ORDER__
@ -115,7 +123,9 @@ typedef unsigned SizeType;
// Adopt from boost // Adopt from boost
#ifndef RAPIDJSON_STATIC_ASSERT #ifndef RAPIDJSON_STATIC_ASSERT
//!@cond RAPIDJSON_HIDDEN_FROM_DOXYGEN
namespace rapidjson { namespace rapidjson {
template <bool x> struct STATIC_ASSERTION_FAILURE; template <bool x> struct STATIC_ASSERTION_FAILURE;
template <> struct STATIC_ASSERTION_FAILURE<true> { enum { value = 1 }; }; template <> struct STATIC_ASSERTION_FAILURE<true> { enum { value = 1 }; };
template<int x> struct StaticAssertTest {}; template<int x> struct StaticAssertTest {};
@ -130,7 +140,13 @@ template<int x> struct StaticAssertTest {};
#else #else
#define RAPIDJSON_STATIC_ASSERT_UNUSED_ATTRIBUTE #define RAPIDJSON_STATIC_ASSERT_UNUSED_ATTRIBUTE
#endif #endif
//!@endcond
/*! \def RAPIDJSON_STATIC_ASSERT
\brief (internal) macro to check for conditions at compile-time
\param x compile-time condition
\hideinitializer
*/
#define RAPIDJSON_STATIC_ASSERT(x) typedef ::rapidjson::StaticAssertTest<\ #define RAPIDJSON_STATIC_ASSERT(x) typedef ::rapidjson::StaticAssertTest<\
sizeof(::rapidjson::STATIC_ASSERTION_FAILURE<bool(x) >)>\ sizeof(::rapidjson::STATIC_ASSERTION_FAILURE<bool(x) >)>\
RAPIDJSON_JOIN(StaticAssertTypedef, __LINE__) RAPIDJSON_STATIC_ASSERT_UNUSED_ATTRIBUTE RAPIDJSON_JOIN(StaticAssertTypedef, __LINE__) RAPIDJSON_STATIC_ASSERT_UNUSED_ATTRIBUTE
@ -139,9 +155,11 @@ template<int x> struct StaticAssertTest {};
/////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
// Helpers // Helpers
//!@cond RAPIDJSON_HIDDEN_FROM_DOXYGEN
#define RAPIDJSON_MULTILINEMACRO_BEGIN do { #define RAPIDJSON_MULTILINEMACRO_BEGIN do {
#define RAPIDJSON_MULTILINEMACRO_END \ #define RAPIDJSON_MULTILINEMACRO_END \
} while((void)0, 0) } while((void)0, 0)
//!@endcond
/////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
// Allocators and Encodings // Allocators and Encodings
@ -149,6 +167,7 @@ template<int x> struct StaticAssertTest {};
#include "allocators.h" #include "allocators.h"
#include "encodings.h" #include "encodings.h"
//! main RapidJSON namespace
namespace rapidjson { namespace rapidjson {
/////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////