balsoft/ligo
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Alpha: fix typos and fill placeholders in services doc

Browse Source
This commit is contained in:
Benjamin Canou 2018-06-04 17:04:20 +02:00
parent 2e21a67648
commit ee735c33cf
6 changed files with 128 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/doc_gen/rpc_doc.ml
View File

@ -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 "@[<h>%a@]%a"
Format.pp_print_text (Option.unopt ~default:"" service.description)
Query.pp service.query
let pp ppf prefix service =

16
src/proto_alpha/lib_protocol/src/apply_operation_result.ml
View File

@ -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),

62
src/proto_alpha/lib_protocol/src/delegate_services.ml
View File

@ -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

46
src/proto_alpha/lib_protocol/src/delegate_services.mli
View File

@ -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 ->

5
src/proto_alpha/lib_protocol/src/helpers_services.ml
View File

@ -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")

46
src/proto_alpha/lib_protocol/src/level_repr.ml
View File

@ -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 ;