From c87b6c533df524e418980196d023eda16132896e Mon Sep 17 00:00:00 2001
From: Pietro Abate <pietro.abate@tezcore.com>
Date: Tue, 28 Aug 2018 16:23:58 +0200
Subject: [PATCH] Prevalidator: Add doc string to prevalidator/ion.

---
 src/lib_shell/prevalidation.mli | 13 +++++++++++++
 src/lib_shell/prevalidator.mli  | 24 +++++++++++++++++++++++-
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/src/lib_shell/prevalidation.mli b/src/lib_shell/prevalidation.mli
index edf2649f0..b49c9e44a 100644
--- a/src/lib_shell/prevalidation.mli
+++ b/src/lib_shell/prevalidation.mli
@@ -23,14 +23,25 @@
 (*                                                                           *)
 (*****************************************************************************)
 
+(** A newly received block is validated by replaying locally the block
+    creation, applying each operation and its finalization to ensure their
+    consistency. This module is stateless and creates and manupulates the
+    prevalidation_state. *)
+
 type prevalidation_state
 
+(** Creates a new prevalidation context w.r.t. the protocol associate to the
+    predecessor block . When ?protocol_data is passed to this function, it will
+    be used to create the new block *)
 val start_prevalidation :
   ?protocol_data: MBytes.t ->
   predecessor: State.Block.t ->
   timestamp: Time.t ->
   unit -> prevalidation_state tzresult Lwt.t
 
+(** Given a prevalidation context applies a list of operations,
+    returns a new prevalidation context plus the preapply result containing the
+    list of operations that cannot be applied to this context *)
 val prevalidate :
   prevalidation_state -> sort:bool ->
   (Operation_hash.t * Operation.t) list ->
@@ -40,6 +51,8 @@ val end_prevalidation :
   prevalidation_state ->
   Tezos_protocol_environment_shell.validation_result tzresult Lwt.t
 
+(** Pre-apply creates a new block ( running start_prevalidation, prevalidate and
+    end_prevalidation), and returns a new block. *)
 val preapply :
   predecessor:State.Block.t ->
   timestamp:Time.t ->
diff --git a/src/lib_shell/prevalidator.mli b/src/lib_shell/prevalidator.mli
index 1f39f7685..cf1d8e544 100644
--- a/src/lib_shell/prevalidator.mli
+++ b/src/lib_shell/prevalidator.mli
@@ -54,18 +54,40 @@ type limits = {
 
 type error += Closed of Chain_id.t
 
+(** Creates a new worker. Each chain is associated with a prevalidator. Typically,
+    this is the case for the main chain and a test chain *)
 val create: limits -> Distributed_db.chain_db -> t Lwt.t
+
 val shutdown: t -> unit Lwt.t
+
+(** Notify the prevalidator worker of a set of operations (in the form of a mempool)
+    received from a peer. *)
 val notify_operations: t -> P2p_peer.Id.t -> Mempool.t -> unit
+
+(** Notify the prevalidator worker of a new injected operation. This will be added
+    to the mempool of the worker *)
 val inject_operation: t -> Operation.t -> unit tzresult Lwt.t
+
+(** Notify the prevalidator worker that a new head was received. The new head will
+    cause the reset of the prevalidation context *)
 val flush: t -> Block_hash.t -> unit tzresult Lwt.t
+
+(** Returns the timestamp of the prevalidator worker, that is the timestamp of the last
+    reset of the prevalidation context *)
 val timestamp: t -> Time.t
+
+(** Returns the list of valid operations known to this prevalidation worker *)
 val operations: t -> error Preapply_result.t * Operation.t Operation_hash.Map.t
+
+(** Returns the list of pending operations known to this prevalidation worker *)
 val pending: ?block:State.Block.t -> t -> Operation.t Operation_hash.Map.t Lwt.t
 
+(** Returns the list of prevalidation workers running and their associated chain *)
 val running_workers: unit -> (Chain_id.t * t) list
-val status: t -> Worker_types.worker_status
 
+(** Worker status and events *)
+
+val status: t -> Worker_types.worker_status
 val pending_requests : t -> (Time.t * Prevalidator_worker_state.Request.view) list
 val current_request : t -> (Time.t * Time.t * Prevalidator_worker_state.Request.view) option
 val last_events : t -> (Lwt_log_core.level * Prevalidator_worker_state.Event.t list) list