From ee735c33cf6a22043309e79d5f31ae715a4f5d10 Mon Sep 17 00:00:00 2001 From: Benjamin Canou Date: Mon, 4 Jun 2018 17:04:20 +0200 Subject: [PATCH] Alpha: fix typos and fill placeholders in services doc --- docs/doc_gen/rpc_doc.ml | 4 +- .../src/apply_operation_result.ml | 16 ++--- .../lib_protocol/src/delegate_services.ml | 62 ++++++++++++++----- .../lib_protocol/src/delegate_services.mli | 46 +++++++++----- .../lib_protocol/src/helpers_services.ml | 5 +- .../lib_protocol/src/level_repr.ml | 46 +++++++++++--- 6 files changed, 128 insertions(+), 51 deletions(-) diff --git a/docs/doc_gen/rpc_doc.ml b/docs/doc_gen/rpc_doc.ml index 358052777..7a52ebaa8 100644 --- a/docs/doc_gen/rpc_doc.ml +++ b/docs/doc_gen/rpc_doc.ml @@ -164,8 +164,8 @@ module Description = struct let pp_description ppf (service : _ RPC_description.service) = let open RPC_description in (* TODO collect and display arg description (in path and in query) *) - Format.fprintf ppf "%s%a" - (Option.unopt ~default:"" service.description) + Format.fprintf ppf "@[%a@]%a" + Format.pp_print_text (Option.unopt ~default:"" service.description) Query.pp service.query let pp ppf prefix service = diff --git a/src/proto_alpha/lib_protocol/src/apply_operation_result.ml b/src/proto_alpha/lib_protocol/src/apply_operation_result.ml index 7e4d31e8f..306f46cde 100644 --- a/src/proto_alpha/lib_protocol/src/apply_operation_result.ml +++ b/src/proto_alpha/lib_protocol/src/apply_operation_result.ml @@ -12,8 +12,10 @@ open Data_encoding let error_encoding = def "error" - (* FIXME RPC /chains/blocks/head/errors lint*) - ~description:"... FIXME ..." @@ + ~description: + "The full list of RPC errors would be too long to include.\n\ + It is available at RPC `/errors` (GET).\n\ + Errors specific to protocol Alpha have an id that starts with `proto.alpha`." @@ splitted ~json:(conv (fun err -> @@ -655,7 +657,7 @@ let contents_result_list_encoding = | Contents_result_list (Cons_result (o, os)) -> Contents_result o :: to_list (Contents_result_list os) in let rec of_list = function - | [] -> assert false + | [] -> Pervasives.failwith "cannot decode empty operation result" | [Contents_result o] -> Contents_result_list (Single_result o) | (Contents_result o) :: os -> let Contents_result_list os = of_list os in @@ -664,7 +666,7 @@ let contents_result_list_encoding = Contents_result_list (Cons_result (o, os)) | Manager_operation_result _, Cons_result _ -> Contents_result_list (Cons_result (o, os)) - | _ -> Pervasives.failwith "...FIXME..." in + | _ -> Pervasives.failwith "cannot decode ill-formed operation result" in def "operation.alpha.contents_list_result" @@ conv to_list of_list (list contents_result_encoding) @@ -683,7 +685,7 @@ let contents_and_result_list_encoding = Contents_and_result (op, res) :: to_list (Contents_and_result_list rest) in let rec of_list = function - | [] -> assert false (* FIXME error message *) + | [] -> Pervasives.failwith "cannot decode empty combined operation result" | [Contents_and_result (op, res)] -> Contents_and_result_list (Single_and_result (op, res)) | (Contents_and_result (op, res)) :: rest -> @@ -693,7 +695,7 @@ let contents_and_result_list_encoding = Contents_and_result_list (Cons_and_result (op, res, rest)) | Manager_operation _, Cons_and_result (_, _, _) -> Contents_and_result_list (Cons_and_result (op, res, rest)) - | _ -> Pervasives.failwith "...FIXME..." in + | _ -> Pervasives.failwith "cannot decode ill-formed combined operation result" in conv to_list of_list (list contents_and_result_encoding) type 'kind operation_metadata = { @@ -845,7 +847,7 @@ let operation_data_and_metadata_encoding = conv (fun (Operation_data op, Operation_metadata res) -> match kind_equal_list op.contents res.contents with - | None -> assert false (* FIXME *) + | None -> Pervasives.failwith "cannot decode inconsistent combined operation result" | Some Eq -> (Contents_and_result_list (pack_contents_list op.contents res.contents), diff --git a/src/proto_alpha/lib_protocol/src/delegate_services.ml b/src/proto_alpha/lib_protocol/src/delegate_services.ml index 93cfed80d..03d001135 100644 --- a/src/proto_alpha/lib_protocol/src/delegate_services.ml +++ b/src/proto_alpha/lib_protocol/src/delegate_services.ml @@ -65,7 +65,7 @@ module S = struct let list_delegate = RPC_service.get_service ~description: - "List all registred delegates." + "Lists all registered delegates." ~query: list_query ~output: (list Signature.Public_key_hash.encoding) path @@ -110,8 +110,8 @@ module S = struct let staking_balance = RPC_service.get_service ~description: - "Returns the total amount of token delegated to a given delegate. \ - This includes the balance of all the contracts that delegates \ + "Returns the total amount of tokens delegated to a given delegate. \ + This includes the balances of all the contracts that delegate \ to it, but also the balance of the delegate itself and its frozen \ fees and deposits. The rewards do not count in the delegated balance \ until they are unfrozen." @@ -122,7 +122,7 @@ module S = struct let delegated_contracts = RPC_service.get_service ~description: - "Returns the list of contract that delegates to a given delegate." + "Returns the list of contracts that delegate to a given delegate." ~query: RPC_query.empty ~output: (list Contract_hash.encoding) RPC_path.(path / "delegated_contracts") @@ -130,9 +130,9 @@ module S = struct let delegated_balance = RPC_service.get_service ~description: - "The includes the balance of all the contracts that delegates \ - to it. This excludes the delegate own balance and its frozen \ - balances." + "Returns the balances of all the contracts that delegate to a \ + given delegate. This excludes the delegate's own balance and \ + its frozen balances." ~query: RPC_query.empty ~output: Tez.encoding RPC_path.(path / "delegated_balance") @@ -140,7 +140,7 @@ module S = struct let deactivated = RPC_service.get_service ~description: - "Returns whether the delegate is currently tagged as deactivated or not." + "Tells whether the delegate is currently tagged as deactivated or not." ~query: RPC_query.empty ~output: bool RPC_path.(path / "deactivated") @@ -149,11 +149,10 @@ module S = struct RPC_service.get_service ~description: "Returns the cycle by the end of which the delegate might be \ - deactivated, whether should she failed to execute any delegate \ - action until then. \ + deactivated if she fails to execute any delegate action. \ A deactivated delegate might be reactivated \ - (without loosing any rolls) by simply re-register as a delegate. \ - For deactivated delegate this value contains the cycle by which \ + (without loosing any rolls) by simply re-registering as a delegate. \ + For deactivated delegates, this value contains the cycle by which \ they were deactivated." ~query: RPC_query.empty ~output: Cycle.encoding @@ -255,8 +254,6 @@ let requested_levels ~default ctxt cycles levels = | levels, cycles -> (* explicitly fail when requested levels or cycle are in the past... or too far in the future... *) - (* check_levels levels >>=? fun () -> *) - (* check_cycles levels >>=? fun () -> *) let levels = List.sort_uniq Level.compare @@ -293,7 +290,7 @@ module Baking_rights = struct (req "level" Raw_level.encoding) (req "delegate" Signature.Public_key_hash.encoding) (req "priority" uint16) - (opt "timestamp" Timestamp.encoding)) + (opt "estimated_time" Timestamp.encoding)) module S = struct @@ -323,7 +320,24 @@ module Baking_rights = struct let baking_rights = RPC_service.get_service - ~description: "...FIXME..." + ~description: + "Retrieves the list of delegates allowed to bake a block.\n\ + By default, it gives the best baking priorities for bakers \ + that have at least one opportunity below the 64th priority \ + for the next block.\n\ + Parameters `level` and `cycle` can be used to specify the \ + (valid) level(s) in the past or future at which the baking \ + rights have to be returned. Parameter `delegate` can be \ + used to restrict the results to the given delegates. If \ + parameter `all` is set, all the baking opportunities for \ + each baker at each level are returned, instead of just the \ + first one.\n\ + Returns the list of baking slots. Also returns the minimal \ + timestamps that correspond to these slots. The timestamps \ + are omitted for levels in the past, and are only estimates \ + for levels later that the next block, based on the \ + hypothesis that all predecessor blocks were baked at the \ + first priority." ~query: baking_rights_query ~output: (list encoding) custom_root @@ -444,7 +458,21 @@ module Endorsing_rights = struct let endorsing_rights = RPC_service.get_service - ~description: "...FIXME..." + ~description: + "Retrieves the delegates allowed to endorse a block.\n\ + By default, it gives the endorsement slots for bakers that \ + have at least one in the next block.\n\ + Parameters `level` and `cycle` can be used to specify the \ + (valid) level(s) in the past or future at which the \ + endorsement rights have to be returned. Parameter \ + `delegate` can be used to restrict the results to the given \ + delegates.\n\ + Returns the list of endorsement slots. Also returns the \ + minimal timestamps that correspond to these slots. The \ + timestamps are omitted for levels in the past, and are only \ + estimates for levels later that the next block, based on \ + the hypothesis that all predecessor blocks were baked at \ + the first priority." ~query: endorsing_rights_query ~output: (list encoding) custom_root diff --git a/src/proto_alpha/lib_protocol/src/delegate_services.mli b/src/proto_alpha/lib_protocol/src/delegate_services.mli index 56c4cf37d..094cf06d1 100644 --- a/src/proto_alpha/lib_protocol/src/delegate_services.mli +++ b/src/proto_alpha/lib_protocol/src/delegate_services.mli @@ -83,19 +83,24 @@ module Baking_rights : sig timestamp: Timestamp.t option ; } - (** Compute the baking rights. By default, it computes the baking - rights for the next block and only returns the first available - priority for bakers that appears in the 64 first priorities. + (** Retrieves the list of delegates allowed to bake a block. - The optional arguments [levels] and [cycles] allows to compute - baking for an explicit list of levels or for all the levels of the given - cycles. + By default, it gives the best baking priorities for bakers + that have at least one opportunity below the 64th priority for + the next block. - The optional argument [delegates] allows to filter - the non-explicitly listed delegates out of the resulting list. + Parameters [levels] and [cycles] can be used to specify the + (valid) level(s) in the past or future at which the baking rights + have to be returned. Parameter [delegates] can be used to + restrict the results to the given delegates. If parameter [all] + is [true], all the baking opportunities for each baker at each level + are returned, instead of just the first one. - When [all=false], the function only returns the minimal priority - for each delegates. When [all=true], all priorities are returned. *) + Returns the list of baking slots. Also returns the minimal + timestamps that correspond to these slots. The timestamps are + omitted for levels in the past, and are only estimates for levels + later that the next block, based on the hypothesis that all + predecessor blocks were baked at the first priority. *) val get: 'a #RPC_context.simple -> ?levels: Raw_level.t list -> @@ -116,15 +121,22 @@ module Endorsing_rights : sig estimated_time: Timestamp.t option ; } - (** Compute the endorsing rights. By default, it computes the - endorsing rights for the next block. + (** Retrieves the delegates allowed to endorse a block. - The optional arguments [levels] and [cycles] allows to compute - baking for an explicit list of levels or for all the levels of - the given cycles. + By default, it gives the endorsement slots for bakers that have + at least one in the next block. - The optional argument [delegates] allows to filter the - non-explicitly listed delegates out of the resulting list.. *) + Parameters [levels] and [cycles] can be used to specify the + (valid) level(s) in the past or future at which the endorsement + rights have to be returned. Parameter [delegates] can be used to + restrict the results to the given delegates. Returns the list of + endorsement slots. Also returns the minimal timestamps that + correspond to these slots. + + Timestamps are omitted for levels in the past, and are only + estimates for levels later that the next block, based on the + hypothesis that all predecessor blocks were baked at the first + priority. *) val get: 'a #RPC_context.simple -> ?levels: Raw_level.t list -> diff --git a/src/proto_alpha/lib_protocol/src/helpers_services.ml b/src/proto_alpha/lib_protocol/src/helpers_services.ml index 8d2fb3834..c1982e42a 100644 --- a/src/proto_alpha/lib_protocol/src/helpers_services.ml +++ b/src/proto_alpha/lib_protocol/src/helpers_services.ml @@ -433,7 +433,10 @@ module S = struct let current_level = RPC_service.get_service - ~description: "..." + ~description: + "Returns the level of the interrogated block, or the one of a \ + block located `offset` blocks after in the chain (or before \ + when negative). For instance, the next block if `offset` is 1." ~query: level_query ~output: Level.encoding RPC_path.(path / "current_level") diff --git a/src/proto_alpha/lib_protocol/src/level_repr.ml b/src/proto_alpha/lib_protocol/src/level_repr.ml index 5c03f4998..0a3b29841 100644 --- a/src/proto_alpha/lib_protocol/src/level_repr.ml +++ b/src/proto_alpha/lib_protocol/src/level_repr.ml @@ -53,13 +53,45 @@ let encoding = voting_period ; voting_period_position ; expected_commitment }) (obj7 - (req "level" Raw_level_repr.encoding) - (req "level_position" int32) - (req "cycle" Cycle_repr.encoding) - (req "cycle_position" int32) - (req "voting_period" Voting_period_repr.encoding) - (req "voting_period_position" int32) - (req "expected_commitment" bool)) + (req "level" + ~description: + "The level of the block relative to genesis. This is also \ + the Shell's notion of level" + Raw_level_repr.encoding) + (req "level_position" + ~description: + "The level of the block relative to the block that starts \ + protocol alpha. This is specific to the protocol \ + alpha. Other protocols might or might not include a \ + similar notion." + int32) + (req "cycle" + ~description: + "The current cycle's number. Note that cycles are a \ + protocol-specific notion. As a result, the cycle number starts at 0 \ + with the first block of protocol alpha." + Cycle_repr.encoding) + (req "cycle_position" + ~description: + "The current level of the block relative to the first \ + block of the current cycle." + int32) + (req "voting_period" + ~description: + "The current voting period's index. Note that cycles are a \ + protocol-specific notion. As a result, the voting period \ + index starts at 0 with the first block of protocol alpha." + Voting_period_repr.encoding) + (req "voting_period_position" + ~description: + "The current level of the block relative to the first \ + block of the current voting period." + int32) + (req "expected_commitment" + ~description: + "Tells wether the baker of this block has to commit a seed \ + nonce hash." + bool)) let root first_level = { level = first_level ;