Minor documentation updates

Author: ludocode

README.md

@@ -89,7 +89,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 and/or platform-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. 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?
 

src/mpack-config.h.sample

@@ -178,6 +178,9 @@
  *
  * This automatically detects -Os with GCC/Clang. Unfortunately there
  * doesn't seem to be a macro defined for /Os under MSVC.
+ *
+ * This feature is currently experimental and may be removed in a
+ * future release.
  */
 #ifndef MPACK_OPTIMIZE_FOR_SIZE
 #ifdef __OPTIMIZE_SIZE__

src/mpack/mpack-platform.h

@@ -156,7 +156,7 @@ extern "C" {
  *   - functions declared inline only in builds optimized for speed (MPACK_INLINE_SPEED)
  *
  * MPack does not use static inline in header files; only one non-inline definition
- * of each function should exist in the final build. This reduces the binary size
+ * of each function should exist in the final build. This can reduce the binary size
  * in cases where the compiler cannot or chooses not to inline a function.
  * The addresses of functions should also compare equal across translation units
  * regardless of whether they are declared inline.
@@ -250,10 +250,10 @@ extern "C" {
  * In release mode, mpack_assert() is converted to an assurance to the compiler
  * that the expression cannot be false (via e.g. __assume() or __builtin_unreachable())
  * to improve optimization where supported. There is thus no point in "safely" handling
- * the case of this being false. Writing mpack_assert(0) rarely makes sense;
- * the compiler will throw away any code after it. If at any time an mpack_assert()
- * is not true, the behaviour is undefined. This also means the expression is
- * evaluated even in release.
+ * the case of this being false. Writing mpack_assert(0) rarely makes sense (except
+ * possibly as a default handler in a switch) since the compiler will throw away any
+ * code after it. If at any time an mpack_assert() is not true, the behaviour is
+ * undefined. This also means the expression is evaluated even in release.
  *
  * mpack_break() on the other hand is compiled to nothing in release. It is
  * used in situations where we want to highlight a programming error as early as

src/mpack/mpack-writer.h

@@ -61,7 +61,8 @@ typedef struct mpack_writer_t mpack_writer_t;
 
 /**
  * The mpack writer's flush function to flush the buffer to the output stream.
- * It should flag an appropriate error on the writer if flushing fails.
+ * It should flag an appropriate error on the writer if flushing fails (usually
+ * mpack_error_io.)
  *
  * The specified context for callbacks is at writer->context.
  */
@@ -169,7 +170,8 @@ void mpack_writer_init_file(mpack_writer_t* writer, const char* filename);
  * @def mpack_writer_init_stack(writer, flush, context)
  * @hideinitializer
  *
- * Initializes an mpack writer using stack space.
+ * Initializes an mpack writer using stack space as a buffer. A flush function
+ * should be added to the writer to flush the buffer.
  */
 
 #define mpack_writer_init_stack_line_ex(line, writer) \