From 413274632c7eef200c691a86aea51a5e0e2ca7e1 Mon Sep 17 00:00:00 2001
From: Nicolas Ayache <nicolas.ayache@nomadic-labs.com>
Date: Thu, 2 Jun 2022 13:35:19 +0200
Subject: [PATCH 1/3] Proto: Alpha_context docstrings.

---
 .../lib_protocol/alpha_context.mli            | 121 +++++++++++++++---
 1 file changed, 104 insertions(+), 17 deletions(-)

diff --git a/src/proto_alpha/lib_protocol/alpha_context.mli b/src/proto_alpha/lib_protocol/alpha_context.mli
index 9ae91306fc0a..416ec3aa730d 100644
--- a/src/proto_alpha/lib_protocol/alpha_context.mli
+++ b/src/proto_alpha/lib_protocol/alpha_context.mli
@@ -64,6 +64,7 @@ type public_key_hash = Signature.Public_key_hash.t
 
 type signature = Signature.t
 
+(** This module re-exports definitions from {!Slot_repr}. *)
 module Slot : sig
   type t
 
@@ -100,6 +101,7 @@ module Slot : sig
   module Set : Set.S with type elt = t
 end
 
+(** This module re-exports definitions from {!Tez_repr}. *)
 module Tez : sig
   type repr
 
@@ -144,6 +146,7 @@ module Tez : sig
   val div_exn : t -> int -> t
 end
 
+(** This module re-exports definitions from {!Period_repr}. *)
 module Period : sig
   include BASIC_DATA
 
@@ -172,6 +175,7 @@ module Period : sig
   val compare : period -> period -> int
 end
 
+(** This module re-exports definitions from {!Time_repr}. *)
 module Timestamp : sig
   include BASIC_DATA with type t = Time.t
 
@@ -195,11 +199,14 @@ module Timestamp : sig
 
   val to_seconds_string : time -> string
 
+  (** See {!Raw_context.current_timestamp}. *)
   val current : context -> time
 
+  (** See {!Raw_context.predecessor_timestamp}. *)
   val predecessor : context -> time
 end
 
+(** This module re-exports definitions from {!Ratio_repr}. *)
 module Ratio : sig
   type t = {numerator : int; denominator : int}
 
@@ -208,6 +215,7 @@ module Ratio : sig
   val pp : Format.formatter -> t -> unit
 end
 
+(** This module re-exports definitions from {!Raw_level_repr}. *)
 module Raw_level : sig
   include BASIC_DATA
 
@@ -230,6 +238,7 @@ module Raw_level : sig
   val of_int32_exn : int32 -> raw_level
 end
 
+(** This module re-exports definitions from {!Cycle_repr}. *)
 module Cycle : sig
   include BASIC_DATA
 
@@ -252,6 +261,7 @@ module Cycle : sig
   module Map : Map.S with type key = cycle
 end
 
