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
};