Proto_alpha/levels: added documentation

src/proto_alpha/lib_protocol/src/level_repr.mli

@@ -8,15 +8,31 @@
 (**************************************************************************)
 
 type t = private {
-  level: Raw_level_repr.t ;
+  level: Raw_level_repr.t (** The level of the block relative to genesis. This
-  level_position: int32 ;
+                              is also the Shell's notion of level. *);
-  cycle: Cycle_repr.t ;
+  level_position: int32 (** The level of the block relative to the block that
-  cycle_position: int32 ;
+                            starts protocol alpha. This is specific to the
+                            protocol alpha. Other protocols might or might not
+                            include a similar notion. *);
+  cycle: Cycle_repr.t (** The current cycle's number. Note that cycles are a
+                          protocol-specific notion. As a result, the cycle
+                          number starts at 0 with the first block of protocol
+                          alpha. *);
+  cycle_position: int32 (** The current level of the block relative to the first
+                            block of the current cycle. *);
   voting_period: Voting_period_repr.t ;
   voting_period_position: int32 ;
   expected_commitment: bool ;
 }
 
+(* Note that, the type `t` above must respect some invariants (hence the
+   `private` annotation). Notably:
+
+   level_position = cycle * blocks_per_cycle + cycle_position
+*)
+
+
+
 type level = t
 
 include Compare.S with type t := level

src/proto_alpha/lib_protocol/src/raw_level_repr.mli

@@ -7,6 +7,9 @@
 (*                                                                        *)
 (**************************************************************************)
 
+(** The shell's notion of a level: an integer indicating the number of blocks
+    since genesis: genesis is 0, all other blocks have increasing levels from
+    there. *)
 type t
 type raw_level = t
 val encoding: raw_level Data_encoding.t