doc: fix protocol/datatypes.

Change-Id: I98feff61d7303f73aff6f038cda3bdeb94fea021

doc/source/protocol/datatypes.rst

@@ -1,77 +1,175 @@
 Datatypes
 =========
 
+double
+------
+
 .. list-table::
-    :header-rows: 1
+    :widths: 20 80
+    :stub-columns: 1
 
-    * - Data type
+    * - Datatype
-      - Specification (simple)
+      - | ["double"] **or**
-      - Specification (with limits)
+        | ["double", <min>] **or**
-      - Transport example
+        | ["double", <min>, <max>]
-      - Datatype used in C/C++ API
+        |
-      - Remarks 
+        | if <max> is not given or null, there is no upper limit
+        | if <min> is null or not given, there is no lower limit
 
-    * - double
+    * - Transport example
-      - ["double"]
+      - | 3.14159265
-      - ["double", <min>, <max>]
-      - 3.14159265
-      - double
-      -  
 
-    * - int
+    * - Datatype in C/C++
-      - ["int"]
+      - | double
-      - ["int", <min>, <max>]
-      - -55
-      - int64_t
-      -
 
-    * - bool
+int
-      - ["bool"]
+---
-      -
-      - true
-      - int64_t
-      -
 
-    * - enum
+.. list-table::
-      - ["enum", {<name> : <value>, ....}]
+    :widths: 20 80
-      -
+    :stub-columns: 1
-      - 1
-      - int64_t
-      -
 
-    * - string
+    * - Datatype
-      - ["string"]
+      - | ["int"] **or**
-      - ["string", <min len>, <max len>]
+        | ["int", <min>] **or**
-      - "hello!"
+        | ["int", <min>, <max>]
-      - char *
+        |
-      -
+        | if <max> is not given or null, there is no upper limit
+        | if <min> is null or not given, there is no lower limit
 
-    * - blob
+    * - Transport example
-      - ["blob"]
+      - | -55
-      - ["blob", <min len>, <max len>]
-      - "AA=="
-      - struct {int64_t len, char \*data}
-      - transport is base64 encoded
 
-    * - array
+    * - Datatype in C/C++
-      - ["array", <basic type>]
+      - | int64_t
-      - ["array", <basic type>, <min len>, <max len>]
-      - [3,4,7,2,1]
-      - <basic_datatype>[]
-      -
 
-    * - tuple
+bool
-      - ["tuple", [<datatype>, <datatype>, ...]]
+----
-      -
-      - [0,"idle"]
-      - struct ??
-      - 
 
-    * - struct
+.. list-table::
-      - ["struct", {<name> : <datatype>, <name>: <datatype>, ....}]
+    :widths: 20 80
-      -
+    :stub-columns: 1
-      - {"x": 0, "y": 1}
-      - struct ??
-      -
-      
 
+    * - Datatype
+      - | ["bool"]
+
+    * - Transport example
+      - | true
+
+    * - Datatype in C/C++
+      - | int64_t
+
+
+enum
+----
+
+.. list-table::
+    :widths: 20 80
+    :stub-columns: 1
+
+    * - Datatype
+      - | ["enum", {<name> : <value>, ....}]
+
+    * - Transport example
+      - | 2
+
+    * - Datatype in C/C++
+      - | int64_t
+
+
+string
+------
+
+.. list-table::
+    :widths: 20 80
+    :stub-columns: 1
+
+    * - Datatype
+      - | ["string"] **or**
+        | ["string", <max len>] **or**
+        | ["string", <max len>, <min len>]
+        |
+        | if <max len> is not given, it is assumed as 255.
+        | if <min len> is not given, it is assumed as 0.
+        | if the string is UTF-8 encoded, the length is counting the number of bytes, not characters
+
+    * - Transport example
+      - | "hello!"
+
+    * - Datatype in C/C++
+      - | char \*
+
+blob
+----
+
+.. list-table::
+    :widths: 20 80
+    :stub-columns: 1
+
+    * - Datatype
+      - | ["blob", <max len>] **or**
+        | ["blob", <max len>, <min len>]
+        |
+        | if <max len> is not given, it is assumed as 255.
+        | if the string is UTF-8 encoded, the length is counting the number of bytes, not characters
+        | if <min len> is not given, it is assumed as 0.
+
+    * - Transport example
+      - | "AA=="  (base64 encoded)
+
+    * - Datatype in C/C++
+      - | struct {int64_t len, char \*data}
+
+array
+-----
+
+.. list-table::
+    :widths: 20 80
+    :stub-columns: 1
+
+    * - Datatype
+      - | ["array", <basic type>, <max len>] **or**
+        | ["array", <basic type>, <max len>, <min len>]
+        |
+        | if <min len> is not given, it is assumed as 0.
+        | the length is the number of elements
+
+    * - Transport example
+      - | [3,4,7,2,1]
+
+    * - Datatype in C/C++
+      - | <basic_datatype>[]
+ 
+tuple
+-----
+
+.. list-table::
+    :widths: 20 80
+    :stub-columns: 1
+
+    * - Datatype
+      - | ["tuple", [<datatype>, <datatype>, ...]]
+
+    * - Transport example
+      - | [0,"idle"]
+
+    * - Datatype in C/C++
+      - | struct ??
+
+struct
+------
+
+.. list-table::
+    :widths: 20 80
+    :stub-columns: 1
+
+    * - Datatype
+      - | ["struct", {<name> : <datatype>, <name>: <datatype>, ....}]
+
+    * - Transport example
+      - | {"x": 0, "y": 1}
+
+    * - Datatype in C/C++
+      - | struct ??
+        |
+        | might be null