Docs

git-svn-id: https://svn.kapsi.fi/jpa/nanopb@956 e3a754e5-d11d-0410-8d38-ebb782a927b9

1 files changed, 45 insertions, 1 deletions

diff --git a/docs/reference.rst b/docs/reference.rst
index 4c8c874e..b8f9454e 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -2,6 +2,8 @@
 Nanopb: API reference
 =====================
 
+.. include :: menu.rst
+
 .. contents ::
 
 pb.h
@@ -42,7 +44,7 @@ PB_HTYPE_CALLBACK    0x30  A field with dynamic storage size, data is
 
 pb_field_t
 ----------
-Describes a single structure field with memory position in relation to others. ::
+Describes a single structure field with memory position in relation to others. The descriptions are usually autogenerated. ::
 
     typedef struct _pb_field_t pb_field_t;
     struct _pb_field_t {
@@ -63,6 +65,48 @@ Describes a single structure field with memory position in relation to others. :
 :array_size:    Maximum number of entries in an array, if it is an array type.
 :ptr:           Pointer to default value for optional fields, or to submessage description for PB_LTYPE_SUBMESSAGE.
 
+The *uint8_t* datatypes limit the maximum size of a single item to 255 bytes and arrays to 255 items. Compiler will warn "Initializer too large for type" if the limits are exceeded. The types can be changed to larger ones if necessary.
+
+pb_bytes_array_t
+----------------
+An byte array with a field for storing the length::
+
+    typedef struct {
+        size_t size;
+        uint8_t bytes[1];
+    } pb_bytes_array_t;
+
+In an actual array, the length of *bytes* may be different.
+
+pb_callback_t
+-------------
+Part of a message structure, for fields with type PB_HTYPE_CALLBACK::
+
+    typedef struct _pb_callback_t pb_callback_t;
+    struct _pb_callback_t {
+        union {
+            bool (*decode)(pb_istream_t *stream, const pb_field_t *field, void *arg);
+            bool (*encode)(pb_ostream_t *stream, const pb_field_t *field, const void *arg);
+        } funcs;
+        
+        void *arg;
+    };
+
+The *arg* is passed to the callback when calling. It can be used to store any information that the callback might need.
+
+When calling `pb_encode`_, *funcs.encode* must be set, and similarly when calling `pb_decode`_, *funcs.decode* must be set. The function pointers are stored in the same memory location but are of incompatible types.
+
+pb_wire_type_t
+--------------
+Protocol Buffers wire types. These are used with `pb_encode_tag`_. ::
+
+    typedef enum {
+        PB_WT_VARINT = 0,
+        PB_WT_64BIT  = 1,
+        PB_WT_STRING = 2,
+        PB_WT_32BIT  = 5
+    } pb_wire_type_t;
+
 pb_encode.h
 ===========