From f6474047392a5176c0b03fbfbc290bb09d5e0218 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rapha=C3=ABl=20Proust?= <code@bnwr.net>
Date: Wed, 30 May 2018 15:40:03 +0800
Subject: [PATCH] Proto_alpha/levels: added documentation

---
 .../lib_protocol/src/level_repr.mli           | 24 +++++++++++++++----
 .../lib_protocol/src/raw_level_repr.mli       |  3 +++
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/src/proto_alpha/lib_protocol/src/level_repr.mli b/src/proto_alpha/lib_protocol/src/level_repr.mli
index abe88bc4b..61065b31d 100644
--- a/src/proto_alpha/lib_protocol/src/level_repr.mli
+++ b/src/proto_alpha/lib_protocol/src/level_repr.mli
@@ -8,15 +8,31 @@
 (**************************************************************************)
 
 type t = private {
-  level: Raw_level_repr.t ;
-  level_position: int32 ;
-  cycle: Cycle_repr.t ;
-  cycle_position: int32 ;
+  level: Raw_level_repr.t (** The level of the block relative to genesis. This
+                              is also the Shell's notion of level. *);
+  level_position: int32 (** The level of the block relative to the block that
+                            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
diff --git a/src/proto_alpha/lib_protocol/src/raw_level_repr.mli b/src/proto_alpha/lib_protocol/src/raw_level_repr.mli
index cbd538dc7..c70d9bd8a 100644
--- a/src/proto_alpha/lib_protocol/src/raw_level_repr.mli
+++ b/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