Add docstrings in src/environment/v1/

src/environment/v1/tezos_data.mli

@@ -7,6 +7,10 @@
 (*                                                                        *)
 (**************************************************************************)
 
+(** Tezos Protocol Environment - Basic data structures *)
+
+(** Generic interface for a datatype with comparison, pretty-printer
+    and serialization functions. *)
 module type DATA = sig
 
   type t
@@ -31,8 +35,8 @@ module type DATA = sig
 
 end
 
-module Fitness : DATA with type t = MBytes.t list
-
+(** Generic interface for a datatype with comparison, pretty-printer,
+    serialization functions and a hashing function. *)
 module type HASHABLE_DATA = sig
 
   include DATA
@@ -43,11 +47,18 @@ module type HASHABLE_DATA = sig
 
 end
 
+(** The fitness of a block is defined as a list of bytes,
+    compared in a lexicographical order (longer list are greater). *)
+module Fitness : DATA with type t = MBytes.t list
+
+(** Tezos operations. *)
 module Operation : sig
 
   type shell_header = {
     net_id: Net_id.t ;
     branch: Block_hash.t ;
+    (** The operation is only valid in a branch containing the
+        block [branch]. *)
   }
   val shell_header_encoding: shell_header Data_encoding.t
 
@@ -66,10 +77,14 @@ module Block_header : sig
   type shell_header = {
     net_id: Net_id.t ;
     level: Int32.t ;
-    proto_level: int ; (* uint8 *)
+    (** The number of preceding block in this chain, i.e. the genesis
+        has level 0. *)
+    proto_level: int ;
+    (** The number of preceding protocol change in the chain (modulo 256), 
+        i.e the genesis has proto_level 0. *)
     predecessor: Block_hash.t ;
     timestamp: Time.t ;
-    validation_passes: int ; (* uint8 *)
+    validation_passes: int ;
     operations_hash: Operation_list_list_hash.t ;
     fitness: MBytes.t list ;
   }

src/environment/v1/updater.mli

@@ -7,7 +7,7 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Tezos Protocol Environment - Protocol Implementation Updater *)
+(** Tezos Protocol Environment - Protocol updater. *)
 
 type validation_result = {
   context: Context.t ;
@@ -31,13 +31,13 @@ module type PROTOCOL = sig
   (** The version specific type of operations. *)
   type operation
 
-  (** The maximum size of operations in bytes *)
+  (** The maximum size of operations in bytes. *)
   val max_operation_data_length: int
 
-  (** The maximum size of block headers in bytes *)
+  (** The maximum size of block headers in bytes. *)
   val max_block_length: int
 
-  (** The maximum *)
+  (** The maximum number of operations allowed in one block. *)
   val max_number_of_operations: int
 
   (** The parsing / preliminary validation function for
@@ -75,11 +75,10 @@ module type PROTOCOL = sig
 
   (** The first step in a block validation sequence. Initializes a
       validation context for validating a block. Takes as argument the
-      {!Block_header.t} to initialize the context for this block, patching
-      the context resulting of the application of the predecessor
-      block passed as parameter. The function {!precheck_block} may
-      not have been called before [begin_application], so all the
-      check performed by the former must be repeated in the latter. *)
+      {!Block_header.t} to initialize the context for this block. The
+      function {!precheck_block} may not have been called before
+      [begin_application], so all the check performed by the former
+      must be repeated in the latter. *)
   val begin_application:
     predecessor_context: Context.t ->
     predecessor_timestamp: Time.t ->
@@ -88,10 +87,13 @@ module type PROTOCOL = sig
     validation_state tzresult Lwt.t
 
   (** Initializes a validation context for constructing a new block
-      (as opposed to validating an existing block). Since there is no
-      {!Block_header.t} header available, the parts that it provides are
-      passed as arguments (predecessor block hash, context resulting
-      of the application of the predecessor block, and timestamp). *)
+      (as opposed to validating an existing block). When the
+      [proto_header] argument is not specified, the function should
+      produce the exact same effect on the context than would produce
+      the validation of a block containing an "equivalent" (but
+      complete) header. For instance, if the block header usually
+      includes a signature, the header provided to
+      {!begin_construction} could includes a faked signature. *)
   val begin_construction:
     predecessor_context: Context.t ->
     predecessor_timestamp: Time.t ->
@@ -116,6 +118,9 @@ module type PROTOCOL = sig
   (** The list of remote procedures exported by this implementation *)
   val rpc_services: rpc_context RPC.directory
 
+  (** An ad-hoc context patcher. It used only for debugging protocol
+      while running in the "sandbox" mode. This function is never used
+      in production. *)
   val configure_sandbox:
     Context.t -> Data_encoding.json option -> Context.t tzresult Lwt.t
 

src/environment/v1/z.mli

@@ -7,6 +7,8 @@
 (*                                                                        *)
 (**************************************************************************)
 
+(** Tezos Protocol Environment - Arbitrary precision arithmetic. *)
+
 type t
 val zero: t
 val one: t