From c7cfdcb4d995f549e369b5fbc1a901bcae79873a Mon Sep 17 00:00:00 2001 From: Pietro Date: Wed, 25 Jul 2018 10:52:31 +0200 Subject: [PATCH] [Doc]: Fix minor warnings and errors in the doc --- docs/whitedoc/michelson.rst | 7 ++----- src/lib_clic/clic.mli | 2 +- src/lib_data_encoding/data_encoding.mli | 26 ++++++++++++------------ vendors/ocaml-hacl/src/hacl.mli | 20 +++++++++--------- vendors/ocaml-secp256k1/src/external.mli | 2 +- 5 files changed, 27 insertions(+), 30 deletions(-) diff --git a/docs/whitedoc/michelson.rst b/docs/whitedoc/michelson.rst index a0480efb9..bac8184cd 100644 --- a/docs/whitedoc/michelson.rst +++ b/docs/whitedoc/michelson.rst @@ -2057,9 +2057,7 @@ The stack type contains both the types of each element in the stack, as well as an optional variable annotation for each element. In this sub-section we note: - ``[]`` for the empty stack ; -- ``@annot (top) : (rest)`` for the stack whose first value has type - ``(top)`` and is annotated with variable annotation ``@annot`` and - whose queue has stack type ``(rest)``. +- ``@annot (top) : (rest)`` for the stack whose first value has type ``(top)`` and is annotated with variable annotation ``@annot`` and whose queue has stack type ``(rest)``. The instructions which do not accept any variable annotations are: @@ -2472,8 +2470,7 @@ Micheline expressions are encoded in JSON like this: list of annotations, including their leading ``@``, ``%`` or ``%`` sign. - ``{ "prim": "pair", "args": [ { "prim": "nat", "args": [] }, { "prim": - "nat", "args": [] } ], "annots": [":t"] }`` + ``{ "prim": "pair", "args": [ { "prim": "nat", "args": [] }, { "prim": "nat", "args": [] } ], "annots": [":t"] }`` As in the concrete syntax, all domain specific constants are encoded as strings. diff --git a/src/lib_clic/clic.mli b/src/lib_clic/clic.mli index 3be6fad01..3959fbfd5 100644 --- a/src/lib_clic/clic.mli +++ b/src/lib_clic/clic.mli @@ -37,7 +37,7 @@ open Error_monad Commands are series of fixed keywords and positional arguments, in order to support command lines close to a natural language. *) -(** {2 Argument parsers. *) +(** {2 Argument parsers.} *) (** The type for argument parsers, used for both positional and optional arguments. diff --git a/src/lib_data_encoding/data_encoding.mli b/src/lib_data_encoding/data_encoding.mli index 09c7b38e5..aee7b803c 100644 --- a/src/lib_data_encoding/data_encoding.mli +++ b/src/lib_data_encoding/data_encoding.mli @@ -126,7 +126,7 @@ module Encoding: sig (** Integer with bounds in a given range. Both bounds are inclusive. - @raise [Invalid_argument] if the bounds are beyond the interval + @raise Invalid_argument if the bounds are beyond the interval [-2^30; 2^30-1]. These bounds are chosen to be compatible with all versions of OCaml. *) @@ -188,7 +188,7 @@ module Encoding: sig If [max_length] is passed and the encoding of elements has fixed size, a {!check_size} is automatically added for earlier rejection. - @raise [Invalid_argument] if the inner encoding is variable. *) + @raise Invalid_argument if the inner encoding is variable. *) val array : ?max_length:int -> 'a encoding -> 'a array encoding (** List combinator. @@ -199,7 +199,7 @@ module Encoding: sig If [max_length] is passed and the encoding of elements has fixed size, a {!check_size} is automatically added for earlier rejection. - @raise [Invalid_argument] if the inner encoding is also variable. *) + @raise Invalid_argument if the inner encoding is also variable. *) val list : ?max_length:int -> 'a encoding -> 'a list encoding (** Provide a transformer from one encoding to a different one. @@ -262,7 +262,7 @@ module Encoding: sig field are 'variable', the first ones should be wrapped with [dynamic_size]. - @raise [Invalid_argument] if more than one field is a variable one. *) + @raise Invalid_argument if more than one field is a variable one. *) val obj1 : 'f1 field -> 'f1 encoding @@ -298,7 +298,7 @@ module Encoding: sig ('f1 * 'f2 * 'f3 * 'f4 * 'f5 * 'f6 * 'f7 * 'f8 * 'f9 * 'f10) encoding (** Create a larger object from the encodings of two smaller ones. - @raise [Invalid_argument] if both arguments are not objects or if both + @raise Invalid_argument if both arguments are not objects or if both tuples contains a variable field.. *) val merge_objs : 'o1 encoding -> 'o2 encoding -> ('o1 * 'o2) encoding @@ -312,7 +312,7 @@ module Encoding: sig are 'variable', the first ones should be wrapped with [dynamic_size]. - @raise [Invalid_argument] if more than one field is a variable one. *) + @raise Invalid_argument if more than one field is a variable one. *) val tup1 : 'f1 encoding -> @@ -355,7 +355,7 @@ module Encoding: sig (** Create a large tuple encoding from two smaller ones. - @raise [Invalid_argument] if both values are not tuples or if both + @raise Invalid_argument if both values are not tuples or if both tuples contains a variable field. *) val merge_tups : 'a1 encoding -> 'a2 encoding -> ('a1 * 'a2) encoding @@ -394,7 +394,7 @@ module Encoding: sig cases. The default is [`Uint8] and you must use a [`Uint16] if you are going to have more than 256 cases. - @raise [Invalid_argument] if it is given the empty list + @raise Invalid_argument if it is given the empty list or if there are more cases than can fit in the tag size. *) val union : ?tag_size:[ `Uint8 | `Uint16 ] -> 't case list -> 't encoding @@ -424,17 +424,17 @@ module Encoding: sig See the preamble for an explanation. *) module Fixed : sig - (** @raises [Invalid_argument] if the argument is less or equal to zero. *) + (** @raises Invalid_argument if the argument is less or equal to zero. *) val string : int -> string encoding - (** @raises [Invalid_argument] if the argument is less or equal to zero. *) + (** @raises Invalid_argument if the argument is less or equal to zero. *) val bytes : int -> MBytes.t encoding (** [add_padding e n] is a padded version of the encoding [e]. In Binary, there are [n] null bytes ([\000]) added after the value encoded by [e]. In JSON, padding is ignored. - @raises [Invalid_argument] if [n <= 0]. *) + @raises Invalid_argument if [n <= 0]. *) val add_padding : 'a encoding -> int -> 'a encoding end @@ -445,11 +445,11 @@ module Encoding: sig val string : string encoding val bytes : MBytes.t encoding - (** @raises [Invalid_argument] if the encoding argument is variable length + (** @raises Invalid_argument if the encoding argument is variable length or may lead to zero-width representation in binary. *) val array : ?max_length:int -> 'a encoding -> 'a array encoding - (** @raises [Invalid_argument] if the encoding argument is variable length + (** @raises Invalid_argument if the encoding argument is variable length or may lead to zero-width representation in binary. *) val list : ?max_length:int -> 'a encoding -> 'a list encoding diff --git a/vendors/ocaml-hacl/src/hacl.mli b/vendors/ocaml-hacl/src/hacl.mli index cfb6d354c..52731cc2e 100644 --- a/vendors/ocaml-hacl/src/hacl.mli +++ b/vendors/ocaml-hacl/src/hacl.mli @@ -59,7 +59,7 @@ module Hash : sig module HMAC_SHA256 : sig val write_hmac : key:Bigstring.t -> msg:Bigstring.t -> Bigstring.t -> unit - (** @raise [Invalid_argument] if argument is less than 32 bytes long *) + (** @raise Invalid_argument if argument is less than 32 bytes long *) val hmac : key:Bigstring.t -> msg:Bigstring.t -> Bigstring.t @@ -83,10 +83,10 @@ module Secretbox : sig val boxzerobytes : int val unsafe_of_bytes : Bigstring.t -> key - (** @raise [Invalid_argument] if argument is not [keybytes] bytes long *) + (** @raise Invalid_argument if argument is not [keybytes] bytes long *) val blit_of_bytes : Bigstring.t -> int -> key - (** @raise [Invalid_argument] if argument is not [keybytes] bytes long *) + (** @raise Invalid_argument if argument is not [keybytes] bytes long *) val genkey : unit -> key @@ -121,16 +121,16 @@ module Box : sig val blit_to_bytes : _ key -> ?pos:int -> Bigstring.t -> unit val unsafe_sk_of_bytes : Bigstring.t -> secret key - (** @raise [Invalid_argument] if argument is not [skbytes] bytes long *) + (** @raise Invalid_argument if argument is not [skbytes] bytes long *) val unsafe_pk_of_bytes : Bigstring.t -> public key - (** @raise [Invalid_argument] if argument is not [pkbytes] bytes long *) + (** @raise Invalid_argument if argument is not [pkbytes] bytes long *) val unsafe_ck_of_bytes : Bigstring.t -> combined key - (** @raise [Invalid_argument] if argument is not [ckbytes] bytes long *) + (** @raise Invalid_argument if argument is not [ckbytes] bytes long *) val of_seed : ?pos:int -> Bigstring.t -> secret key - (** @raise [Invalid_argument] if [pos] is outside the buffer or the buffer + (** @raise Invalid_argument if [pos] is outside the buffer or the buffer is less than [skbytes] bytes long *) val neuterize : secret key -> public key @@ -156,10 +156,10 @@ module Sign : sig val equal : 'a key -> 'a key -> bool val unsafe_sk_of_bytes : Bigstring.t -> secret key - (** @raise [Invalid_argument] if argument is less than [skbytes] bytes long *) + (** @raise Invalid_argument if argument is less than [skbytes] bytes long *) val unsafe_pk_of_bytes : Bigstring.t -> public key - (** @raise [Invalid_argument] if argument is less than [pkbytes] bytes long *) + (** @raise Invalid_argument if argument is less than [pkbytes] bytes long *) val unsafe_to_bytes : _ key -> Bigstring.t (** [unsafe_to_bytes k] is the internal [Bigstring.t] where the key @@ -175,7 +175,7 @@ module Sign : sig (** [sign sk msg buf] writes the signature of [msg] with [sk] at [buf]. - @raises [Invalid_argument] if [buf] is smaller than [bytes] + @raises Invalid_argument if [buf] is smaller than [bytes] bytes long. *) val verify : diff --git a/vendors/ocaml-secp256k1/src/external.mli b/vendors/ocaml-secp256k1/src/external.mli index cdaa8e2a5..41ba1eafc 100644 --- a/vendors/ocaml-secp256k1/src/external.mli +++ b/vendors/ocaml-secp256k1/src/external.mli @@ -180,7 +180,7 @@ module Sign : sig writes signs [msg] with [sk] and writes the signature to [buf] at [?pos]. It returns the number of bytes written (64). - @raise [Invalid_argument] if [buf] is not long enough to contain + @raise Invalid_argument if [buf] is not long enough to contain a signature or signing has failed. *) val write_sign_recoverable : Context.t -> sk:Key.secret Key.t ->