+(** This module re-exports definitions from {!Round_repr}. *)
 module Round : sig
   (* A round represents an iteration of the single-shot consensus algorithm.
      This mostly simply re-exports [Round_repr]. See [Round_repr] for
@@ -283,12 +293,16 @@ module Round : sig
 
   module Map : Map.S with type key = t
 
+  (** See {!Round_repr.Durations.t}. *)
   type round_durations
 
+  (** See {!Round_repr.Durations.pp}. *)
   val pp_round_durations : Format.formatter -> round_durations -> unit
 
+  (** See {!Round_repr.Durations.encoding}. *)
   val round_durations_encoding : round_durations Data_encoding.t
 
+  (** See {!Round_repr.Durations.round_duration}. *)
   val round_duration : round_durations -> t -> Period.t
 
   module Durations : sig
@@ -485,6 +499,8 @@ end
 
 module Entrypoint : module type of Entrypoint_repr
 
+(** This module re-exports definitions from {!Script_repr} and
+    {!Michelson_v1_primitives}. *)
 module Script : sig
   type prim = Michelson_v1_primitives.prim =
     | K_parameter
@@ -689,6 +705,8 @@ module Script : sig
     lazy_expr ->
     (expr * context) tzresult
 
+  (** Decode an expression in the context after consuming the deserialization
+      gas cost. *)
   val force_bytes_in_context :
     context -> lazy_expr -> (bytes * context) tzresult
 
@@ -713,6 +731,8 @@ module Script : sig
   val strip_annotations : node -> node
 end
 
+(** This module re-exports definitions from {!Constants_repr} and
+    {!Constants_storage}. *)
 module Constants : sig
   (** Fixed constants *)
   type fixed
@@ -731,7 +751,7 @@ module Constants : sig
 
   val michelson_maximum_type_size : int
 
-  (** Constants parameterized by context *)
+  (** Constants parameterized by context. See {!Constants_parametric_repr}. *)
   module Parametric : sig
     type dal = {
       feature_enable : bool;
@@ -884,6 +904,7 @@ module Constants : sig
 
   val delay_increment_per_round : context -> Period.t
 
+  (** See {!Raw_context.round_durations}. *)
   val round_durations : context -> Round.round_durations
 
   val consensus_committee_size : context -> int
@@ -1048,6 +1069,7 @@ module Internal_for_tests : sig
   val to_raw : context -> Raw_context.t
 end
 
+(** This module re-exports definitions from {!Cache_repr}. *)
 module Cache : sig
   type size = int
 
@@ -1115,6 +1137,8 @@ module Cache : sig
     (module INTERFACE with type cached_value = 'a)
 end
 
+(** This module re-exports definitions from {!Level_repr} and
+    {!Level_storage}. *)
 module Level : sig
   type t = private {
     level : Raw_level.t;
@@ -1165,6 +1189,7 @@ module Level : sig
   val may_snapshot_rolls : context -> bool
 end
 
+(** This module re-exports definitions from {!Fitness_repr}. *)
 module Fitness : sig
   type error += Invalid_fitness | Wrong_fitness | Outdated_fitness
 
@@ -1203,6 +1228,7 @@ module Fitness : sig
   val predecessor_round : t -> Round.t
 end
 
+(** This module re-exports definitions from {!Nonce_storage}. *)
 module Nonce : sig
   type t
 
@@ -1227,6 +1253,7 @@ module Nonce : sig
   val check_hash : nonce -> Nonce_hash.t -> bool
 end
 
+(** This module re-exports definitions from {!Seed_repr} and {!Seed_storage}. *)
 module Seed : sig
   type seed
 
@@ -1298,7 +1325,10 @@ module Big_map : sig
   type alloc = {key_type : Script_repr.expr; value_type : Script_repr.expr}
 end
 
+(** This module re-exports definitions from {!Sapling_repr}, {!Sapling_storage}
+    and {!Sapling_validator}. *)
 module Sapling : sig
+  (** See {!Sapling_state.Id}. *)
   module Id : sig
     type t
 
@@ -1402,13 +1432,16 @@ module Sapling : sig
   end
 end
 
+(** This module re-exports definitions from {!Lazy_storage_diff}. *)
 module Lazy_storage : sig
+  (** This module re-exports definitions from {!Lazy_storage_kind}. *)
   module Kind : sig
     type ('id, 'alloc, 'updates) t =
       | Big_map : (Big_map.Id.t, Big_map.alloc, Big_map.updates) t
       | Sapling_state : (Sapling.Id.t, Sapling.alloc, Sapling.updates) t
   end
 
+  (** This module re-exports definitions from {!Lazy_storage_kind.IdSet}. *)
   module IdSet : sig
     type t
 
@@ -1452,14 +1485,14 @@ module Lazy_storage : sig
 end
 
 module Origination_nonce : sig
-  (** see [Raw_context.init_origination_nonce] *)
+  (** See {!Raw_context.init_origination_nonce}. *)
   val init : context -> Operation_hash.t -> context
 
-  (** see [Raw_context.unset_origination_nonce] *)
+  (** See {!Raw_context.unset_origination_nonce}. *)
   val unset : context -> context
 
   (** This module disclose a type and a function that are only useful for
-      tests. See [Origination_nonce] for documentation. *)
+      tests. See {!Origination_nonce} for documentation. *)
   module Internal_for_tests : sig
     type t
 
@@ -1469,8 +1502,7 @@ module Origination_nonce : sig
   end
 end
 
-(** This module re-exports functions from {!Ticket_hash_repr}. See
-    documentation of the functions there. *)
+(** This module re-exports definitions from {!Ticket_hash_repr}. *)
 module Ticket_hash : sig
   type t
 
@@ -1514,6 +1546,8 @@ module Ticket_hash : sig
   end
 end
 
+(** This module re-exports definitions from {!Contract_repr} and
+    {!Contract_storage}. *)
 module Contract : sig
   type t =
     | Implicit of Signature.Public_key_hash.t
@@ -1543,14 +1577,18 @@ module Contract : sig
 
   val list : context -> t list Lwt.t
 
+  (** See {!Contract_manager_storage.get_manager_key}. *)
   val get_manager_key :
     ?error:error -> context -> public_key_hash -> public_key tzresult Lwt.t
 
+  (** See {!Contract_manager_storage.is_manager_key_revealed}. *)
   val is_manager_key_revealed :
     context -> public_key_hash -> bool tzresult Lwt.t
 
+  (** See {!Contract_manager_storage.check_public_key}. *)
   val check_public_key : public_key -> public_key_hash -> unit tzresult
 
+  (** See {!Contract_manager_storage.reveal_manager_key}. *)
   val reveal_manager_key :
     ?check_consistency:bool ->
     context ->
@@ -1633,6 +1671,7 @@ module Contract : sig
   end
 end
 
+(** This module re-exports definitions from {!Tx_rollup_level_repr}. *)
 module Tx_rollup_level : sig
   include BASIC_DATA
 
@@ -1682,6 +1721,7 @@ module Tx_rollup : sig
   end
 end
 
+(** This module re-exports definitions from {!Tx_rollup_withdraw_repr}. *)
 module Tx_rollup_withdraw : sig
   type order = {
     claimer : Signature.Public_key_hash.t;
@@ -1694,6 +1734,8 @@ module Tx_rollup_withdraw : sig
   val encoding : t Data_encoding.t
 end
 
+(** This module re-exports definitions from
+    {!Tx_rollup_withdraw_list_hash_repr}. *)
 module Tx_rollup_withdraw_list_hash : sig
   include S.HASH
 
@@ -1702,6 +1744,7 @@ module Tx_rollup_withdraw_list_hash : sig
   val empty : t
 end
 
+(** This module re-exports definitions from {!Tx_rollup_message_result_repr}. *)
 module Tx_rollup_message_result : sig
   type t = {
     context_hash : Context_hash.t;
@@ -1715,6 +1758,8 @@ module Tx_rollup_message_result : sig
   val init : t
 end
 
+(** This module re-exports definitions from
+    {!Tx_rollup_message_result_hash_repr}. *)
 module Tx_rollup_message_result_hash : sig
   include S.HASH
 
@@ -1723,6 +1768,8 @@ module Tx_rollup_message_result_hash : sig
   val init : t
 end
 
+(** This module re-exports definitions from {!Tx_rollup_commitment_repr.Hash}.
+*)
 module Tx_rollup_commitment_hash : sig
   val commitment_hash : string
 
@@ -1801,6 +1848,8 @@ module Tx_rollup_state : sig
   end
 end
 
+(** This module re-exports definitions from {!Tx_rollup_reveal_repr} and
+    {!Tx_rollup_reveal_storage}. *)
 module Tx_rollup_reveal : sig
   type t = {
     contents : Script.lazy_expr;
@@ -1862,6 +1911,7 @@ module Tx_rollup_message : sig
   val pp : Format.formatter -> t -> unit
 end
 
+(** This module re-exports definitions from {!Tx_rollup_message_hash_repr}. *)
 module Tx_rollup_message_hash : sig
   include S.HASH
 
@@ -1925,7 +1975,7 @@ module Tx_rollup_inbox : sig
     context tzresult Lwt.t
 end
 
-(** This simply re-exports [Tx_rollup_commitment_repr] *)
+(** This module re-exports definitions from {!Tx_rollup_commitment_repr}. *)
 module Tx_rollup_commitment : sig
   module Merkle_hash : S.HASH
 
@@ -2074,6 +2124,7 @@ module Tx_rollup_commitment : sig
     (context * Tx_rollup_state.t) tzresult Lwt.t
 end
 
+(** This module re-exports definitions from {!Tx_rollup_hash_builder}. *)
 module Tx_rollup_hash : sig
   val message_result :
     context ->
@@ -2091,6 +2142,7 @@ module Tx_rollup_hash : sig
     (context * Tx_rollup_withdraw_list_hash.t) tzresult
 end
 
+(** This module re-exports definitions from {!Tx_rollup_errors_repr}. *)
 module Tx_rollup_errors : sig
   type error +=
     | Tx_rollup_already_exists of Tx_rollup.t
@@ -2175,6 +2227,7 @@ module Sc_rollup_repr : sig
   type t = Address.t
 end
 
+(** This module re-exports definitions from {!Bond_id_repr}. *)
 module Bond_id : sig
   type t =
     | Tx_rollup_bond_id of Tx_rollup.t
@@ -2195,6 +2248,7 @@ module Bond_id : sig
   end
 end
 
+(** This module re-exports definitions from {!Receipt_repr}. *)
 module Receipt : sig
   type balance =
     | Contract of Contract.t
@@ -2239,6 +2293,7 @@ module Receipt : sig
   val group_balance_updates : balance_updates -> balance_updates tzresult
 end
 
+(** This module re-exports definitions from {!Delegate_storage}. *)
 module Delegate : sig
   val init :
     context ->
@@ -2246,6 +2301,7 @@ module Delegate : sig
     Signature.Public_key_hash.t ->
     context tzresult Lwt.t
 
+  (** See {!Contract_delegate_storage.find}. *)
   val find : context -> Contract.t -> public_key_hash option tzresult Lwt.t
 
   val set :
@@ -2332,25 +2388,31 @@ module Delegate : sig
   val staking_balance :
     context -> Signature.Public_key_hash.t -> Tez.t tzresult Lwt.t
 
+  (** See {!Contract_delegate_storage.delegated_contracts}. *)
   val delegated_contracts :
     context -> Signature.Public_key_hash.t -> Contract.t list Lwt.t
 
   val delegated_balance :
     context -> Signature.Public_key_hash.t -> Tez.t tzresult Lwt.t
 
+  (** See {!Contract_delegate_storage.registered}. *)
   val registered : context -> Signature.Public_key_hash.t -> bool tzresult Lwt.t
 
   val deactivated :
     context -> Signature.Public_key_hash.t -> bool tzresult Lwt.t
 
+  (** See {!Delegate_activation_storage.last_cycle_before_deactivation}. *)
   val last_cycle_before_deactivation :
     context -> Signature.Public_key_hash.t -> Cycle.t tzresult Lwt.t
 
   val pubkey : context -> public_key_hash -> public_key tzresult Lwt.t
 
+  (** See {!Stake_storage.prepare_stake_distribution}. *)
   val prepare_stake_distribution : context -> context tzresult Lwt.t
 end
 
+(** This module re-exports definitions from {!Voting_period_repr} and
+    {!Voting_period_storage}. *)
 module Voting_period : sig
   type kind = Proposal | Exploration | Cooldown | Promotion | Adoption
 
@@ -2394,6 +2456,7 @@ module Voting_period : sig
   val get_rpc_succ_info : context -> info tzresult Lwt.t
 end
 
+(** This module re-exports definitions from {!Vote_repr} and {!Vote_storage}. *)
 module Vote : sig
   type proposal = Protocol_hash.t
 
@@ -2476,7 +2539,8 @@ module Vote : sig
   val clear_current_proposal : context -> context tzresult Lwt.t
 end
 
-(** See {!Sc_rollup_storage} and {!Sc_rollup_repr}. *)
+(** This module re-exports definitions from {!Sc_rollup_storage} and
+    {!Sc_rollup_repr}. *)
 module Sc_rollup : sig
   (** See {!Sc_rollup_tick_repr}. *)
   module Tick : sig
@@ -3060,7 +3124,7 @@ module Sc_rollup : sig
   end
 end
 
-(** This simply re-exports {!Destination_repr}. *)
+(** This module re-exports definitions from {!Destination_repr}. *)
 module Destination : sig
   type t =
     | Contract of Contract.t
@@ -3085,6 +3149,8 @@ module Destination : sig
 end
 
 module Dal : sig
+  (** This module re-exports definitions from {!Dal_endorsement_repr} and
+      {!Raw_context.Dal}. *)
   module Endorsement : sig
     type t
 
@@ -3101,6 +3167,8 @@ module Dal : sig
     val record_available_shards : context -> t -> int list -> context
   end
 
+  (** This module re-exports definitions from {!Dal_slot_repr},
+      {!Dal_slot_storage} and {!Raw_context.Dal}. *)
   module Slot : sig
     type header
 
@@ -3121,6 +3189,7 @@ module Dal : sig
   end
 end
 
+(** This module re-exports definitions from {!Block_payload_repr}. *)
 module Block_payload : sig
   val hash :
     predecessor:Block_hash.t ->
@@ -3129,6 +3198,7 @@ module Block_payload : sig
     Block_payload_hash.t
 end
 
+(** This module re-exports definitions from {!Block_header_repr}. *)
 module Block_header : sig
   type contents = {
     payload_hash : Block_payload_hash.t;
@@ -3231,6 +3301,7 @@ module Block_header : sig
     unit tzresult
 end
 
+(** This module re-exports definitions from {!Lazy_storage_kind}. *)
 module Kind : sig
   type preendorsement_consensus_kind = Preendorsement_consensus_kind
 
@@ -3347,6 +3418,8 @@ module Kind : sig
     | Sc_rollup_recover_bond_manager_kind : sc_rollup_recover_bond manager
 end
 
+(** All the definitions below are re-exported from {!Operation_repr}. *)
+
 type 'a consensus_operation_type =
   | Endorsement : Kind.endorsement consensus_operation_type
   | Preendorsement : Kind.preendorsement consensus_operation_type
@@ -3590,6 +3663,7 @@ type packed_operation = {
 
 val manager_kind : 'kind manager_operation -> 'kind Kind.manager
 
+(** This module re-exports definitions from {!Operation_repr}. *)
 module Operation : sig
   type nonrec 'kind contents = 'kind contents
 
@@ -3816,6 +3890,8 @@ module Operation : sig
   val to_list : packed_contents_list -> packed_contents list
 end
 
+(** This module re-exports definitions from {!Stake_storage},
+    {!Delegate_storage} and {!Delegate}. *)
 module Stake_distribution : sig
   val snapshot : context -> context tzresult Lwt.t
 
@@ -3834,12 +3910,16 @@ module Stake_distribution : sig
     Slot.t ->
     (context * (public_key * public_key_hash)) tzresult Lwt.t
 
+  (** See {!Delegate.pubkey}. *)
   val delegate_pubkey : context -> public_key_hash -> public_key tzresult Lwt.t
 
+  (** See {!Delegate.staking_balance}. *)
   val get_staking_balance :
     context -> Signature.Public_key_hash.t -> Tez.t tzresult Lwt.t
 end
 
+(** This module re-exports definitions from {!Commitment_repr} and,
+    {!Commitment_storage}. *)
 module Commitment : sig
   type t = {
     blinded_public_key_hash : Blinded_public_key_hash.t;
@@ -3849,10 +3929,12 @@ module Commitment : sig
   val encoding : t Data_encoding.t
 end
 
+(** This module re-exports definitions from {!Bootstrap_storage}. *)
 module Bootstrap : sig
   val cycle_end : context -> Cycle.t -> context tzresult Lwt.t
 end
 
+(** This module re-exports definitions from {!Migration_repr}. *)
 module Migration : sig
   type origination_result = {
     balance_updates : Receipt.balance_updates;
@@ -3884,6 +3966,8 @@ val prepare :
   tzresult
   Lwt.t
 
+(** All the definitions below are re-exported from {!Raw_context}. *)
+
 val activate : context -> Protocol_hash.t -> context Lwt.t
 
 val reset_internal_nonce : context -> context
@@ -3896,6 +3980,10 @@ val internal_nonce_already_recorded : context -> int -> bool
 
 val description : context Storage_description.t
 
+val record_non_consensus_operation_hash : context -> Operation_hash.t -> context
+
+val non_consensus_operations : context -> Operation_hash.t list
+
 (** Finalize an {{!t} [Alpha_context.t]}, producing a [validation_result].
  *)
 val finalize :
@@ -3904,10 +3992,7 @@ val finalize :
 (** Should only be used by [Main.current_context] to return a context usable for RPCs *)
 val current_context : context -> Context.t
 
-val record_non_consensus_operation_hash : context -> Operation_hash.t -> context
-
-val non_consensus_operations : context -> Operation_hash.t list
-
+(** This module re-exports definitions from {!Parameters_repr}. *)
 module Parameters : sig
   type bootstrap_account = {
     public_key_hash : public_key_hash;
@@ -3934,6 +4019,8 @@ module Parameters : sig
   val encoding : t Data_encoding.t
 end
 
+(** This module re-exports definitions from {!Liquidity_baking_repr} and
+    {!Liquidity_baking_storage}. *)
 module Liquidity_baking : sig
   type liquidity_baking_toggle_vote =
         Liquidity_baking_repr.liquidity_baking_toggle_vote =
@@ -3963,9 +4050,7 @@ module Liquidity_baking : sig
     (context * 'a list * Toggle_EMA.t) tzresult Lwt.t
 end
 
-(** This module re-exports functions from [Ticket_storage]. See
-    documentation of the functions there.
- *)
+(** This module re-exports definitions from {!Ticket_storage}. *)
 module Ticket_balance : sig
   type error +=
     | Negative_ticket_balance of {key : Ticket_hash.t; balance : Z.t}
@@ -3991,6 +4076,7 @@ module First_level_of_protocol : sig
   val get : context -> Raw_level.t tzresult Lwt.t
 end
 
+(** This module re-exports definitions from {!Raw_context.Consensus}. *)
 module Consensus : sig
   include
     Raw_context.CONSENSUS
@@ -4007,7 +4093,7 @@ module Consensus : sig
     context -> Block_hash.t * Block_payload_hash.t -> context Lwt.t
 end
 
-(** See 'token.mli' for more explanation. *)
+(** This module re-exports definitions from {!Token}. *)
 module Token : sig
   type container =
     [ `Contract of Contract.t
@@ -4060,6 +4146,7 @@ module Token : sig
     (context * Receipt.balance_updates) tzresult Lwt.t
 end
 
+(** This module re-exports definitions from {!Fees_storage}. *)
 module Fees : sig
   val record_paid_storage_space :
     context -> Contract.t -> (context * Z.t * Z.t) tzresult Lwt.t
-- 
GitLab


From a3b692681c77ff521a563752078e17c4a752e360 Mon Sep 17 00:00:00 2001
From: Nicolas Ayache <nicolas.ayache@nomadic-labs.com>
Date: Fri, 17 Jun 2022 08:48:59 +0200
Subject: [PATCH 2/3] Proto: Alpha_context docstrings for Internal_for_tests
 modules.

---
 .../lib_protocol/alpha_context.mli            | 30 ++++++++++++++++---
 1 file changed, 26 insertions(+), 4 deletions(-)

diff --git a/src/proto_alpha/lib_protocol/alpha_context.mli b/src/proto_alpha/lib_protocol/alpha_context.mli
index 416ec3aa730d..ffb2aa127d91 100644
--- a/src/proto_alpha/lib_protocol/alpha_context.mli
+++ b/src/proto_alpha/lib_protocol/alpha_context.mli
@@ -1025,6 +1025,8 @@ module Global_constants_storage : sig
     the table. *)
   val expand : t -> Script.expr -> (t * Script.expr) tzresult Lwt.t
 
+  (** This module discloses definitions that are only useful for tests and must
+      not be used otherwise. *)
   module Internal_for_tests : sig
     (** [node_too_large node] returns true if:
       - The number of sub-nodes in the [node]
@@ -1065,6 +1067,8 @@ module Global_constants_storage : sig
   end
 end
 
+(** This module discloses definitions that are only useful for tests and must
+    not be used otherwise. *)
 module Internal_for_tests : sig
   val to_raw : context -> Raw_context.t
 end
@@ -1491,8 +1495,8 @@ module Origination_nonce : sig
   (** See {!Raw_context.unset_origination_nonce}. *)
   val unset : context -> context
 
-  (** This module disclose a type and a function that are only useful for
-      tests. See {!Origination_nonce} for documentation. *)
+  (** This module discloses definitions that are only useful for tests and must
+      not be used otherwise. See {!Origination_nonce}. *)
   module Internal_for_tests : sig
     type t
 
@@ -1536,6 +1540,8 @@ module Ticket_hash : sig
     owner:Script.node ->
     (t * context) tzresult
 
+  (** This module discloses definitions that are only useful for tests and must
+      not be used otherwise. *)
   module Internal_for_tests : sig
     val make_uncarbonated :
       ticketer:Script.node ->
@@ -1663,8 +1669,10 @@ module Contract : sig
     script:Script.t * Lazy_storage.diffs option ->
     context tzresult Lwt.t
 
+  (** This module discloses definitions that are only useful for tests and must
+      not be used otherwise. *)
   module Internal_for_tests : sig
-    (** see [Contract_repr.originated_contract] for documentation *)
+    (** See {!Contract_repr.originated_contract}. *)
     val originated_contract : Origination_nonce.Internal_for_tests.t -> t
 
     val paid_storage_space : context -> t -> Z.t tzresult Lwt.t
@@ -1715,8 +1723,10 @@ module Tx_rollup : sig
 
   module Set : Set.S with type elt = t
 
+  (** This module discloses definitions that are only useful for tests and must
+      not be used otherwise. *)
   module Internal_for_tests : sig
-    (** see [tx_rollup_repr.originated_tx_rollup] for documentation *)
+    (** See {!Tx_rollup_repr.originated_tx_rollup}. *)
     val originated_tx_rollup : Origination_nonce.Internal_for_tests.t -> t
   end
 end
@@ -1806,6 +1816,8 @@ module Tx_rollup_state : sig
 
   val adjust_storage_allocation : t -> delta:Z.t -> (t * Z.t) tzresult
 
+  (** This module discloses definitions that are only useful for tests and must
+      not be used otherwise. *)
   module Internal_for_tests : sig
     val make :
       ?burn_per_byte:Tez.t ->
@@ -2237,6 +2249,8 @@ module Bond_id : sig
 
   val compare : t -> t -> int
 
+  (** This module discloses definitions that are only useful for tests and must
+      not be used otherwise. *)
   module Internal_for_tests : sig
     val fold_on_bond_ids :
       context ->
@@ -2608,6 +2622,8 @@ module Sc_rollup : sig
 
       val of_bytes : string -> t tzresult
 
+      (** This module discloses definitions that are only useful for tests and
+          must not be used otherwise. *)
       module Internal_for_tests : sig
         val to_bytes : t -> string tzresult
       end
@@ -2855,6 +2871,8 @@ module Sc_rollup : sig
 
       val to_bytes : t -> serialized tzresult
 
+      (** This module discloses definitions that are only useful for tests and
+          must not be used otherwise. *)
       module Internal_for_tests : sig
         val of_bytes : string -> t tzresult
       end
@@ -3119,6 +3137,8 @@ module Sc_rollup : sig
 
   val get_boot_sector : context -> t -> string tzresult Lwt.t
 
+  (** This module discloses definitions that are only useful for tests and
+      must not be used otherwise. *)
   module Internal_for_tests : sig
     val originated_sc_rollup : Origination_nonce.Internal_for_tests.t -> t
   end
@@ -4065,6 +4085,8 @@ module Ticket_balance : sig
   val get_balance :
     context -> Ticket_hash.t -> (Z.t option * context) tzresult Lwt.t
 
+  (** This module discloses definitions that are only useful for tests and
+      must not be used otherwise. *)
   module Internal_for_tests : sig
     val used_storage_space : context -> Z.t tzresult Lwt.t
 
-- 
GitLab


From 38ded3d0c3dbe71e4d0ed5bd53e186ca7f1bc544 Mon Sep 17 00:00:00 2001
From: Nicolas Ayache <nicolas.ayache@nomadic-labs.com>
Date: Fri, 17 Jun 2022 11:35:47 +0000
Subject: [PATCH 3/3] Proto: Alpha_context docstrings for definitions inside
 modules.

---
 src/proto_alpha/lib_protocol/alpha_context.mli | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/proto_alpha/lib_protocol/alpha_context.mli b/src/proto_alpha/lib_protocol/alpha_context.mli
index ffb2aa127d91..4b62e4fb4619 100644
--- a/src/proto_alpha/lib_protocol/alpha_context.mli
+++ b/src/proto_alpha/lib_protocol/alpha_context.mli
@@ -968,6 +968,7 @@ module Constants : sig
   val encoding : t Data_encoding.t
 end
 
+(** See the definitions inside the module. *)
 module Global_constants_storage : sig
   type error += Expression_too_deep
 
@@ -1488,6 +1489,7 @@ module Lazy_storage : sig
   val apply : t -> diffs -> (t * Z.t) tzresult Lwt.t
 end
 
+(** See the definitions inside the module. *)
 module Origination_nonce : sig
   (** See {!Raw_context.init_origination_nonce}. *)
   val init : context -> Operation_hash.t -> context
-- 
GitLab