Check for empty message type before incrementing required_field_index.

[apps/agl-service-can-low-level.git] / docs / reference.rst

diff --git a/docs/reference.rst b/docs/reference.rst
index 6094e13..3388488 100644 (file)
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -11,9 +11,13 @@ Nanopb: API reference
 
 Compilation options
 ===================
-The following options can be specified using -D switch given to the C compiler
-when compiling the nanopb library and applications using it. You must have the
-same settings for the nanopb library and all code that includes pb.h.
+The following options can be specified in one of two ways:
+
+1. Using the -D switch on the C compiler command line.
+2. By #defining them at the top of pb.h.
+
+You must have the same settings for the nanopb library and all code that
+includes pb.h.
 
 ============================  ================================================
 __BIG_ENDIAN__                 Set this if your platform stores integers and
@@ -277,13 +281,38 @@ Protocol Buffers wire types. These are used with `pb_encode_tag`_. ::
         PB_WT_32BIT  = 5
     } pb_wire_type_t;
 
+PB_GET_ERROR
+------------
+Get the current error message from a stream, or a placeholder string if
+there is no error message::
+
+    #define PB_GET_ERROR(stream) (string expression)
+
+This should be used for printing errors, for example::
 
+    if (!pb_decode(...))
+    {
+        printf("Decode failed: %s\n", PB_GET_ERROR(stream));
+    }
 
+The macro only returns pointers to constant strings (in code memory),
+so that there is no need to release the returned pointer.
 
+PB_RETURN_ERROR
+---------------
+Set the error message and return false::
 
+    #define PB_RETURN_ERROR(stream,msg) (sets error and returns false)
 
+This should be used to handle error conditions inside nanopb functions
+and user callback functions::
 
+    if (error_condition)
+    {
+        PB_RETURN_ERROR(stream, "something went wrong");
+    }
 
+The *msg* parameter must be a constant string.