Base: Add block header docstring

docs/whitedoc/proof_of_stake.rst

@@ -29,10 +29,11 @@ The shell header contains
 -  ``fitness``: a sequence of sequences of unsigned bytes, ordered by
    length and then lexicographically. It represents the claimed fitness
    of the chain ending in this block.
--  ``operations_hash`` The root hash of a merkle tree of a list of root
+-  ``operations_hash`` The hash of a list of root hashes of merkle
-   hashes of merkle trees for various sets of operations in the block.
+      trees of operations. There is one list of operations per
+      validation pass
 -  ``context`` Hash of the state of the context after application of
-   this block. Useful for light clients.
+   this block.
 
 Protocol header (for tezos.alpha):
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

src/lib_base/block_header.mli

@@ -25,13 +25,25 @@
 
 type shell_header = {
   level: Int32.t ;
+  (** Height of the block, from the genesis block. *)
   proto_level: int ; (* uint8 *)
+  (** Number of protocol changes since genesis modulo 256. *)
   predecessor: Block_hash.t ;
+  (** Hash of the preceding block. *)
   timestamp: Time.t ;
+  (** Timestamp at which the block is claimed to have been created. *)
   validation_passes: int ; (* uint8 *)
+  (** Number of validation passes (also number of lists of operations). *)
   operations_hash: Operation_list_list_hash.t ;
+  (** Hash of the list of lists (actually root hashes of merkle trees)
+      of operations included in the block. There is one list of
+      operations per validation pass. *)
   fitness: Fitness.t ;
+  (** A sequence of sequences of unsigned bytes, ordered by length and
+      then lexicographically. It represents the claimed fitness of the
+      chain ending in this block. *)
   context: Context_hash.t ;
+  (** Hash of the state of the context after application of this block. *)
 }
 
 val shell_header_encoding: shell_header Data_encoding.t