annotate example idl file with appropriate comments

tests/example.idl

@@ -1,67 +1,85 @@
-(def-newtype time_micros_t sint64_t)
 
+-- An example gidl IDL.
+-- Line comments are haskell style.
+{- Block comments are haskell style, as well. -}
+
+-------------------------------------------------------------------------------
+-- Type language
+-------------------------------------------------------------------------------
+
+-- All types end with a _t suffix in gidl syntax. Code generators may elect to
+-- drop the _t suffix when generating type definitions.
+
+-- Newtype definitions create a distinct type by wrapping an existing atomic,
+-- enum, or newtype.
+(def-newtype time_micros_t sint64_t)
 
+-- Enums are pairs of names and integer values. Must be a one-to-one
+-- mapping: names are not repeated, values are not repeated.
+-- Enums default to 32 bit width if you don't really care.
+-- N.B. we should probably change it to default to the smallest
+-- width that fits the values the user declared.
 (def-enum mode_t
  (stabilize 0)
  (auto 1))
 
+-- The user can specify a bit width for enums with the
+-- following syntax. 8, 16, 32, 64 bit widths are valid.
 (def-enum (armed_t 8)
  (disarmed 0)
  (armed 1))
 
+-- Structures are a set of pairs of names and types. All
+-- names must be distinct. All types must be atomic, enum,
+-- or newtypes.
 (def-struct heartbeat_t
  (time time_micros_t)
  (armed armed_t))
 
-(def-newtype lat_t sint32_t)
-(def-newtype lon_t sint32_t)
-
-
-(def-newtype meters_t float_t)
-
+-- Definitions may be out of order. Circular definitions
+-- are not permitted.
 (def-struct coordinate_t
  (lat lat_t)
  (lon lon_t)
  (alt meters_t))
+(def-newtype lat_t sint32_t)
+(def-newtype lon_t sint32_t)
+(def-newtype meters_t float_t)
 
+-- There is no way to extend (subtype) an existing structure, or compose
+-- structures within structures. However, names may be repeated.
 (def-struct timed_coord_t
   (lat lat_t)
   (lon lon_t)
   (alt meters_t)
   (time time_micros_t))
 
+-------------------------------------------------------------------------------
+-- Interface language
+-------------------------------------------------------------------------------
 
+-- Here is an interface which defines a single stream named heartbeat.
 (def-interface vehicle_i ()
- (heartbeat (stream 10 heartbeat_t)))
+ (heartbeat (stream heartbeat_t)))
 
+-- Type definitions may be interspersed with interface definitions
+(def-enum light_mode_t
+  (off  0)
+  (blink_slow 1)
+  (blink_fast 2)
+  (on 3))
+
+-- Here is an interface which defines a single attribute. Attributes
+-- may be given read, write, or readwrite access.
+(def-interface light_i ()
+  (light_mode (attr readwrite light_mode_t)))
 
-(def-interface controllable_vehicle_i (vehicle_i) -- Inherits from interface vehicle
+-- Interfaces may be extended (subtyped). No shadowing of method
+-- names permitted.
+-- This interface extends the vehicle_i and light_i interfaces,
+-- and defines two additional attributes.
+(def-interface controllable_vehicle_i (vehicle_i light_i)
   (current_waypoint (attr read      coordinate_t))
   (next_waypoint    (attr readwrite timed_coord_t)))
 
+