Improve comments and docs (#319, #710, #999)
diff --git a/docs/concepts.md b/docs/concepts.md
index 6130bc1..33f610c 100644
--- a/docs/concepts.md
+++ b/docs/concepts.md
@@ -161,7 +161,7 @@
 
 1)  Strings, bytes and repeated fields of any type map to callback
     functions by default.
-2)  If there is a special option `(nanopb).max_size` specified in the
+2)  If there is a special option `(nanopb).max_length` or `(nanopb).max_size` specified in the
     .proto file, string maps to null-terminated char array and bytes map
     to a structure containing a char array and a size field.
 3)  If `(nanopb).fixed_length` is set to `true` and
diff --git a/docs/reference.md b/docs/reference.md
index 720e679..890be37 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -170,6 +170,64 @@
 * `--strip-path`: Remove relative path from generated `#include` directives.
 * `--cpp-descriptors`: Generate extra convenience definitions for use from C++
 
+For a full list of generator command line options, use `nanopb_generator.py --help`:
+
+    Usage: nanopb_generator.py [options] file.pb ...
+
+    Options:
+    -h, --help            show this help message and exit
+    -V, --version         Show version info and exit (add -v for protoc version
+                            info)
+    -x FILE               Exclude file from generated #include list.
+    -e EXTENSION, --extension=EXTENSION
+                            Set extension to use instead of '.pb' for generated
+                            files. [default: .pb]
+    -H EXTENSION, --header-extension=EXTENSION
+                            Set extension to use for generated header files.
+                            [default: .h]
+    -S EXTENSION, --source-extension=EXTENSION
+                            Set extension to use for generated source files.
+                            [default: .c]
+    -f FILE, --options-file=FILE
+                            Set name of a separate generator options file.
+    -I DIR, --options-path=DIR, --proto-path=DIR
+                            Search path for .options and .proto files. Also
+                            determines relative paths for output directory
+                            structure.
+    --error-on-unmatched  Stop generation if there are unmatched fields in
+                            options file
+    --no-error-on-unmatched
+                            Continue generation if there are unmatched fields in
+                            options file (default)
+    -D OUTPUTDIR, --output-dir=OUTPUTDIR
+                            Output directory of .pb.h and .pb.c files
+    -Q FORMAT, --generated-include-format=FORMAT
+                            Set format string to use for including other .pb.h
+                            files. Value can be 'quote', 'bracket' or a format
+                            string. [default: #include "%s"]
+    -L FORMAT, --library-include-format=FORMAT
+                            Set format string to use for including the nanopb pb.h
+                            header. Value can be 'quote', 'bracket' or a format
+                            string. [default: #include <%s>]
+    --strip-path          Strip directory path from #included .pb.h file name
+    --no-strip-path       Opposite of --strip-path (default since 0.4.0)
+    --cpp-descriptors     Generate C++ descriptors to lookup by type (e.g.
+                            pb_field_t for a message)
+    -T, --no-timestamp    Don't add timestamp to .pb.h and .pb.c preambles
+                            (default since 0.4.0)
+    -t, --timestamp       Add timestamp to .pb.h and .pb.c preambles
+    -q, --quiet           Don't print anything except errors.
+    -v, --verbose         Print more information.
+    -s OPTION:VALUE       Set generator option (max_size, max_count etc.).
+    --protoc-opt=OPTION   Pass an option to protoc when compiling .proto files
+    --protoc-insertion-points
+                            Include insertion point comments in output for use by
+                            custom protoc plugins
+    -C, --c-style         Use C naming convention.
+
+    Compile file.pb from file.proto by: 'protoc -ofile.pb file.proto'. Output will
+    be written to file.pb.h and file.pb.c.
+
 ## pb.h
 
 ### pb_byte_t
diff --git a/generator/proto/nanopb.proto b/generator/proto/nanopb.proto
index d45da24..18164e6 100644
--- a/generator/proto/nanopb.proto
+++ b/generator/proto/nanopb.proto
@@ -1,9 +1,15 @@
-// Custom options for defining:
-// - Maximum size of string/bytes
-// - Maximum number of elements in array
+// This file contains definitions of custom options used to control the
+// code generator in nanopb protocol buffers library.
 //
-// These are used by nanopb to generate statically allocable structures
-// for memory-limited environments.
+// Most commonly used options are max_count and max_size, which allow
+// the generator to allocate static arrays for repeated and string fields.
+//
+// There are three ways to use these options:
+//  1. Use a separate <protofile>.options file
+//  2. Use command line switches to nanopb_generator.py
+//  3. Use [(nanopb).option = value] in your <protofile>.proto file
+//
+// For detailed documentation, refer to "Generator options" in docs/reference.md
 
 syntax = "proto2";
 import "google/protobuf/descriptor.proto";
diff --git a/pb_decode.h b/pb_decode.h
index ae1d3cc..3f392b2 100644
--- a/pb_decode.h
+++ b/pb_decode.h
@@ -37,10 +37,21 @@
     bool (*callback)(pb_istream_t *stream, pb_byte_t *buf, size_t count);
 #endif
 
-    void *state; /* Free field for use by callback implementation */
+    /* state is a free field for use of the callback function defined above.
+     * Note that when pb_istream_from_buffer() is used, it reserves this field
+     * for its own use.
+     */
+    void *state;
+
+    /* Maximum number of bytes left in this stream. Callback can report
+     * EOF before this limit is reached. Setting a limit is recommended
+     * when decoding directly from file or network streams to avoid
+     * denial-of-service by excessively long messages.
+     */
     size_t bytes_left;
     
 #ifndef PB_NO_ERRMSG
+    /* Pointer to constant (ROM) string when decoding function returns error */
     const char *errmsg;
 #endif
 };
diff --git a/pb_encode.h b/pb_encode.h
index 8913683..6dc089d 100644
--- a/pb_encode.h
+++ b/pb_encode.h
@@ -37,11 +37,21 @@
 #else
     bool (*callback)(pb_ostream_t *stream, const pb_byte_t *buf, size_t count);
 #endif
-    void *state;          /* Free field for use by callback implementation. */
-    size_t max_size;      /* Limit number of output bytes written (or use SIZE_MAX). */
-    size_t bytes_written; /* Number of bytes written so far. */
+
+    /* state is a free field for use of the callback function defined above.
+     * Note that when pb_ostream_from_buffer() is used, it reserves this field
+     * for its own use.
+     */
+    void *state;
+
+    /* Limit number of output bytes written. Can be set to SIZE_MAX. */
+    size_t max_size;
+
+    /* Number of bytes written so far. */
+    size_t bytes_written;
     
 #ifndef PB_NO_ERRMSG
+    /* Pointer to constant (ROM) string when decoding function returns error */
     const char *errmsg;
 #endif
 };