Fix/why is shift a number

doc/datatypes/conditional.md

@@ -15,7 +15,6 @@ For `compareTo` variables, to go up one level when referencing a field, use "../
 Switch statement field names starting with "/" will reference a root variable. Root variables are primitives that can be used for comparisons and changed dynamically.
 
 Example:
-
 A switch which can encode a byte, a varint, a float or a string depending on "someField". 
 If the value of someField is different, then the value encoded is of type void.
 ```json
@@ -43,7 +42,8 @@ Represents a simple optional type.
 It's encoded as a boolean indicating whether the value is there or not.
 It's similar to the `Optional` type in java or `Maybe` in haskell.
 
-Example: An option of value string
+Example:
+An option of value string
 ```json
 [
   "option",

doc/datatypes/numeric.md

@@ -36,7 +36,7 @@ Example:
 ```
 Example of value: `65535` (size = 2) / `16777215` (size = 3)
 
-### **varint** ( )
+### **varint** ()
 Arguments: None
 
 [Protobuf](https://developers.google.com/protocol-buffers/docs/encoding#varints)-compatible representation for variable-length integers using one or more bytes. Intended for 32-bit unsigned integers, or signed 32-bit integers that have been directly cast to an integer (where the MSB is the sign bit) before encoding.

doc/datatypes/primitives.md

@@ -1,20 +1,20 @@
 ## Primitives
 
-### **bool** ( )
+### **bool** ()
 Arguments: None
 
 Represents a boolean, encoded in one byte.
 
 Example of value: `true` / `false`
 
-### **cstring** ( )
-Arguments: encoding
+### **cstring** ({ ?encoding: String })
+Arguments:
+* encoding : the encoding of the string, UTF-8 by default
 
-Represents a null terminated string. Similar to strings in C.
-Assumes UTF-8 encoding by default
+Represents a null-terminated string. Similar to strings in C.
 
 Example:
-Example: A string length prefixed by a varint.
+A UTF-16 string of unknown size that is expected to end with the zero character (null-terminal).
 ```json
 [
   "cstring", { "encoding": "utf-16" }
@@ -23,7 +23,7 @@ Example: A string length prefixed by a varint.
 
 Example of value: `"my string"`
 
-### **void** ( )
+### **void** ()
 Arguments: None
 
 Represents an empty value.

doc/datatypes/structures.md

@@ -8,7 +8,8 @@ Arguments:
 
 Represents a list of values with same type.
 
-Example: An array of int prefixed by a short length.
+Example:
+An array of int prefixed by a short length.
 ```json
 [
   "array",
@@ -20,7 +21,7 @@ Example: An array of int prefixed by a short length.
 ```
 Example of value: `[1, 2, 3, 4]` (type = [i8](./numeric.md)) / `["ac", "dc"]` (type = [cstring](./utils.md))
 
-### **container** ([ { name: String, type: Type, ?anon: Bool }, ... ])
+### **container** ([ { name: String, type: Type, ?anon: Boolean }, ... ])
 Arguments: 
 * [array] : a field
 * * name : the name of field
@@ -29,7 +30,8 @@ Arguments:
 
 Represents a list of named values.
 
-Example: A container with fields of type int, int, ushort and ushort.
+Example:
+A container with fields of type int, int, ushort and ushort.
 ```json
 [
   "container",
@@ -57,7 +59,8 @@ Arguments:
 
 Represents a count field for an array or a buffer. 
 
-Example: A count for a field name records, of type short.
+Example:
+A count for a field name records, of type short.
 ```json
 [
   "count",

doc/datatypes/utils.md

@@ -8,7 +8,8 @@ Arguments:
 
 Represents a raw bytes with count prefix/field or without it.
 
-Example: An buffer prefixed by a varint length.
+Example:
+An buffer prefixed by a varint length.
 ```json
 [
     "buffer",
@@ -29,7 +30,6 @@ Represents a list of value with sizes that are not a multiple of 8bits.
 The sum of the sizes must be a multiple of 8.
 
 Example:
-
 3 values, x, y and z with sizes in bits : 26, 12, 26. Notice that 26+12+26=64.
 ```json
 [
@@ -52,7 +52,6 @@ Arguments:
 Maps string to a values.
 
 Example:
-
 Maps a byte to a string, 1 to "byte", 2 to "short", 3 to "int", 4 to "long".
 ```json
 [
@@ -70,17 +69,16 @@ Maps a byte to a string, 1 to "byte", 2 to "short", 3 to "int", 4 to "long".
 ```
 Example of value: `"int"`
 
-### **bitflags** ([ { type: string, flags: object | array, big?: boolean, shift?: number } ])
+### **bitflags** ([ { type: String, flags: Object | Array, ?big: Boolean, ?shift: Boolean } ])
 Arguments:
 * type : The underlying integer type (eg varint, lu32).
 * flags : Either an array of flag values from LSB to MSB, or an object containing a mappng of valueName => bitMask.
-* big : 64+ bits. In langauges like javascript (where all numbers are 64-bit floating points), special data types may have to be used for integers greater than 32 bits, so this must be set to true if the `type` is using the special data type.
-* shift : Specify if flags is an object and holds bit positions as values opposed to a bitmask.
+* big : If the type is 64+ bits. In languages like javascript (where all numbers are 64-bit floating points), special data types may have to be used for integers greater than 32 bits, so this must be set to true if the `type` is using the special data type.
+* shift : Specify if flags is an object and holds bit positions as values opposed to a bitmask, false by default.
 
 Represents boolean flags packed into an integer. Similar to bitfields, but only intended for enumerated boolean flags (each flag occupies 1 bit), and supports arbitrary underlying integer types.
 
 Example:
-
 ```json
 [
   "bitflags",
@@ -92,15 +90,33 @@ Example:
 ```
 
 or 
-```yaml
+```json
+[
+  "bitflags",
+  {
+    "type": "lu32",
+    "big": true,
+    "flags": {
+      "onGround": 1,
+      "inAir": 2
+    }
+  }
+]
+```
+
+(where `1` and `2` respectively are the JSON-compatible, decimal representations of the bitmasks `0b01` and `0b10`)
+
+or 
+```json
 [
   "bitflags",
   {
     "type": "lu32",
     "big": true,
+    "shift": true,
     "flags": {
-      "onGround": 0b1,
-      "inAir": 0b10
+      "onGround": 0,
+      "inAir": 1
     }
   }
 ]
@@ -109,15 +125,16 @@ or
 Example of value to pass when writing: `{"flags": { "onGround": true, "inAir": false } }`. Likewise when reading you will get a similar object back, with a extra `_value` field holding the raw integer.
 
 
-### **pstring** ({ countType: Type, ?count: Countable })
+### **pstring** ({ countType: Type, ?count: Countable, ?encoding: String })
 Arguments:
 * countType : the type of the length prefix
 * count : optional (either count or countType), a reference to the field counting the elements, or a fixed size (an integer)
-* encoding: the encoding of the string, UTF-8 by default
+* encoding : the encoding of the string, UTF-8 by default
 
 Represents a string.
 
-Example: A string length prefixed by a varint.
+Example:
+A string length prefixed by a varint.
 ```json
 [
   "pstring", { "countType": "varint", "encoding": "utf-8" }