From 3e1c4008c33e6b8ef3b1a885adc184e40b9b4c8b Mon Sep 17 00:00:00 2001 From: Pietro Abate Date: Tue, 14 Nov 2017 00:42:58 +0100 Subject: [PATCH] Add docstrings in `src/environment/v1/` --- src/environment/v1/tezos_data.mli | 23 +++++++++++++++++++---- src/environment/v1/updater.mli | 31 ++++++++++++++++++------------- src/environment/v1/z.mli | 2 ++ 3 files changed, 39 insertions(+), 17 deletions(-) diff --git a/src/environment/v1/tezos_data.mli b/src/environment/v1/tezos_data.mli index 8740a5364..0f535dc42 100644 --- a/src/environment/v1/tezos_data.mli +++ b/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 ; } diff --git a/src/environment/v1/updater.mli b/src/environment/v1/updater.mli index e6021b5c3..b635401b8 100644 --- a/src/environment/v1/updater.mli +++ b/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 diff --git a/src/environment/v1/z.mli b/src/environment/v1/z.mli index 123ce6c6d..fd629afb9 100644 --- a/src/environment/v1/z.mli +++ b/src/environment/v1/z.mli @@ -7,6 +7,8 @@ (* *) (**************************************************************************) +(** Tezos Protocol Environment - Arbitrary precision arithmetic. *) + type t val zero: t val one: t