Various documentation updates

Author: ludocode

README.md

@@ -8,7 +8,7 @@ MPack is a C implementation of an encoder and decoder for the [MessagePack](http
  * [Extensively documented](http://ludocode.github.io/mpack/)
  * [Extremely fast](https://github.com/ludocode/schemaless-benchmarks#speed---desktop-pc)
 
-The core of MPack contains a buffered reader and writer with a custom callback to fill or flush the buffer. Helper functions can be enabled to read values of expected type, to work with files, to allocate strings automatically, to check UTF-8 encoding, and more. The MPack featureset can be configured at compile-time to set which features, components and debug checks are compiled, and what dependencies are available.
+The core of MPack contains a buffered reader and writer, and a tree-style parser that decodes into a tree of dynamically typed nodes. Helper functions can be enabled to read values of expected type, to work with files, to allocate strings automatically, to check UTF-8 encoding, and more. The MPack featureset can be configured at compile-time to set which features, components and debug checks are compiled, and what dependencies are available.
 
 The MPack code is small enough to be embedded directly into your codebase. The easiest way to use it is to download the [amalgamation package](https://github.com/ludocode/mpack/releases) and insert the source files directly into your project. Copy `mpack.h` and `mpack.c` into to your codebase, and copy `mpack-config.h.sample` as `mpack-config.h`. You can use the defaults or edit it if you'd like to customize the MPack featureset.
 
@@ -53,6 +53,8 @@ if (mpack_tree_destroy(tree) != mpack_ok) {
 
 Note that no additional error handling is needed in the above code. If the file is missing or corrupt, if map keys are missing or if nodes are not in the expected types, special "nil" nodes and false/zero values are returned and the tree is placed in an error state. An error check is only needed before using the data.
 
+The above example decodes into allocated pages of nodes. A fixed node pool can be provided to the parser instead in memory-constrained environments. For maximum performance and minimal memory usage, the [Expect API](docs/expect.md) can be used to parse data of a predefined schema.
+
 ## The Write API
 
 The MPack Write API encodes structured data to MessagePack.
@@ -112,7 +114,7 @@ MPack is rich in features while maintaining very high performance and a small co
 
 A larger feature comparison table is available [here](docs/features.md) which includes descriptions of the various entries in the table.
 
-This [benchmarking suite](https://github.com/ludocode/schemaless-benchmarks) compares the performance of MPack to other implementations of schemaless serialization formats. MPack outperforms all other MessagePack implementations, and in some tests MPack is several times faster than [RapidJSON](https://github.com/miloyip/rapidjson) for equivalent data.
+[This benchmarking suite](https://github.com/ludocode/schemaless-benchmarks) compares the performance of MPack to other implementations of schemaless serialization formats. MPack outperforms all JSON and MessagePack libraries, and in some tests MPack is several times faster than [RapidJSON](https://github.com/miloyip/rapidjson) for equivalent data.
 
 ## Why Not Just Use JSON?
 
@@ -126,7 +128,7 @@ Conceptually, MessagePack stores data similarly to JSON: they are both composed
 
 - Binary data is not supported by JSON at all. Small binary blobs such as icons and thumbnails need to be Base64 encoded or passed out-of-band.
 
-The above issues greatly increase the complexity of the decoder. Full-featured JSON decoders are quite large, and minimal decoders tend to leave out such features as string unescaping and float parsing, instead leaving these up to the user or platform. This can lead to hard-to-find platform-specific and locale-specific bugs. This also significantly decreases performance, making JSON unattractive for use in applications such as mobile games.
+The above issues greatly increase the complexity of the decoder. Full-featured JSON decoders are quite large, and minimal decoders tend to leave out such features as string unescaping and float parsing, instead leaving these up to the user or platform. This can lead to hard-to-find platform-specific and locale-specific bugs, as well as a greater potential for security vulnerabilites. This also significantly decreases performance, making JSON unattractive for use in applications such as mobile games.
 
 While the space inefficiencies of JSON can be partially mitigated through minification and compression, the performance inefficiencies cannot. More importantly, if you are minifying and compressing the data, then why use a human-readable format in the first place?
 

docs/doxygen-layout.xml

@@ -11,7 +11,7 @@
 
   <!-- Layout definition for a group page -->
   <group>
-    <briefdescription visible="yes"/>
+    <detaileddescription visible="yes" title="Description"/>
     <groupgraph visible="$GROUP_GRAPHS"/>
     <memberdecl>
       <nestedgroups visible="yes" title=""/>
@@ -34,7 +34,6 @@
       <friends title=""/>
       <membergroups visible="yes"/>
     </memberdecl>
-    <detaileddescription title=""/>
     <memberdef>
       <pagedocs/>
       <inlineclasses title=""/>

docs/doxygen-mpack-css.css

@@ -2,8 +2,11 @@ table.doxtable th {
 	background-color: #e0e7ff;
 	color: #000;
 }
-.textblock code {
-    background-color: #f3f3f3;
+.textblock code,
+.contents p code, .contents p em,
+.contents dd code, .contents dd em {
+    padding: 1pt 2pt 1pt 2pt;
+    background-color: #f5f5f5;
 }
 .textblock li {
     margin: 3pt 0 3pt 0;

docs/expect.md

@@ -3,7 +3,7 @@
 
 The Expect API is used to imperatively parse data of a fixed (hardcoded) schema. It is most useful when parsing very large MessagePack files, parsing in memory-constrained environments, or generating parsing code from a schema. The API is similar to [CMP](https://github.com/camgunz/cmp), but has many helper functions especially for map keys and expected value ranges. Some of these will be covered below.
 
-If you are not writing code for an embedded device or generating parsing code from a schema, you should not follow this guide. You should most likely be using the Node API instead.
+*If you are not writing code for an embedded device or generating parsing code from a schema, you should not follow this guide. You should most likely be using the Node API instead.*
 
 ## A simple example
 

src/mpack-config.h.sample

@@ -15,7 +15,6 @@
  *
  * Copy @c mpack-config.h.sample to @c mpack-config.h somewhere in your
  * project's include tree and, optionally, edit it to suit your setup.
- *
  * In almost all cases you can leave this file with the default config.
  *
  * You can also override the default configuration by pre-defining options
@@ -109,34 +108,34 @@
 /**
  * @def MPACK_MALLOC
  *
- * Defines the memory allocation function used by mpack. This is used by
+ * Defines the memory allocation function used by MPack. This is used by
  * helpers for automatically allocating data the correct size, and for
  * debugging functions. If this macro is undefined, the allocation helpers
  * will not be compiled.
  *
- * The default is malloc() if MPACK_STDLIB is enabled.
+ * The default is malloc() if @ref MPACK_STDLIB is enabled.
  */
 /**
  * @def MPACK_FREE
  *
- * Defines the memory free function used by mpack. This is used by helpers
+ * Defines the memory free function used by MPack. This is used by helpers
  * for automatically allocating data the correct size. If this macro is
  * undefined, the allocation helpers will not be compiled.
  *
- * The default is free() if MPACK_MALLOC has not been customized and
- * MPACK_STDLIB is enabled.
+ * The default is free() if @ref MPACK_MALLOC has not been customized and
+ * @ref MPACK_STDLIB is enabled.
  */
 /**
  * @def MPACK_REALLOC
  *
- * Defines the realloc function used by mpack. It is used by growable
+ * Defines the realloc function used by MPack. It is used by growable
  * buffers to resize more efficiently.
  *
- * The default is realloc() if MPACK_MALLOC has not been customized and
- * MPACK_STDLIB is enabled.
+ * The default is realloc() if @ref MPACK_MALLOC has not been customized and
+ * @ref MPACK_STDLIB is enabled.
  *
- * This is optional, even when MPACK_MALLOC is used. If MPACK_MALLOC is
- * set and MPACK_REALLOC is not, MPACK_MALLOC is used with a simple copy
+ * This is optional, even when @ref MPACK_MALLOC is used. If @ref MPACK_MALLOC is
+ * set and @ref MPACK_REALLOC is not, @ref MPACK_MALLOC is used with a simple copy
  * to grow buffers.
  */
 #if defined(MPACK_STDLIB) && !defined(MPACK_MALLOC)
@@ -158,13 +157,13 @@
  * @def MPACK_DEBUG
  *
  * Enables debug features. You may want to wrap this around your
- * own debug preprocs. By default, they are enabled if DEBUG or _DEBUG
+ * own debug preprocs. By default, this is enabled if @c DEBUG or @c _DEBUG
  * are defined.
  *
- * Note that MPACK_DEBUG cannot be defined differently for different
+ * Note that @ref MPACK_DEBUG cannot be defined differently for different
  * source files because it affects layout of structs defined in header
  * files. Your entire project must be compiled with the same value of
- * MPACK_DEBUG. (This is why NDEBUG is not used.)
+ * @ref MPACK_DEBUG. (This is why @c NDEBUG is not used.)
  */
 #if !defined(MPACK_DEBUG) && (defined(DEBUG) || defined(_DEBUG))
 #define MPACK_DEBUG 1
@@ -179,7 +178,7 @@
  * on embedded devices. If this is disabled, string functions such as
  * mpack_error_to_string() and mpack_type_to_string() return an empty string.
  *
- * This is on by default if MPACK_STRINGS is not defined.
+ * This is on by default if it is not defined.
  */
 #if !defined(MPACK_STRINGS)
 #define MPACK_STRINGS 1
@@ -189,10 +188,12 @@
  * Set this to 1 to implement a custom mpack_assert_fail() function. This
  * function must not return, and must have the following signature:
  *
- *     void mpack_assert_fail(const char* message)
+ * @code{.c}
+ * void mpack_assert_fail(const char* message)
+ * @endcode
  *
- * Asserts are only used when MPACK_DEBUG is enabled, and can be triggered
- * by bugs in mpack or bugs due to incorrect usage of mpack.
+ * Asserts are only used when @ref MPACK_DEBUG is enabled, and can be triggered
+ * by bugs in MPack or bugs due to incorrect usage of MPack.
  */
 #ifndef MPACK_CUSTOM_ASSERT
 #define MPACK_CUSTOM_ASSERT 0
@@ -223,7 +224,7 @@
  * Note that without write tracking enabled, it is possible for buggy code
  * to emit invalid MessagePack without flagging an error by writing the wrong
  * number of elements or bytes in a compound type. With tracking enabled,
- * MPACK will catch such errors and break on the offending line of code.
+ * MPack will catch such errors and break on the offending line of code.
  *
  * This is enabled by default in debug builds (provided a malloc() is
  * available.)
@@ -310,7 +311,7 @@
 #endif
 
 /**
- * The maximum depth for the node parser if MPACK_MALLOC is not available.
+ * The maximum depth for the node parser if @ref MPACK_MALLOC is not available.
  * The parsing stack is placed on the call stack.
  */
 #ifndef MPACK_NODE_MAX_DEPTH_WITHOUT_MALLOC

src/mpack/mpack-common.h

@@ -344,15 +344,11 @@ MPACK_INLINE bool mpack_tag_equal(mpack_tag_t left, mpack_tag_t right) {
 
 /*
  * Helpers to perform unaligned network-endian loads and stores
- * at arbitrary addresses.
+ * at arbitrary addresses. Byte-swapping builtins are used if they
+ * are available and if they improve performance.
  *
  * These will remain available in the public API so feel free to
  * use them for other purposes, but they are undocumented.
- *
- * The bswap builtins are used when needed and available. With
- * GCC 5.2 they appear to give better performance and smaller
- * code size on little-endian ARM while compiling to the same
- * assembly as the bit-shifting code on x86_64.
  */
 
 MPACK_INLINE uint8_t mpack_load_u8(const char* p) {