[Doc]: Fix minor warnings and errors in the doc

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
+- ``@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)``.
-  ``(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":
+   ``{ "prim": "pair", "args": [ { "prim": "nat", "args": [] }, { "prim": "nat", "args": [] } ], "annots": [":t"] }``
-     "nat", "args": [] } ], "annots": [":t"] }``
 
 As in the concrete syntax, all domain specific constants are encoded as
 strings.

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.

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
 

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 :

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