More unittests

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

diff --git a/docs/index.rst b/docs/index.rst
index 5a5cc82..7658036 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,6 +2,8 @@
 Nanopb: Protocol Buffers with small code size
 =============================================
 
+.. include :: menu.rst
+
 Nanopb is an ANSI-C library for encoding and decoding messages in Google's `Protocol Buffers`__ format with minimal requirements for RAM and code space.
 It is primarily suitable for 32-bit microcontrollers.
 
@@ -40,10 +42,13 @@ Features and limitations
 
 **Limitations**
 
-#) User must provide callbacks when decoding arrays or strings without maximum size.
+#) User must provide callbacks when decoding arrays or strings without maximum size. Malloc support could be added as a separate module.
 #) Some speed has been sacrificed for code size. For example varint calculations are always done in 64 bits.
 #) Encoding is focused on writing to streams. For memory buffers only it could be made more efficient.
 #) The deprecated Protocol Buffers feature called "groups" is not supported.
+#) Fields in the generated structs are ordered by the tag number, instead of the natural ordering in .proto file.
+#) Unknown fields are not preserved when decoding and re-encoding a message.
+#) Numeric arrays are always encoded as packed, even if not marked as packed in .proto. This causes incompatibility with decoders that do not support packed format.
 
 Getting started
 ===============
@@ -54,8 +59,12 @@ For starters, consider this simple message::
     required int32 value = 1;
  }
 
-Save this in *example.proto* and run it through *nanopb_generate.py*. You
-should now have in *example.h*::
+Save this in *example.proto* and compile it::
+
+    user@host:~$ protoc -omessage.pb message.proto
+    user@host:~$ python ../generator/nanopb_generator.py message.pb
+
+You should now have in *example.h*::
 
  typedef struct {
     int32_t value;
@@ -74,19 +83,14 @@ After that, buffer will contain the encoded message.
 The number of bytes in the message is stored in *stream.bytes_written*.
 You can feed the message to *protoc --decode=Example example.proto* to verify its validity.
 
-Library reference
-=================
-
-**Encoding**
-
-**Decoding**
-
-**Specifying field options**
+Debugging and testing
+=====================
+Extensive unittests are included under the *tests* folder. Just type *make* there to run the tests.
 
-**Generated code**
+This also generates a file called *breakpoints* which includes all lines returning *false* in nanopb. You can use this in gdb by typing *source breakpoints*, after which gdb will break on first nanopb error.
 
 Wishlist
 ========
 #) A specialized encoder for encoding to a memory buffer. Should serialize in reverse order to avoid having to determine submessage size beforehand.
-#) A cleaner rewrite of the source generator.
+#) A cleaner rewrite of the Python-based source generator.
 #) Better performance for 16- and 8-bit platforms: use smaller datatypes where possible.