From 6a83898d98989739c3494db03ae8f738cf8c99d0 Mon Sep 17 00:00:00 2001
From: Pietro <pietro.abate@tezcore.com>
Date: Sun, 30 Sep 2018 15:02:05 +0200
Subject: [PATCH] Base: Add block header docstring

---
 docs/whitedoc/proof_of_stake.rst |  7 ++++---
 src/lib_base/block_header.mli    | 12 ++++++++++++
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/docs/whitedoc/proof_of_stake.rst b/docs/whitedoc/proof_of_stake.rst
index 1153553b7..0b24a7a5a 100644
--- a/docs/whitedoc/proof_of_stake.rst
+++ b/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
-   hashes of merkle trees for various sets of operations in the block.
+-  ``operations_hash`` The hash of a list of root hashes of merkle
+      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):
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/src/lib_base/block_header.mli b/src/lib_base/block_header.mli
index 9b7281ab6..9586b6145 100644
--- a/src/lib_base/block_header.mli
+++ b/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