From c4dfc61905cec3ff02c72082a17867c7571c2ca9 Mon Sep 17 00:00:00 2001 From: Simmo Saan Date: Mon, 15 Apr 2024 11:31:36 +0300 Subject: [PATCH] Fixes for odoc (#1130) * Add missing module copy-s to dune * Fix ambiguous doc comment in BatRandom * Disable non-compiling array_filter bench with dune * Suppress Toploop.directive_table deprecated alert * Add camlp-streams and str to dune build for OCaml 5 compatibility * Fix bench_int compilation with Stdlib * Fix dune inline_tests nor preprocessing, adapt conditional $inject-s * Fix deprecated String.nsplit in BatGc * Suppress unused warnings in qtest * Remove $Id comments which confuse qtest * Split batteries_compattest from dune library * Use test stanza for testsuite * Add title to odoc index * Remove duplicate title from ocamldoc index * Fix BatSys.backend_type @since * Fix module synopses for odoc * Fix most @raise annotations for odoc * Fix @since annotations for odoc * Replace @added and @obsolete tags for odoc * Fix heading levels for odoc * Remove empty heading for odoc * Remove spurious markup for odoc * Fix ul formatting for odoc * Add BatBytes to documentation index * Fix ambiguities for odoc * Revert symbol changes in BatChar documentation --- src/batArray.mli | 42 +++++++++++----------- src/batBig_int.mli | 36 ++++++++++--------- src/batBigarray.mli | 39 +++++++++++--------- src/batBitSet.mli | 8 ++--- src/batBool.mli | 6 ++-- src/batBuffer.mli | 14 ++++---- src/batBytes.mli | 3 +- src/batCache.mli | 1 + src/batChar.mli | 12 +++---- src/batCharParser.mli | 2 +- src/batComplex.mli | 6 ++-- src/batDeque.mli | 10 +++--- src/batDigest.mli | 1 + src/batDllist.mli | 12 +++---- src/batDynArray.mli | 18 +++++----- src/batEnum.mli | 32 ++++++++--------- src/batFile.mli | 10 +++--- src/batFingerTree.mli | 16 ++++----- src/batFloat.mli | 66 ++++++++++++++++++++-------------- src/batFormat.mli | 38 ++++++++++---------- src/batGc.mli | 14 +++++--- src/batGenlex.mli | 10 +++--- src/batHashtbl.mli | 38 ++++++++++---------- src/batHeap.mli | 10 +++--- src/batIMap.mli | 6 ++-- src/batIO.mli | 69 +++++++++++++++++++---------------- src/batInnerIO.mli | 44 ++++++++++++++--------- src/batInnerPervasives.ml | 2 +- src/batInnerWeaktbl.mli | 4 +-- src/batInt.mli | 12 +++---- src/batInt32.mli | 9 ++--- src/batInt64.mli | 8 ++--- src/batLazyList.mli | 69 ++++++++++++++++++++--------------- src/batLexing.mli | 12 +++---- src/batList.mli | 73 +++++++++++++++++++++---------------- src/batLog.mli | 1 + src/batLogger.mli | 12 +++---- src/batMap.mli | 17 ++++----- src/batMarshal.mli | 2 +- src/batMultiMap.mli | 4 +-- src/batMultiPMap.mli | 4 +-- src/batNativeint.mli | 15 ++++---- src/batNum.mli | 18 +++++----- src/batNumber.mli | 14 +++++--- src/batOptParse.mli | 30 ++++++++-------- src/batOption.mli | 6 ++-- src/batParserCo.mli | 16 ++++----- src/batPathGen.mli | 14 ++++---- src/batPervasives.mli | 32 ++++++++--------- src/batPrintexc.mli | 16 ++++----- src/batPrintf.mli | 28 +++++++-------- src/batQueue.mli | 4 +-- src/batRandom.mli | 8 ++--- src/batRef.mli | 2 +- src/batRefList.mli | 4 +-- src/batResult.mli | 12 +++---- src/batScanf.mli | 32 ++++++++--------- src/batSeq.mli | 22 ++++++------ src/batSet.mli | 20 +++++------ src/batStack.mli | 14 ++++---- src/batStream.mli | 30 +++++++++------- src/batString.mli | 52 +++++++++++++-------------- src/batSubstring.mli | 36 ++++++++++++------- src/batSys.mli | 12 ++++--- src/batText.mli | 16 ++++----- src/batUnit.mli | 4 +-- src/batUnix.mli | 76 +++++++++++++++++++++------------------ src/batUref.mli | 2 +- src/batVect.mli | 42 +++++++++++----------- src/index.mld | 17 ++++----- 70 files changed, 749 insertions(+), 637 deletions(-) diff --git a/src/batArray.mli b/src/batArray.mli index d2f065224..224830277 100644 --- a/src/batArray.mli +++ b/src/batArray.mli @@ -20,7 +20,7 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA *) -(** {6 Array operations} +(** Array operations. Arrays are mutable data structures with a fixed size, which support fast access and modification, and are used pervasively in @@ -341,7 +341,7 @@ val singleton : 'a -> 'a array *) -(** {6 Sorting} *) +(** {1 Sorting} *) val sort : ('a -> 'a -> int) -> 'a array -> unit @@ -437,7 +437,7 @@ val pivot_split : 'a BatOrd.ord -> 'a array -> 'a -> int * int *) -(**{6 Operations on two arrays}*) +(**{1 Operations on two arrays}*) val iter2 : ('a -> 'b -> unit) -> 'a array -> 'b array -> unit (** [Array.iter2 f [|a0; a1; ...; an|] [|b0; b1; ...; bn|]] @@ -473,7 +473,7 @@ val cartesian_product : 'a array -> 'b array -> ('a * 'b) array (** Cartesian product of the two arrays. @since 2.2.0 *) -(**{6 Predicates}*) +(**{1 Predicates}*) val for_all : ('a -> bool) -> 'a array -> bool (** [for_all p [|a0; a1; ...; an|]] checks if all elements of the @@ -542,7 +542,7 @@ val partition : ('a -> bool) -> 'a array -> 'a array * 'a array elements of [a] that do not satisfy [p]. The order of the elements in the input array is preserved. *) -(** {6 Array transformations} *) +(** {1 Array transformations} *) val rev : 'a array -> 'a array (** Array reversal.*) @@ -550,7 +550,7 @@ val rev : 'a array -> 'a array val rev_in_place : 'a array -> unit (** In-place array reversal. The array argument is updated. *) -(** {6 Conversions} *) +(** {1 Conversions} *) val enum : 'a array -> 'a BatEnum.t (** Returns an enumeration of the elements of an array. @@ -567,7 +567,7 @@ val of_backwards : 'a BatEnum.t -> 'a array the enumeration as the last element of the array and vice versa. *) -(** {6 Utilities} *) +(** {1 Utilities} *) val range : 'a array -> int BatEnum.t (** [range a] returns an enumeration of all valid indexes into the given @@ -587,7 +587,7 @@ val remove_at : int -> 'a array -> 'a array @raise Invalid_argument if [i] is outside of [a] bounds. @since 3.3.0 *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) val print : ?first:string -> ?last:string -> ?sep:string -> ('a, 'b) BatIO.printer -> ('a t, 'b) BatIO.printer @@ -628,7 +628,7 @@ val equal : 'a BatOrd.eq -> 'a array BatOrd.eq equal if their lengths are the same and corresponding elements test equal. *) -(** {6 Override modules}*) +(** {1 Override modules}*) (** The following modules replace functions defined in {!Array} with functions behaving slightly differently but having the same @@ -722,13 +722,13 @@ sig while a [('a, [`Read]) array] only has read-only capabilities and a [('a, [`Write]) array] only has write-only capabilities.*) - (**{6 Base operations}*) + (**{1 Base operations}*) external length : ('a, [> ]) t -> int = "%array_length" external get : ('a, [> `Read]) t -> int -> 'a = "%array_safe_get" external set : ('a, [> `Write]) t -> int -> 'a -> unit = "%array_safe_set" - (**{6 Constructors}*) + (**{1 Constructors}*) external make : int -> 'a -> ('a, _) t = "caml_make_vect" external create : int -> 'a -> ('a, _) t = "caml_make_vect" @@ -771,7 +771,7 @@ sig val make_matrix : int -> int -> 'a -> (('a, _)t, _) t val create_matrix : int -> int -> 'a -> (('a, _)t, _) t - (** {6 Iterators}*) + (** {1 Iterators}*) val iter : ('a -> unit) -> ('a, [> `Read]) t -> unit val map : ('a -> 'b) -> ('a, [>`Read]) t -> ('b, _) t @@ -784,12 +784,12 @@ sig val fold_right : ('b -> 'a -> 'a) -> ('b, [> `Read]) t -> 'a -> 'a val fold_while : ('acc -> 'a -> bool) -> ('acc -> 'a -> 'acc) -> 'acc -> ('a, [> `Read]) t -> ('acc * int) - (**{6 Operations on two arrays}*) + (**{1 Operations on two arrays}*) val iter2 : ('a -> 'b -> unit) -> ('a, [> `Read]) t -> ('b, [> `Read]) t -> unit val iter2i : (int -> 'a -> 'b -> unit) -> ('a, [> `Read]) t -> ('b, [> `Read]) t -> unit - (**{6 Predicates}*) + (**{1 Predicates}*) val for_all : ('a -> bool) -> ('a, [> `Read]) t -> bool val exists : ('a -> bool) -> ('a, [> `Read]) t -> bool @@ -805,7 +805,7 @@ sig val find_all : ('a -> bool) -> ('a, [> `Read]) t -> ('a, _) t val partition : ('a -> bool) -> ('a, [> `Read]) t -> ('a, _) t * ('a, _)t - (** {6 Array transformations} *) + (** {1 Array transformations} *) val rev : ('a, [> `Read]) t -> ('a, _) t val rev_in_place : ('a, [`Read | `Write]) t -> unit @@ -816,7 +816,7 @@ sig val fill : ('a, [> `Write]) t -> int -> int -> 'a -> unit val blit : ('a, [> `Read]) t -> int -> ('a, [>`Write]) t -> int -> int -> unit - (** {6 Conversions} *) + (** {1 Conversions} *) val enum : ('a, [> `Read]) t -> 'a BatEnum.t val of_enum : 'a BatEnum.t -> ('a, _) t @@ -828,13 +828,13 @@ sig val pivot_split : 'a BatOrd.ord -> ('a, [> `Read]) t -> 'a -> int * int val of_list : 'a list -> ('a, _) t - (** {6 Utilities} *) + (** {1 Utilities} *) val sort : ('a -> 'a -> int) -> ('a, [> `Read | `Write]) t -> unit val stable_sort : ('a -> 'a -> int) -> ('a, [ `Read | `Write]) t -> unit val fast_sort : ('a -> 'a -> int) -> ('a, [`Read | `Write]) t -> unit - (** {6 Boilerplate code}*) + (** {1 Boilerplate code}*) val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatIO.output -> 'b -> unit) -> 'a BatIO.output -> ('b, [>`Read]) t -> unit @@ -842,7 +842,7 @@ sig val ord : 'a BatOrd.ord -> ('a, [> `Read]) t BatOrd.ord val equal : 'a BatOrd.eq -> ('a, [> `Read]) t BatOrd.eq - (** {6 Override modules}*) + (** {1 Override modules}*) (** Operations on {!BatArray.Cap} without exceptions.*) module Exceptionless : sig @@ -888,7 +888,7 @@ sig val count_matching: f:('a -> bool) -> ('a, [>`Read]) t -> int end (**/**) - (** {6 Undocumented functions} *) + (** {1 Undocumented functions} *) external unsafe_get : ('a, [> `Read]) t -> int -> 'a = "%array_unsafe_get" external unsafe_set : ('a, [> `Write])t -> int -> 'a -> unit = "%array_unsafe_set" @@ -910,7 +910,7 @@ end (**/**) -(** {6 Undocumented functions} *) +(** {1 Undocumented functions} *) (* for tests *) val is_sorted_by : ('a -> 'b) -> 'a array -> bool diff --git a/src/batBig_int.mli b/src/batBig_int.mli index f469b3ecc..5ef49c01c 100644 --- a/src/batBig_int.mli +++ b/src/batBig_int.mli @@ -48,7 +48,7 @@ val one : big_int val unit_big_int : big_int (** The big integer [1]. *) -(** {6 Arithmetic operations} *) +(** {1 Arithmetic operations} *) val neg : big_int -> big_int val succ : big_int -> big_int @@ -130,16 +130,18 @@ val power_big_int_positive_big_int: big_int -> big_int -> big_int representing the first argument [a] raised to the power [b] (the second argument). Depending on the function, [a] and [b] can be either small integers - or big integers. @raise Invalid_argument if [b] is negative. *) + or big integers. + + @raise Invalid_argument if [b] is negative. *) val operations : t BatNumber.numeric -(** {6 Generators} *) +(** {1 Generators} *) val ( -- ) : big_int -> big_int -> big_int BatEnum.t val ( --- ): big_int -> big_int -> big_int BatEnum.t -(** {6 Comparisons and tests} *) +(** {1 Comparisons and tests} *) val compare : big_int -> big_int -> int val ord : big_int -> big_int -> BatOrd.order @@ -188,7 +190,7 @@ val num_digits_big_int : big_int -> int ##V>=4.3## @since 2.5.0 and OCaml 4.03 *) -(** {6 Conversions to and from strings} *) +(** {1 Conversions to and from strings} *) val to_string : big_int -> string val string_of_big_int : big_int -> string @@ -222,8 +224,9 @@ val to_string_in_base : int -> big_int -> string (** [to_string_in_base b n] returns the string representation in base [b] of the given big integer [n]. Should you have advanced needs (arbitrarily large bases, or custom digits instead of the usual [0,1,...9,a,b,...,z]), use - [to_string_in_custom_base] instead. @raise Invalid_argument if b is not in - [2 .. 36]. *) + [to_string_in_custom_base] instead. + + @raise Invalid_argument if b is not in [2 .. 36]. *) val to_string_in_custom_base : string -> int -> big_int -> string (** First argument, called [symbols], is the vector of the symbols used to @@ -233,8 +236,9 @@ val to_string_in_custom_base : string -> int -> big_int -> string provided that [symbols] can accommodate it. Concretely, the base [b] must be at least [2], and [symbols] must be of size at least [b]. The default value of [big_int_base_default_symbols] contains 62 symbols, as it uses lowercase and - uppercase letters both. See below for more information. @raise Invalid_argument - if [b] is incorrect. *) + uppercase letters both. See below for more information. + + @raise Invalid_argument if [b] is incorrect. *) val big_int_base_default_symbols : string @@ -252,7 +256,7 @@ val big_int_base_default_symbols : string *) -(** {6 Conversions to and from other numerical types} *) +(** {1 Conversions to and from other numerical types} *) val of_int : int -> big_int @@ -335,7 +339,7 @@ val of_float: float -> big_int val to_float: big_int -> float -(** {6 Bit-oriented operations} *) +(** {1 Bit-oriented operations} *) val and_big_int : big_int -> big_int -> big_int (** Bitwise logical ``and''. @@ -372,14 +376,14 @@ val extract_big_int : big_int -> int -> int -> big_int a two's complement representation is used. *) -(** {6 Submodules grouping all infix operators} *) +(** {1 Submodules grouping all infix operators} *) module Infix : BatNumber.Infix with type bat__infix_t = t module Compare : BatNumber.Compare with type bat__compare_t = t (**/**) -(** {6 For internal use} *) +(** {1 For internal use} *) val nat_of_big_int : big_int -> Nat.nat val big_int_of_nat : Nat.nat -> big_int val base_power_big_int: int -> int -> big_int -> big_int @@ -388,7 +392,7 @@ val round_futur_last_digit : Bytes.t -> int -> int -> bool val approx_big_int: int -> big_int -> string ##V>=4.3##val round_big_int_to_float: big_int -> bool -> float -(** {6 Obsolete}*) +(** {1 Obsolete}*) val zero_big_int : big_int (** The big integer [0]. *) @@ -432,8 +436,8 @@ val gcd_big_int : big_int -> big_int -> big_int (**/**) -(** {6 Boilerplate code} *) +(** {1 Boilerplate code} *) -(** {7 Printing} *) +(** {2 Printing} *) val print : 'a BatIO.output -> t -> unit diff --git a/src/batBigarray.mli b/src/batBigarray.mli index 5f12c1d65..a001f6d00 100644 --- a/src/batBigarray.mli +++ b/src/batBigarray.mli @@ -51,7 +51,7 @@ @author David Teller *) -(** {6 Element kinds} *) +(** {1 Element kinds} *) (** Big arrays can contain elements of the following kinds: - IEEE single precision (32 bits) floating-point numbers @@ -220,7 +220,7 @@ val kind_size_in_bytes : ('a, 'b) kind -> int @since 2.5.0 *) -(** {6 Array layouts} *) +(** {1 Array layouts} *) type c_layout = Bigarray.c_layout ##V>=4.2## = C_layout_typ (**) @@ -258,7 +258,7 @@ type 'a layout = 'a Bigarray.layout if ['a] is {!Bigarray.fortran_layout}. *) -(** {7 Supported layouts} +(** {2 Supported layouts} The abstract values [c_layout] and [fortran_layout] represent the two supported layouts at the level of values. @@ -562,7 +562,7 @@ sig end -##V>=4.5##(** {6 Zero-dimensional arrays} *) +##V>=4.5##(** {1 Zero-dimensional arrays} *) ##V>=4.5## ##V>=4.5##(** Zero-dimensional arrays. The [Array0] structure provides operations ##V>=4.5## similar to those of {!Bigarray.Genarray}, but specialized to the case @@ -619,7 +619,7 @@ end ##V>=4.5##end -(** {6 One-dimensional arrays} *) +(** {1 One-dimensional arrays} *) (** One-dimensional arrays. The [Array1] structure provides operations similar to those of @@ -752,7 +752,7 @@ module Array1 : sig given big array. *) - (**{6 Unsafe operations} + (**{1 Unsafe operations} In case of doubt, don't use them.*) @@ -771,7 +771,7 @@ module Array1 : sig end -(** {6 Two-dimensional arrays} *) +(** {1 Two-dimensional arrays} *) (** Two-dimensional arrays. The [Array2] structure provides operations similar to those of {!Bigarray.Genarray}, but specialized to the @@ -912,7 +912,7 @@ sig (** Build a two-dimensional array initialized from the given big array. *) - (**{6 Unsafe operations} + (**{1 Unsafe operations} In case of doubt, don't use them.*) @@ -929,7 +929,7 @@ sig end -(** {6 Three-dimensional arrays} *) +(** {1 Three-dimensional arrays} *) (** Three-dimensional arrays. The [Array3] structure provides operations similar to those of {!Bigarray.Genarray}, but specialized to the case @@ -1095,7 +1095,7 @@ sig (** Build a three-dimensional array initialized from the given big array. *) - (**{6 Unsafe operations} + (**{1 Unsafe operations} In case of doubt, don't use them.*) @@ -1112,12 +1112,13 @@ sig end -(** {6 Coercions between generic big arrays and fixed-dimension big arrays} *) +(** {1 Coercions between generic big arrays and fixed-dimension big arrays} *) ##V>=4.5##external genarray_of_array0 : ##V>=4.5## ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genarray.t = "%identity" ##V>=4.5##(** Return the generic big array corresponding to the given zero-dimensional -##V>=4.5## big array. @since 2.7.0 and OCaml 4.05.0 *) +##V>=4.5## big array. +##V>=4.5## @since 2.7.0 and OCaml 4.05.0 *) external genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genarray.t = "%identity" @@ -1142,21 +1143,27 @@ external genarray_of_array3 : val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array1.t (** Return the one-dimensional big array corresponding to the given - generic big array. @raise Invalid_argument if the generic big array + generic big array. + + @raise Invalid_argument if the generic big array does not have exactly one dimension. *) val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array2.t (** Return the two-dimensional big array corresponding to the given - generic big array. @raise Invalid_argument if the generic big array + generic big array. + + @raise Invalid_argument if the generic big array does not have exactly two dimensions. *) val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array3.t (** Return the three-dimensional big array corresponding to the given - generic big array. @raise Invalid_argument if the generic big array + generic big array. + + @raise Invalid_argument if the generic big array does not have exactly three dimensions. *) -(** {6 Re-shaping big arrays} *) +(** {1 Re-shaping big arrays} *) val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c) Genarray.t (** [reshape b [|d1;...;dN|]] converts the big array [b] to a diff --git a/src/batBitSet.mli b/src/batBitSet.mli index 04c07c25e..b1b690269 100644 --- a/src/batBitSet.mli +++ b/src/batBitSet.mli @@ -92,7 +92,7 @@ val next_set_bit : t -> int -> int option @raise Invalid_argument on negative index ([n < 0]) *) -(** {6 In-place Update} *) +(** {1 In-place Update} *) (** These functions modify an existing bitset. *) @@ -129,7 +129,7 @@ val differentiate_sym : t -> t -> unit (** [differentiate_sym s t] sets [s] to the symmetrical difference of the sets [s] and [t]. *) -(** {6 Return new bitset} *) +(** {1 Return new bitset} *) (** These functions return a new bitset that shares nothing with the input bitset. This is not as efficient as the in-place update. *) @@ -156,7 +156,7 @@ val diff : t -> t -> t val sym_diff : t -> t -> t (** [sym_diff s t] returns the symmetrical difference of [s] and [t]. *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) val print: 'a BatInnerIO.output -> t -> unit (* Print the given BitSet to the given output channel. This @@ -193,7 +193,7 @@ val ord : t -> t -> BatOrd.order (** [ord s1 s2] returns [BatOrd.Lt], [BatOrd.Eq] or [BatOrd.Gt] if [compare s1 s2] is, respectively, [< 0], [0] or [> 0]. *) -(** {6 Internals} *) +(** {1 Internals} *) val capacity : t -> int (** [capacity s] returns the number of bits, both set and unset, stored in [s]. This is guaranteed to be larger than the largest element diff --git a/src/batBool.mli b/src/batBool.mli index 1290169a4..5b507844b 100644 --- a/src/batBool.mli +++ b/src/batBool.mli @@ -93,12 +93,12 @@ val operations : t BatNumber.numeric include BatNumber.Bounded -(** {6 Submodules grouping all infix operators} *) +(** {1 Submodules grouping all infix operators} *) module Infix : BatNumber.Infix with type bat__infix_t = t module Compare : BatNumber.Compare with type bat__compare_t = t -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print: 'a BatInnerIO.output -> t -> unit diff --git a/src/batBuffer.mli b/src/batBuffer.mli index 24e3d03b3..a37b1f80b 100644 --- a/src/batBuffer.mli +++ b/src/batBuffer.mli @@ -81,8 +81,9 @@ val blit : t -> int -> Bytes.t -> int -> int -> unit *) val nth : t -> int -> char -(** get the n-th character of the buffer. @raise Invalid_argument if - index out of bounds *) +(** get the n-th character of the buffer. + + @raise Invalid_argument if index out of bounds *) val length : t -> int (** Return the number of characters currently contained in the buffer. *) @@ -142,11 +143,12 @@ val add_buffer : t -> t -> unit val add_input : t -> BatInnerIO.input -> int -> unit (** [add_input b ic n] reads exactly [n] character from the input [ic] - and stores them at the end of buffer [b]. @raise End_of_file if - the channel contains fewer than [n] characters. *) + and stores them at the end of buffer [b]. + + @raise End_of_file if the channel contains fewer than [n] characters. *) val add_channel : t -> BatInnerIO.input -> int -> unit -(** @obsolete replaced by {!add_input}*) +(** @deprecated replaced by {!add_input}*) val output_buffer : t -> string BatInnerIO.output (** [output_buffer b] creates an output channel that writes to that @@ -178,7 +180,7 @@ val output_buffer : t -> string BatInnerIO.output ##V>=4.6## ##V>=4.6## @since 2.8.0 and OCaml 4.06.0 *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) val enum : t -> char BatEnum.t (** Returns an enumeration of the characters of a buffer. *) diff --git a/src/batBytes.mli b/src/batBytes.mli index e6cd824ed..08fd75ff7 100644 --- a/src/batBytes.mli +++ b/src/batBytes.mli @@ -574,7 +574,8 @@ let s = Bytes.of_string "hello" ##V>=4.08## ##V>=4.08## 8-bit and 16-bit integers are represented by the [int] type, ##V>=4.08## which has more bits than the binary encoding. These extra bits -##V>=4.08## are handled as follows: {ul +##V>=4.08## are handled as follows: +##V>=4.08## {ul ##V>=4.08## {- Functions that decode signed (resp. unsigned) 8-bit or 16-bit ##V>=4.08## integers represented by [int] values sign-extend ##V>=4.08## (resp. zero-extend) their result.} diff --git a/src/batCache.mli b/src/batCache.mli index 076340379..79092436a 100644 --- a/src/batCache.mli +++ b/src/batCache.mli @@ -43,6 +43,7 @@ bindings as pairs. This allows inspection of what is currently cached. *) + type ('a,'b) manual_cache = { get : 'a -> 'b; del : 'a -> unit; diff --git a/src/batChar.mli b/src/batChar.mli index 347b04ced..1da834886 100644 --- a/src/batChar.mli +++ b/src/batChar.mli @@ -81,14 +81,14 @@ val is_lowercase : char -> bool val is_uppercase_latin1: char -> bool (** Determine if a character is uppercase Latin 1. A character is uppercase Latin 1 if it is between - ['A'] and ['Z'], between [''] and [''] or - between [''] and [''] *) + ['A'] and ['Z'], between ['À'] and ['Ö'] or + between ['Ø'] and ['Ý'] *) val is_lowercase_latin1: char -> bool (** Determine if a character is lowercase Latin 1. A character is lowercase Latin 1 if it is between - ['a'] and ['z'], between [''] and [''] or - between [''] and ['']*) + ['a'] and ['z'], between ['Þ'] and ['ö'] or + between ['ø'] and ['ÿ']*) val is_latin1: char -> bool (** Determine if a character is a Latin 1 letter. @@ -132,12 +132,12 @@ val ( -- ): char -> char -> char BatEnum.t ['a' -- 'z'] is the enumeration of all characters between ['a'] and ['z'] included.*) -(** {6 Infix submodule regrouping all infix operators} *) +(** {1 Infix submodule regrouping all infix operators} *) module Infix : sig val ( -- ): char -> char -> char BatEnum.t end -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) val print: 'a BatInnerIO.output -> Char.t -> unit diff --git a/src/batCharParser.mli b/src/batCharParser.mli index 52c00d8fb..930565898 100644 --- a/src/batCharParser.mli +++ b/src/batCharParser.mli @@ -55,7 +55,7 @@ val source_of_enum : char BatEnum.t -> (char, position) Source.t val parse : (char, 'a, position) t -> string -> ('a, position report) BatPervasives.result (**Apply a parser to a string.*) -(**{6 Utilities}*) +(**{1 Utilities}*) val char : char -> (char, char, position) t (** Recognize exactly one char*) diff --git a/src/batComplex.mli b/src/batComplex.mli index 8237d82cb..604f94803 100644 --- a/src/batComplex.mli +++ b/src/batComplex.mli @@ -160,12 +160,12 @@ val of_float : float -> t val to_float : t -> float (** [Complex.to_float (a+bi)] returns the float [a] *) -(** {6 Submodules grouping all infix operators} *) +(** {1 Submodules grouping all infix operators} *) module Infix : BatNumber.Infix with type bat__infix_t = t module Compare : BatNumber.Compare with type bat__compare_t = t -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print: 'a BatInnerIO.output -> t -> unit diff --git a/src/batDeque.mli b/src/batDeque.mli index d63dd96f2..1da5087ea 100644 --- a/src/batDeque.mli +++ b/src/batDeque.mli @@ -32,7 +32,7 @@ include BatInterfaces.Mappable with type 'a mappable = 'a t val size : 'a dq -> int (** [size dq] is the number of elements in the [dq]. O(1) *) -(** {6 Construction} *) +(** {1 Construction} *) val empty : 'a dq (** The empty deque. *) @@ -43,7 +43,7 @@ val cons : 'a -> 'a dq -> 'a dq val snoc : 'a dq -> 'a -> 'a dq (** [snoc x dq] adds [x] to the rear of [dq]. O(1) *) -(** {6 Deconstruction} *) +(** {1 Deconstruction} *) val front : 'a dq -> ('a * 'a dq) option (** [front dq] returns [Some (x, dq')] iff [x] is at the front of @@ -55,7 +55,7 @@ val rear : 'a dq -> ('a dq * 'a) option and [dq'] is the rest of [dq] excluding [x], and [None] if [dq] has no elements. O(1) amortized, O(n) worst case *) -(** {6 Basic operations} *) +(** {1 Basic operations} *) val eq : ?eq:('a -> 'a -> bool) -> 'a dq -> 'a dq -> bool (** [eq dq1 dq2] is true if [dq1] and [dq2] have the same sequence @@ -133,7 +133,7 @@ val rotate_backward : 'a dq -> 'a dq @since 2.3.0 *) -(** {6 Transformation} *) +(** {1 Transformation} *) val of_list : 'a list -> 'a dq (** [of_list l] is a deque representation of the elements of [l]. @@ -154,7 +154,7 @@ val enum : 'a dq -> 'a BatEnum.t is amortized O(1), and O(n) worst case. *) -(** {6 Printing} *) +(** {1 Printing} *) val print : ?first:string -> ?last:string -> ?sep:string -> ('a, 'b) BatIO.printer -> ('a dq, 'b) BatIO.printer diff --git a/src/batDigest.mli b/src/batDigest.mli index 13ce62cfc..30d563300 100644 --- a/src/batDigest.mli +++ b/src/batDigest.mli @@ -30,6 +30,7 @@ @author Xavier Leroy (Base module) @author David Rajchenbach-Teller *) + open BatIO type t = string diff --git a/src/batDllist.mli b/src/batDllist.mli index a89e9ba43..aacd4bc8a 100644 --- a/src/batDllist.mli +++ b/src/batDllist.mli @@ -44,7 +44,7 @@ include BatEnum.Enumerable with type 'a enumerable = 'a t exception Empty -(** {6 node functions } *) +(** {1 node functions } *) (** Creates a node. This is an O(1) operation. *) val create : 'a -> 'a node_t @@ -168,7 +168,7 @@ val find : ('a -> bool) -> 'a node_t -> 'a node_t returns true. @raise Not_found if no such element exists - @added 1.4.0 + @since 1.4.0 *) val for_all : ('a -> bool) -> 'a node_t -> bool @@ -203,7 +203,7 @@ val filter_map : ('a -> 'b option) -> 'a node_t -> 'b node_t @raise Empty if the resulting list is empty.*) -(** {6 list conversion } *) +(** {1 list conversion } *) (** Converts a dllist to a normal list. This is an O(N) operation. *) val to_list : 'a node_t -> 'a list @@ -214,7 +214,7 @@ val to_list : 'a node_t -> 'a list val of_list : 'a list -> 'a node_t -(** {6 enums } *) +(** {1 enums } *) (** Create an enum of the list. Note that modifying the list while the enum exists will have undefined @@ -246,9 +246,9 @@ val backwards : 'a node_t -> 'a BatEnum.t *) val of_enum : 'a BatEnum.t -> 'a node_t -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string ->('a BatInnerIO.output -> 'b -> unit) -> 'a BatInnerIO.output -> 'b t -> unit diff --git a/src/batDynArray.mli b/src/batDynArray.mli index fcf4b3683..0e078457e 100644 --- a/src/batDynArray.mli +++ b/src/batDynArray.mli @@ -47,7 +47,7 @@ exception Invalid_arg of int * string * string contains the parameter name that made the operation fail. *) -(** {6 Array creation} *) +(** {1 Array creation} *) val create : unit -> 'a t (** [create()] returns a new empty dynamic array. *) @@ -68,7 +68,7 @@ val singleton : 'a -> 'a t (** Create an array consisting of exactly one element. @since 3.3.0 *) -(** {6 Array manipulation functions} *) +(** {1 Array manipulation functions} *) val get : 'a t -> int -> 'a (** [get darr idx] gets the element in [darr] at index [idx]. If [darr] has @@ -187,7 +187,7 @@ val compact : 'a t -> unit -(** {6 Array copy and conversion} *) +(** {1 Array copy and conversion} *) val enum : 'a t -> 'a BatEnum.t (** [enum darr] returns the enumeration of [darr] elements. *) @@ -256,7 +256,7 @@ val combine : 'a t -> 'b t -> ('a * 'b) t -(** {6 Array functional support} *) +(** {1 Array functional support} *) val iter : ('a -> unit) -> 'a t -> unit (** [iter f darr] calls the function [f] on every element of [darr]. It @@ -461,7 +461,7 @@ val favg : float t -> float -(** {6 Operations on two arrays} *) +(** {1 Operations on two arrays} *) val iter2 : ('a -> 'b -> unit) -> 'a t -> 'b t -> unit (** [iter2 f [a0, a1, ..., an] [b0, b1, ..., bn]] @@ -509,7 +509,7 @@ val cartesian_product : 'a t -> 'b t -> ('a * 'b) t -(** {6 Array resizers} *) +(** {1 Array resizers} *) type resizer_t = currslots:int -> oldlength:int -> newlength:int -> int (** The type of a resizer function. @@ -619,7 +619,7 @@ val create_with : resizer_t -> 'a t *) -(** {6 Unsafe operations} **) +(** {1 Unsafe operations} **) val unsafe_get : 'a t -> int -> 'a val unsafe_set : 'a t -> int -> 'a -> unit @@ -627,9 +627,9 @@ val unsafe_upd : 'a t -> int -> ('a -> 'a) -> unit (** @since 3.3.0 *) -(** {6 Boilerplate code} *) +(** {1 Boilerplate code} *) -(** {7 Printing} *) +(** {2 Printing} *) val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'b -> unit) -> 'a BatInnerIO.output -> 'b t -> unit diff --git a/src/batEnum.mli b/src/batEnum.mli index 6af55f74c..a21e4dfb6 100644 --- a/src/batEnum.mli +++ b/src/batEnum.mli @@ -81,7 +81,7 @@ include Enumerable with type 'a enumerable = 'a t include BatInterfaces.Mappable with type 'a mappable = 'a t -(** {6 Final functions} +(** {1 Final functions} These functions consume the enumeration until it ends or an exception is raised by the first @@ -167,7 +167,7 @@ val foldi : (int -> 'a -> 'b -> 'b) -> 'b -> 'a t -> 'b val fold2i : (int -> 'a -> 'b -> 'c -> 'c) -> 'c -> 'a t -> 'b t -> 'c -(** {6 Useful functions} *) +(** {1 Useful functions} *) val find : ('a -> bool) -> 'a t -> 'a (** [find f e] returns the first element [x] of [e] such that [f x] returns @@ -301,7 +301,7 @@ val cartesian_product : 'a t -> 'b t -> ('a * 'b) t returned) @since 2.2.0 *) -(** {6 Lazy constructors} +(** {1 Lazy constructors} These functions are lazy which means that they will create a new modified enumeration without actually enumerating any element until they are asked @@ -389,7 +389,7 @@ val concat_map : ('a -> 'b t) -> 'a t -> 'b t [concat_map f e] is the same as [concat (map f e)]. @since 2.2.0 *) -(** {6 Constructors} +(** {1 Constructors} In this section the word {i shall} denotes a semantic requirement. The correct operation of the functions in this @@ -523,11 +523,11 @@ val of_enum : 'a t -> 'a t val combination : ?repeat:bool -> int -> int -> int list t (** [combination n k] returns an enumeration over combination of [k] elements between [n] distincts elements. - + If [repeat] is true, the combination may contain the same elements many times.*) -(** {6 Counting} *) +(** {1 Counting} *) val count : 'a t -> int (** [count e] returns the number of remaining elements in [e] without @@ -554,7 +554,7 @@ val hard_count : 'a t -> int lines in a file).*) (** - {6 Utilities } + {1 Utilities } *) val range : ?until:int -> int -> int t @@ -571,7 +571,7 @@ val combine : 'a t -> 'b t -> ('a * 'b) t (** [combine] transform two streams into a stream of pairs of corresponding elements. If one stream is shorter, excess elements of the longer stream are ignored. - Curried @since 3.0 + @since 3.0 curried *) val uncombine : ('a * 'b) t -> 'a t * 'b t @@ -623,7 +623,7 @@ val switch : ('a -> bool) -> 'a t -> 'a t * 'a t val partition : ('a -> bool) -> 'a t -> 'a t * 'a t (** as [switch] - @added v1.4.0 + @since 1.4.0 *) (*val switchn: int -> ('a -> int) -> 'a t -> 'a t array @@ -641,11 +641,11 @@ val arg_max : ('a -> 'b) -> 'a t -> 'a Example: [-5 -- 5 |> arg_min (fun x -> x * x + 6 * x - 5) = -3] Example: [List.enum ["cat"; "canary"; "dog"; "dodo"; "ant"; "cow"] |> arg_max String.length = "canary"] - @added v1.4.0 + @since 1.4.0 @raise Invalid_argument if the input enum is empty *) -(** {6 Trampolining} *) +(** {1 Trampolining} *) val while_do : ('a -> bool) -> ('a t -> 'a t) -> 'a t -> 'a t (** [while_do cont f e] is a loop on [e] using [f] as body and [cont] as @@ -659,7 +659,7 @@ val while_do : ('a -> bool) -> ('a t -> 'a t) -> 'a t -> 'a t corresponding element has been added to the result stream. *) -(** {6 Infix operators} *) +(** {1 Infix operators} *) (** Infix versions of some functions @@ -733,7 +733,7 @@ val ( @/ ) : ('a -> 'b) -> 'a t -> 'b t val ( //@ ) : 'a t -> ('a -> 'b option) -> 'b t val ( @// ) : ('a -> 'b option) -> 'a t -> 'b t -(** {6 Monad related modules} *) +(** {1 Monad related modules} *) (** Monadic operations on Enumerations containing monadic elements @@ -770,7 +770,7 @@ module Monad : sig end -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'b -> unit) -> 'a BatInnerIO.output -> 'b t -> unit (** Print and consume the contents of an enumeration.*) @@ -809,7 +809,7 @@ val equal : ('a -> 'a -> bool) -> 'a t -> 'a t -> bool the same sequence of elements. *) -(** {6 Override modules}*) +(** {1 Override modules}*) (** The following modules replace functions defined in {!BatEnum} with functions @@ -873,7 +873,7 @@ end (**/**) -(** {6 For system use only, not for the casual user} +(** {1 For system use only, not for the casual user} For compatibility with {!Stream} *) diff --git a/src/batFile.mli b/src/batFile.mli index c8f80b518..1a6b1aefb 100644 --- a/src/batFile.mli +++ b/src/batFile.mli @@ -27,7 +27,7 @@ open BatInnerIO -(** {6 Utilities} *) +(** {1 Utilities} *) val lines_of : string -> string BatEnum.t (** [lines_of name] reads the contents of file [name] as an enumeration of lines. @@ -51,7 +51,7 @@ val size_of_big: string -> Int64.t This function is provided as the size of a file larger than 1 Gb cannot be represented with an [int] on a 32-bit machine.*) -(** {6 File permissions} +(** {1 File permissions} File permissions are used when creating a file to allow controlling which users may read, write or open that file. To use a permission, create a value of type @@ -115,7 +115,7 @@ val set_permissions: string -> permission -> unit val chmod: string -> permission -> unit (** As {!set_permissions}*) -(** {6 Opening a file for reading} *) +(** {1 Opening a file for reading} *) type open_in_flag = [ `create @@ -140,7 +140,7 @@ val with_file_in : ?mode:(open_in_flag list) -> ?perm:permission -> string -> (i invokes [f] to process the contents of that file then, once [f] has returned or triggered an exception, closes the file before proceeding. *) -(** {6 Opening a file for writing} *) +(** {1 Opening a file for writing} *) type open_out_flag = [ `append (**Start writing at the end of the file rather than the start *) @@ -170,7 +170,7 @@ val with_file_out: ?mode:(open_out_flag list) -> ?perm:permission -> string -> ( invokes [f] to write onto that file then, once [f] has returned or triggered an exception, closes the file before proceeding. *) -(** {6 Opening a temporary file for writing} *) +(** {1 Opening a temporary file for writing} *) type open_temporary_out_flag = [ open_out_flag diff --git a/src/batFingerTree.mli b/src/batFingerTree.mli index bd58376b8..e67f3a7a1 100644 --- a/src/batFingerTree.mli +++ b/src/batFingerTree.mli @@ -73,7 +73,7 @@ sig ['wrapped_type]. *) - (** {6 Construction} *) + (** {1 Construction} *) val empty : ('a, 'm) fg (** [empty] is the sequence with no elements. *) @@ -97,7 +97,7 @@ sig O(1) amortized, O(log(n)) worst case. *) - (** {6 Deconstruction} *) + (** {1 Deconstruction} *) val front : (('a, 'm) fg -> (('a, 'm) fg * 'a) option, 'a, 'm) wrap (** [front t] returns [None] when [t] is empty, @@ -193,7 +193,7 @@ sig O(1) amortized, O(log(n)) worst case. *) - (** {6 Inspection} *) + (** {1 Inspection} *) val size : ('a, 'm) fg -> int (** [size t] returns the number of elements in the sequence. @@ -246,9 +246,9 @@ sig O(n). *) - (** {6 Conversions} *) + (** {1 Conversions} *) - (** {7 Conversions to other structures} *) + (** {2 Conversions to other structures} *) val enum : ('a, 'm) fg -> 'a BatEnum.t (** [enum t] builds an enumeration of the elements of [t] going from @@ -277,7 +277,7 @@ sig O(n). *) - (** {7 Conversions from other structures} *) + (** {2 Conversions from other structures} *) val of_enum : ('a BatEnum.t -> ('a, 'm) fg, 'a, 'm) wrap (** [of_enum e] build the sequence containing the elements of [e] @@ -305,7 +305,7 @@ sig O(n). *) - (** {6 Combining/reorganizing} *) + (** {1 Combining/reorganizing} *) val map : (('a -> 'b) -> ('a, 'm) fg -> ('b, 'm) fg, 'b, 'm) wrap (** [map] is equivalent to {!List.map}. @@ -331,7 +331,7 @@ sig O(n). *) - (** {6 Boilerplate code} *) + (** {1 Boilerplate code} *) val print : ?first:string -> ?last:string -> ?sep:string -> ('a, 'b) BatIO.printer -> (('a, _) fg,'b) BatIO.printer diff --git a/src/batFloat.mli b/src/batFloat.mli index 8b73c71da..a627d5d02 100644 --- a/src/batFloat.mli +++ b/src/batFloat.mli @@ -51,7 +51,7 @@ type t = float real numbers by OCaml. *) (** - {6 Usual operations} + {1 Usual operations} *) val zero : float @@ -124,7 +124,7 @@ val ( --- ): t -> t -> t BatEnum.t val operations : t BatNumber.numeric (** - {6 Operations specific to floating-point numbers} + {1 Operations specific to floating-point numbers} *) external sqrt : float -> float = "caml_sqrt_float" "sqrt" @@ -253,10 +253,12 @@ val round_to_string : ?digits:int -> float -> string be imaginary *) val root: float -> int -> float -(** @return True if the sign bit of [x] is set. This usually indicates thet [x] is negative. @since 2.0*) +(** @return True if the sign bit of [x] is set. This usually indicates thet [x] is negative. + @since 2.0*) val signbit: float -> bool -(** [copysign x y] returns a copy of [x] with the same sign as [y]. @since 2.0*) +(** [copysign x y] returns a copy of [x] with the same sign as [y]. + @since 2.0*) val copysign: float -> float -> float val is_nan : float -> bool @@ -274,7 +276,7 @@ val is_finite : float -> bool @since 2.0 *) -(** {6 Constants} *) +(** {1 Constants} *) (** Special float constants. It may not be safe to compare directly with these, as they have multiple internal @@ -301,47 +303,59 @@ val nan : float (** The smallest positive float [x] such that [1.0 +. x <> 1.0]. *) val epsilon : float -(** Euler? ... Euler? ... Euler? @since 2.0*) +(** Euler? ... Euler? ... Euler? + @since 2.0*) val e: float -(** [Math.log2 e] @since 2.0 *) +(** [Math.log2 e] + @since 2.0 *) val log2e: float -(** [log10 e] @since 2.0 *) +(** [log10 e] + @since 2.0 *) val log10e: float -(** [log 2] @since 2.0 *) +(** [log 2] + @since 2.0 *) val ln2: float -(** [log 10] @since 2.0 *) +(** [log 10] + @since 2.0 *) val ln10: float (** The constant pi (3.14159...) *) val pi : float -(** [pi /. 2.] @since 2.0 *) +(** [pi /. 2.] + @since 2.0 *) val pi2: float -(** [pi /. 4.] @since 2.0 *) +(** [pi /. 4.] + @since 2.0 *) val pi4: float -(** [1. /. pi] @since 2.0 *) +(** [1. /. pi] + @since 2.0 *) val invpi: float -(** [2. /. pi] @since 2.0 *) +(** [2. /. pi] + @since 2.0 *) val invpi2: float -(** [2. *. sqrt pi] @since 2.0 *) +(** [2. *. sqrt pi] + @since 2.0 *) val sqrtpi2: float -(** [sqrt 2.] @since 2.0 *) +(** [sqrt 2.] + @since 2.0 *) val sqrt2: float -(** [1. /. sqrt 2.] @since 2.0 *) +(** [1. /. sqrt 2.] + @since 2.0 *) val invsqrt2: float -(** {6 Operations on the internal representation of floating-point +(** {1 Operations on the internal representation of floating-point numbers}*) external frexp : float -> float * int = "caml_frexp_float" @@ -375,7 +389,7 @@ val approx_equal : ?epsilon:float -> float -> float -> bool (** Test whether two floats are approximately equal (i.e. within epsilon of each other). [epsilon] defaults to 1e-5. *) -(** {6 Submodules grouping all infix operators} *) +(** {1 Submodules grouping all infix operators} *) module Infix : sig include BatNumber.Infix with type bat__infix_t = t @@ -390,9 +404,9 @@ include BatNumber.RefOps with type bat__refops_t = t include BatNumber.Bounded with type bounded = t -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print: (t, _) BatIO.printer (**Operations on floating-point numbers, with exceptions raised in @@ -433,7 +447,7 @@ sig real numbers by OCaml. *) (** - {6 Usual operations} + {1 Usual operations} *) val zero : float @@ -490,7 +504,7 @@ sig include BatNumber.Bounded with type bounded = t (** - {6 Operations specific to floating-point numbers} + {1 Operations specific to floating-point numbers} *) val exp : float -> float @@ -565,7 +579,7 @@ sig val pi : float (** The constant pi (3.14159...) *) - (** {6 Operations on the internal representation of floating-point numbers}*) + (** {1 Operations on the internal representation of floating-point numbers}*) val frexp : float -> float * int (** [frexp f] returns the pair of the significant @@ -596,8 +610,8 @@ sig normal, subnormal, zero, infinite, or not a number. *) - (** {6 Boilerplate code}*) + (** {1 Boilerplate code}*) - (** {7 Printing}*) + (** {2 Printing}*) val print: 'a BatInnerIO.output -> t -> unit end diff --git a/src/batFormat.mli b/src/batFormat.mli index bf5449bd7..a93dc9681 100644 --- a/src/batFormat.mli +++ b/src/batFormat.mli @@ -86,7 +86,7 @@ open BatIO @author David Teller *) -(** {6 Boxes} *) +(** {1 Boxes} *) val open_box : int -> unit (** [open_box d] opens a new pretty-printing box @@ -103,7 +103,7 @@ val open_box : int -> unit val close_box : unit -> unit (** Closes the most recently opened pretty-printing box. *) -(** {6 Formatting functions} *) +(** {1 Formatting functions} *) val print_string : string -> unit (** [print_string str] prints [str] in the current box. *) @@ -125,7 +125,7 @@ val print_char : char -> unit val print_bool : bool -> unit (** Prints a boolean in the current box. *) -(** {6 Break hints} *) +(** {1 Break hints} *) val print_space : unit -> unit (** [print_space ()] is used to separate items (typically to print @@ -168,7 +168,7 @@ val print_if_newline : unit -> unit has just been split. Otherwise, ignore the next formatting command. *) -(** {6 Margin} *) +(** {1 Margin} *) val set_margin : int -> unit (** [set_margin d] sets the value of the right margin @@ -181,7 +181,7 @@ val set_margin : int -> unit val get_margin : unit -> int (** Returns the position of the right margin. *) -(** {6 Maximum indentation limit} *) +(** {1 Maximum indentation limit} *) val set_max_indent : int -> unit (** [set_max_indent d] sets the value of the maximum @@ -195,7 +195,7 @@ val set_max_indent : int -> unit val get_max_indent : unit -> int (** Return the value of the maximum indentation limit (in characters). *) -(** {6 Formatting depth: maximum number of boxes allowed before ellipsis} *) +(** {1 Formatting depth: maximum number of boxes allowed before ellipsis} *) val set_max_boxes : int -> unit (** [set_max_boxes max] sets the maximum number @@ -211,7 +211,7 @@ val get_max_boxes : unit -> int val over_max_boxes : unit -> bool (** Tests if the maximum number of boxes allowed have already been opened. *) -(** {6 Advanced formatting} *) +(** {1 Advanced formatting} *) val open_hbox : unit -> unit (** [open_hbox ()] opens a new pretty-printing box. @@ -244,7 +244,7 @@ val open_hovbox : int -> unit When a new line is printed in the box, [d] is added to the current indentation. *) -(** {6 Tabulations} *) +(** {1 Tabulations} *) val open_tbox : unit -> unit (** Opens a tabulation box. *) @@ -270,7 +270,7 @@ val set_tab : unit -> unit val print_tab : unit -> unit (** [print_tab ()] is equivalent to [print_tbreak 0 0]. *) -(** {6 Ellipsis} *) +(** {1 Ellipsis} *) val set_ellipsis_text : string -> unit (** Set the text of the ellipsis printed when too many boxes @@ -279,7 +279,7 @@ val set_ellipsis_text : string -> unit val get_ellipsis_text : unit -> string (** Return the text of the ellipsis. *) -(** {6:tags Semantics Tags} *) +(** {1:tags Semantics Tags} *) type tag = string @@ -356,7 +356,7 @@ val get_print_tags : unit -> bool val get_mark_tags : unit -> bool (** Return the current status of tags printing and tags marking. *) -(** {6 Redirecting the standard formatter output} *) +(** {1 Redirecting the standard formatter output} *) val set_formatter_output : 'a output -> unit (** Sets the output of the formatter to the given argument *) @@ -380,7 +380,7 @@ val get_formatter_output_functions : (** Return the current output functions of the pretty-printer. *) -(** {6:meaning Changing the meaning of standard formatter pretty printing} *) +(** {1:meaning Changing the meaning of standard formatter pretty printing} *) (** The [Format] module is versatile enough to let you completely redefine the meaning of pretty printing: you may provide your own functions to define @@ -420,7 +420,7 @@ val get_formatter_output_functions : ##V<5## including line breaking and indentation functions. Useful to record the ##V<5## current setting and restore it afterwards. *) -(** {6:tags Changing the meaning of printing semantics tags} *) +(** {1 Changing the meaning of printing semantics tags} *) ##V<5##type formatter_tag_functions = { ##V<5## mark_open_tag : tag -> string; @@ -460,7 +460,7 @@ val get_formatter_output_functions : (** Return the current tag functions of the pretty-printer. *) -(** {6 Multiple formatted output} *) +(** {1 Multiple formatted output} *) type formatter=Format.formatter (** Abstract data corresponding to a pretty-printer (also called a @@ -519,7 +519,7 @@ val make_formatter : instance, a formatter to the [Pervasives.out_channel] [oc] is returned by [make_formatter (Pervasives.output oc) (fun () -> Pervasives.flush oc)]. *) -(** {6 Basic functions to use with formatters} *) +(** {1 Basic functions to use with formatters} *) val pp_open_hbox : formatter -> unit -> unit val pp_open_vbox : formatter -> int -> unit @@ -607,7 +607,7 @@ val pp_print_text : formatter -> string -> unit @since 4.02.0 *) -(** {6 [printf] like functions for pretty-printing.} *) +(** {1 [printf] like functions for pretty-printing.} *) val fprintf : formatter -> ('a, formatter, unit) format -> 'a @@ -728,7 +728,7 @@ val ksprintf : (string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b (** Same as [sprintf] above, but instead of returning the string, passes it to the first argument. *) -(** {6 Deprecated} *) +(** {1 Deprecated} *) ##V<5##val bprintf : Buffer.t -> ('a, formatter, unit) format -> 'a ##V<5##(** A deprecated and error prone function. Do not use it. @@ -740,11 +740,11 @@ val ksprintf : (string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b ##V<5##val kprintf : (string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b ##V<5##(** A deprecated synonym for [ksprintf]. *) -(** {6 Basic functions to use with formatters} *) +(** {1 Basic functions to use with formatters} *) val pp_set_formatter_output : formatter -> _ output -> unit -(** {6 Deprecated}*) +(** {1 Deprecated}*) val set_formatter_out_channel : _ output -> unit (** Redirect the pretty-printer output to the given channel. diff --git a/src/batGc.mli b/src/batGc.mli index ce7dce595..4d3a66c56 100644 --- a/src/batGc.mli +++ b/src/batGc.mli @@ -88,11 +88,14 @@ type stat = Gc.stat = (** Maximum size reached by the major heap, in words. *) stack_size: int; - (** Current size of the stack, in words. @since 3.12.0 *) + (** Current size of the stack, in words. + + @since 3.12.0 *) ##V>=4.12## forced_major_collections: int; ##V>=4.12## (** Number of forced full major collections completed since the program -##V>=4.12## was started. @since 4.12.0 *) +##V>=4.12## was started. +##V>=4.12## @since 4.12.0 *) } (** The memory management counters are returned in a [stat] record. @@ -164,13 +167,16 @@ type control = Gc.control = quite fast but can result in fragmentation. 1 is the first-fit policy, which can be slower in some cases but can be better for programs with fragmentation problems. - Default: 0. @since 3.11.0 *) + Default: 0. + + @since 3.11.0 *) ##V>=4.3## window_size : int; ##V>=4.3## (** The size of the window used by the major GC for smoothing ##V>=4.3## out variations in its workload. This is an integer between ##V>=4.3## 1 and 50. -##V>=4.3## Default: 1. @since 2.5.0 and OCaml 4.03.0 *) +##V>=4.3## Default: 1. +##V>=4.3## @since 2.5.0 and OCaml 4.03.0 *) ##V>=4.3## ##V>=4.8## custom_major_ratio : int; diff --git a/src/batGenlex.mli b/src/batGenlex.mli index a228a0663..43a76ff13 100644 --- a/src/batGenlex.mli +++ b/src/batGenlex.mli @@ -74,7 +74,7 @@ val make_lexer : string list -> char Stream.t -> token Stream.t Comments delimited by [(*] and [*)] are skipped as well, and can be nested. *) -(* {6 Batteries extensions to genlex } *) +(* {1 Batteries extensions to genlex } *) type lexer_error = | IllegalCharacter of char | NotReallyAChar @@ -100,7 +100,7 @@ val to_lazy_list_filter: t -> char BatLazyList.t -> token BatLazyList.t val string_of_token : token -> string -(**{6 Extending to other languages}*) +(**{1 Extending to other languages}*) open BatCharParser module Languages : @@ -131,7 +131,7 @@ sig sig (**Create a lexer from a language definition*) - (** {6 High-level API} *) + (** {1 High-level API} *) (** Drop comments, present reserved operators and reserved names as [Kwd], operators and identifiers as [Ident], @@ -144,7 +144,7 @@ sig val feed : (char, position) BatParserCo.Source.t -> (token, position) BatParserCo.Source.t - (** {6 Medium-level API} *) + (** {1 Medium-level API} *) val start : (char, unit, position) BatParserCo.t (**Remove any leading whitespaces*) @@ -180,7 +180,7 @@ sig val number: (char, [`Float of float | `Integer of int] , position) BatParserCo.t (**Parse either an integer or a floating-point number.*) - (** {6 Low-level API} *) + (** {1 Low-level API} *) val char : char -> (char, char , position) BatParserCo.t (** As {!CharParser.char}, but case-insensitive if specified by {!case_sensitive}. *) diff --git a/src/batHashtbl.mli b/src/batHashtbl.mli index 22bb1f133..2d368983f 100644 --- a/src/batHashtbl.mli +++ b/src/batHashtbl.mli @@ -39,7 +39,7 @@ type ('a, 'b) t = ('a, 'b) Hashtbl.t type statistics = Hashtbl.statistics -(**{6 Base operations}*) +(**{1 Base operations}*) val create : int -> ('a, 'b) t (** [Hashtbl.create n] creates a new, empty hash table, with @@ -109,7 +109,7 @@ val stats : ('a, 'b) t -> statistics buckets by size. @since 4.00.0 and batteries 3.5.1 *) -(**{6 Enumerations}*) +(**{1 Enumerations}*) val keys : ('a,'b) t -> 'a BatEnum.t (** Return an enumeration of all the keys of a hashtable. @@ -125,7 +125,7 @@ val enum : ('a, 'b) t -> ('a * 'b) BatEnum.t val of_enum : ('a * 'b) BatEnum.t -> ('a, 'b) t (** Create a hashtable from a (key,value) enumeration. *) -(**{6 Lists}*) +(**{1 Lists}*) val of_list : ('a * 'b) list -> ('a, 'b) t (** Create a hashtable from a list of (key,value) pairs. @@ -139,7 +139,7 @@ val bindings : ('a, 'b) t -> ('a * 'b) list (** Alias for [to_list]. @since 2.6.0 *) -(**{6 Searching}*) +(**{1 Searching}*) val find : ('a, 'b) t -> 'a -> 'b (** [Hashtbl.find tbl x] returns the current binding of [x] in [tbl], @@ -169,7 +169,7 @@ val mem : ('a, 'b) t -> 'a -> bool (** [exists h k] returns true is at least one item with key [k] is found in the hashtable. *)*) -(**{6 Traversing} +(**{1 Traversing} A number of higher-order functions are provided to allow purely functional traversal or transformation of hashtables. @@ -277,7 +277,7 @@ val merge_all: ('a -> 'b list -> 'c list -> 'd list) -> @since 2.10.0 *) -(** {6 The polymorphic hash primitive}*) +(** {1 The polymorphic hash primitive}*) val hash : 'a -> int (** [Hashtbl.hash x] associates a positive integer to any value of @@ -287,16 +287,16 @@ val hash : 'a -> int structures. *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string -> ?kvsep:string -> ('a BatInnerIO.output -> 'b -> unit) -> ('a BatInnerIO.output -> 'c -> unit) -> 'a BatInnerIO.output -> ('b, 'c) t -> unit -(** {6 Override modules}*) +(** {1 Override modules}*) (** The following modules replace functions defined in {!Hashtbl} with functions @@ -366,7 +366,7 @@ sig left:('a, 'b) t -> right:('a, 'c) t -> ('a, 'd) t end -(** {6 Functorial interface} *) +(** {1 Functorial interface} *) module type HashedType = sig @@ -440,7 +440,7 @@ sig ('a BatInnerIO.output -> 'b -> unit) -> 'a BatInnerIO.output -> 'b t -> unit - (** {6 Override modules}*) + (** {1 Override modules}*) (** The following modules replace functions defined in {!Hashtbl} with functions @@ -532,7 +532,7 @@ sig type ('a, 'b, 'c) t constraint 'c = [< `Read | `Write ] (** The type of a hashtable. *) - (**{6 Constructors}*) + (**{1 Constructors}*) val create : int -> ('a, 'b, _) t @@ -562,7 +562,7 @@ sig This operation involves no copying.*) - (**{6 Base operations}*) + (**{1 Base operations}*) val length : ('a, 'b, _) t -> int val is_empty : ('a, 'b, _) t -> bool @@ -574,7 +574,7 @@ sig val clear : ('a, 'b, [>`Write]) t -> unit val stats : ('a, 'b, _) t -> statistics - (**{6 Searching}*) + (**{1 Searching}*) val find : ('a, 'b, [>`Read]) t -> 'a -> 'b val find_all : ('a, 'b, [>`Read]) t -> 'a -> 'b list @@ -588,7 +588,7 @@ sig (** [exists h k] returns true is at least one item with key [k] is found in the hashtable. *)*) - (**{6 Traversing}*) + (**{1 Traversing}*) val iter : ('a -> 'b -> unit) -> ('a, 'b, [>`Read]) t -> unit val for_all : ('a -> 'b -> bool) -> ('a, 'b, [>`Read]) t -> bool @@ -606,7 +606,7 @@ sig val merge_all : ('key -> 'a list -> 'b list -> 'c list) -> ('key, 'a, [>`Read]) t -> ('key, 'b, [>`Read]) t -> ('key, 'c, _) t - (**{6 Conversions}*) + (**{1 Conversions}*) val keys : ('a,'b, [>`Read]) t -> 'a BatEnum.t val values : ('a, 'b, [>`Read]) t -> 'b BatEnum.t @@ -615,16 +615,16 @@ sig val to_list : ('a, 'b, [>`Read]) t -> ('a * 'b) list val of_list : ('a * 'b) list -> ('a, 'b, _) t - (** {6 Boilerplate code}*) + (** {1 Boilerplate code}*) - (** {7 Printing}*) + (** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string -> ?kvsep:string -> ('a BatInnerIO.output -> 'b -> unit) -> ('a BatInnerIO.output -> 'c -> unit) -> 'a BatInnerIO.output -> ('b, 'c, [>`Read]) t -> unit - (** {6 Override modules}*) + (** {1 Override modules}*) (** Operations on {!BatHashtbl.Cap} without exceptions.*) module Exceptionless : diff --git a/src/batHeap.mli b/src/batHeap.mli index e916b4c5c..7ea07d97a 100644 --- a/src/batHeap.mli +++ b/src/batHeap.mli @@ -31,7 +31,7 @@ type +'a t val size : 'a t -> int (** Number of elements in the heap. O(1) *) -(** {6 Construction} *) +(** {1 Construction} *) val empty : 'a t (** The empty heap. *) @@ -43,7 +43,7 @@ val add : 'a -> 'a t -> 'a t (** [add x h] is the same as [insert h x]. This function is intended to be used with [fold_right]. *) -(** {6 Operations} *) +(** {1 Operations} *) val merge : 'a t -> 'a t -> 'a t (** Merge two heaps. O(log m) *) @@ -56,7 +56,7 @@ val del_min : 'a t -> 'a t (** Delete the minimal element of the heap. O(log n) @raise Invalid_argument ["del_min"] if the heap is empty *) -(** {6 Transformation} *) +(** {1 Transformation} *) val of_list : 'a list -> 'a t (** Build a heap from a given list. O(n log n) *) @@ -75,14 +75,14 @@ val enum : 'a t -> 'a BatEnum.t (** Enumerate the elements of the heap in heap order. O(log n) per {!BatEnum.get}. *) -(** {6 Printing} *) +(** {1 Printing} *) val print : ?first:string -> ?last:string -> ?sep:string -> ('a, 'b) BatIO.printer -> ('a t, 'b) BatIO.printer (** Print the contents of the heap in heap order. O(n log n) *) -(** {6 Functorized version} *) +(** {1 Functorized version} *) (** The result of {!Make} *) module type H = diff --git a/src/batIMap.mli b/src/batIMap.mli index 28606ec02..f72f9aa52 100644 --- a/src/batIMap.mli +++ b/src/batIMap.mli @@ -140,8 +140,10 @@ val get_dec_eq : 'a t -> ('a -> 'a -> bool) (** Infix operators over a {!BatIMap} *) module Infix : sig val (-->) : 'a t -> int -> 'a - (** [map-->key] returns the current binding of [key] in [map], - or @raise Not_found if no such binding exists. + (** [map-->key] returns the current binding of [key] in [map]. + + @raise Not_found if no such binding exists. + Equivalent to [find key map]. *) val (<--) : 'a t -> int * 'a -> 'a t diff --git a/src/batIO.mli b/src/batIO.mli index eb8b8214b..4fbc2eb8c 100644 --- a/src/batIO.mli +++ b/src/batIO.mli @@ -121,7 +121,7 @@ exception Input_closed exception Output_closed (** This exception is raised when reading on a closed output. *) -(** {6 Standard inputs/outputs} *) +(** {1 Standard inputs/outputs} *) val stdin : input (** Standard input, as per Unix/Windows conventions (by default, keyboard). @@ -161,7 +161,7 @@ val stdnull: unit output ] *) -(** {6 Standard API} *) +(** {1 Standard API} *) val read : input -> char (** Read a single char from an input or raise [No_more_input] if @@ -180,8 +180,10 @@ val nread : input -> int -> string val really_nread : input -> int -> string (** [really_nread i n] reads a string of exactly [n] characters - from the input. @raise No_more_input if at least [n] characters are - not available. @raise Invalid_argument if [n] < 0. + from the input. + + @raise No_more_input if at least [n] characters are not available. + @raise Invalid_argument if [n] < 0. Example: [let read_md5 ch = really_nread ch 32] *) @@ -205,10 +207,11 @@ val input : input -> Bytes.t -> int -> int -> int val really_input : input -> Bytes.t -> int -> int -> int (** [really_input ic s p len] reads exactly [len] characters from the input [ic], storing them in the string [s], starting at - position [p]. For consistency with {!BatIO.input} it returns - [len]. @raise No_more_input if at [len] characters are not - available. @raise Invalid_argument if [p] and [len] do not - designate a valid substring of [s]. + position [p]. For consistency with {!BatIO.val-input} it returns + [len]. + + @raise No_more_input if at [len] characters are not available. + @raise Invalid_argument if [p] and [len] do not designate a valid substring of [s]. Example: [let _ = really_input stdin b 0 3] *) @@ -251,9 +254,10 @@ val output_substring : 'a output -> string -> int -> int -> int val really_output : 'a output -> Bytes.t -> int -> int -> int (** [really_output o s p len] writes exactly [len] characters from byte sequence [s] onto the the output, starting with the character - at offset [p]. For consistency with {!BatIO.output} it returns - [len]. @raise Invalid_argument if [p] and [len] do not designate - a valid subsequence of [s]. + at offset [p]. For consistency with {!BatIO.val-output} it returns + [len]. + + @raise Invalid_argument if [p] and [len] do not designate a valid subsequence of [s]. This function is useful for networking situations where the output buffer might fill resulting in not the entire substring being @@ -308,7 +312,7 @@ val close_all : unit -> unit *) (**/**) -(** {6 Creation of BatIO Inputs/Outputs} +(** {1 Creation of BatIO Inputs/Outputs} To open a file for reading/writing, see {!File.open_in} and {!File.open_out}*) @@ -356,7 +360,7 @@ val tab_out : ?tab:char -> int -> 'a output -> unit output (** [repeat n out] create an output in which every character or string is repeated [n] times to [out].*)*) -(** {6 Utilities} *) +(** {1 Utilities} *) val read_all : input -> string (** read all the contents of the input until [No_more_input] is raised. *) @@ -395,7 +399,7 @@ external cast_output : 'a output -> unit output = "%identity" -(** {6 Binary files API} +(** {1 Binary files API} Here is some API useful for working with binary files, in particular binary files generated by C applications. By default, encoding of @@ -419,8 +423,9 @@ val read_i16 : input -> int (** Read a signed 16-bit word. *) val read_i32 : input -> int -(** Read a signed 32-bit integer. @raise Overflow if the - read integer cannot be represented as an OCaml 31-bit integer. *) +(** Read a signed 32-bit integer. + + @raise Overflow if the read integer cannot be represented as an OCaml 31-bit integer. *) val read_real_i32 : input -> int32 (** Read a signed 32-bit integer as an OCaml int32. *) @@ -501,8 +506,9 @@ sig (** Read a signed 16-bit word. *) val read_i32 : input -> int - (** Read a signed 32-bit integer. @raise Overflow if the - read integer cannot be represented as an OCaml 31-bit integer. *) + (** Read a signed 32-bit integer. + + @raise Overflow if the read integer cannot be represented as an OCaml 31-bit integer. *) val read_real_i32 : input -> int32 (** Read a signed 32-bit integer as an OCaml int32. *) @@ -565,7 +571,7 @@ sig end -(** {6 Bits API} +(** {1 Bits API} This enable you to read and write from an BatIO bit-by-bit or several bits at the same time. @@ -597,7 +603,7 @@ val drop_bits : in_bits -> unit (** - {6 Creating new types of inputs/outputs} + {1 Creating new types of inputs/outputs} *) @@ -656,7 +662,7 @@ val create_out : Fully create an output by giving all the needed functions. @param write Write one character to the output (see {!write}). - @param output Write a (sub)string to the output (see {!output}). + @param output Write a (sub)string to the output (see {!val-output}). @param flush Flush any buffers of this output (see {!flush}). @param close Close this output. The output will be automatically flushed. @@ -703,7 +709,7 @@ val wrap_out : issue. @param write Write one character to the output (see {!write}). - @param output Write a (sub)string to the output (see {!output}). + @param output Write a (sub)string to the output (see {!val-output}). @param flush Flush any buffers of this output (see {!flush}). @param close Close this output. The output will be automatically flushed. @@ -734,7 +740,7 @@ val inherit_out: *) (** - {6 For compatibility purposes} + {1 For compatibility purposes} *) val input_channel : ?autoclose:bool -> ?cleanup:bool -> in_channel -> input @@ -766,7 +772,7 @@ val to_input_channel : input -> in_channel libraries which can't be adapted. As a general rule, if you can avoid using this function, don't use it.*) -(** {6 Generic BatIO Object Wrappers} +(** {1 Generic BatIO Object Wrappers} These OO Wrappers have been written to provide easy support of BatIO by external libraries. If you want your library to support @@ -813,7 +819,7 @@ val from_out_channel : #out_channel -> unit output val from_in_chars : #in_chars -> input val from_out_chars : #out_chars -> unit output -(** {6 Enumeration API}*) +(** {1 Enumeration API}*) val bytes_of : input -> int BatEnum.t (** Read an enumeration of unsigned 8-bit integers. *) @@ -828,8 +834,9 @@ val i16s_of : input -> int BatEnum.t (** Read an enumartion of signed 16-bit words. *) val i32s_of : input -> int BatEnum.t -(** Read an enumeration of signed 32-bit integers. @raise Overflow if the - read integer cannot be represented as an OCaml 31-bit integer. *) +(** Read an enumeration of signed 32-bit integers. + + @raise Overflow if the read integer cannot be represented as an OCaml 31-bit integer. *) val real_i32s_of : input -> int32 BatEnum.t (** Read an enumeration of signed 32-bit integers as OCaml [int32]s. *) @@ -870,7 +877,7 @@ val default_buffer_size : int (**The default size for internal buffers.*) (** - {6 Thread-safety} + {1 Thread-safety} *) val synchronize_in : ?lock:BatConcurrent.lock -> input -> input @@ -899,7 +906,7 @@ val synchronize_out: ?lock:BatConcurrent.lock -> _ output -> unit output (** - {6 Thread-safety internals} + {1 Thread-safety internals} Unless you are attempting to adapt Batteries Included to a new model of concurrency, you probably won't need this. @@ -935,14 +942,14 @@ val comb : ('a output * 'a output) -> 'a output val make_enum : (input -> 'a) -> input -> 'a BatEnum.t (** - {6 Debugging facilities} + {1 Debugging facilities} *) val get_output_id : _ output -> int val get_input_id : input -> int module Incubator : sig - (** {6 Format-based pretty-printing} *) + (** {1 Format-based pretty-printing} *) module Array : sig val pp : diff --git a/src/batInnerIO.mli b/src/batInnerIO.mli index b64047b69..c33c2b458 100644 --- a/src/batInnerIO.mli +++ b/src/batInnerIO.mli @@ -67,8 +67,11 @@ val nread : input -> int -> string val really_nread : input -> int -> string (** [really_nread i n] reads a string of exactly [n] characters - from the input. @raise No_more_input if at least [n] characters are - not available. @raise Invalid_argument if [n] < 0. *) + from the input. + + @raise No_more_input if at least [n] characters are + not available. + @raise Invalid_argument if [n] < 0. *) val input : input -> Bytes.t -> int -> int -> int (** [input i s p len] reads up to [len] bytes from the given input, @@ -81,9 +84,12 @@ val input : input -> Bytes.t -> int -> int -> int val really_input : input -> Bytes.t -> int -> int -> int (** [really_input i s p len] reads exactly [len] characters from the given input, storing them in the byte sequence [s], starting at - position [p]. For consistency with {!BatIO.input} it returns - [len]. @raise No_more_input if at least [len] characters are not - available. @raise Invalid_argument if [p] and [len] do not designate + position [p]. For consistency with {!BatIO.val-input} it returns + [len]. + + @raise No_more_input if at least [len] characters are not + available. + @raise Invalid_argument if [p] and [len] do not designate a valid subsequence of [s]. *) val close_in : input -> unit @@ -119,8 +125,10 @@ val output_substring : 'a output -> string -> int -> int -> int val really_output : 'a output -> Bytes.t -> int -> int -> int (** [really_output o s p len] writes exactly [len] characters from byte sequence [s] onto the the output, starting with the character - at offset [p]. For consistency with {!BatIO.output} it returns - [len]. @raise Invalid_argument if [p] and [len] do not designate + at offset [p]. For consistency with {!BatIO.val-output} it returns + [len]. + + @raise Invalid_argument if [p] and [len] do not designate a valid subsequence of [s]. *) val really_output_substring : 'a output -> string -> int -> int -> int @@ -202,7 +210,7 @@ val create_out : Fully create an output by giving all the needed functions. @param write Write one character to the output (see {!write}). - @param output Write a (sub)string to the output (see {!output}). + @param output Write a (sub)string to the output (see {!val-output}). @param flush Flush any buffers of this output (see {!flush}). @param close Close this output. The output will be automatically flushed. @@ -262,7 +270,7 @@ val wrap_out : in turn avoids the issue. @param write Write one character to the output (see {!write}). - @param output Write a (sub)string to the output (see {!output}). + @param output Write a (sub)string to the output (see {!val-output}). @param flush Flush any buffers of this output (see {!flush}). @param close Close this output. The output will be automatically flushed. @@ -279,7 +287,7 @@ val default_buffer_size : int (**The default size of buffers.*) -(** {6 Binary files API} +(** {1 Binary files API} Here is some API useful for working with binary files, in particular binary files generated by C applications. By default, encoding of @@ -303,7 +311,9 @@ val read_i16 : input -> int (** Read a signed 16-bit word. *) val read_i32 : input -> int -(** Read a signed 32-bit integer. @raise Overflow if the +(** Read a signed 32-bit integer. + + @raise Overflow if the read integer cannot be represented as an OCaml 31-bit integer. *) val read_real_i32 : input -> int32 @@ -360,7 +370,7 @@ external cast_output : 'a output -> unit output = "%identity" by using this function. *) (** - {6 For compatibility purposes} + {1 For compatibility purposes} *) val input_channel : ?autoclose:bool -> ?cleanup:bool -> in_channel -> input @@ -400,7 +410,7 @@ val to_output_channel: _ output -> out_channel you can avoid using this function, don't use it.*) *) -(** {6 Standard inputs/outputs} *) +(** {1 Standard inputs/outputs} *) val stdin : input (** Standard input, as per Unix/Windows conventions (by default, keyboard).*) @@ -421,7 +431,7 @@ val stdnull: unit output Use this output to ignore messages.*) -(** {6 Comparison} +(** {1 Comparison} The following modules may be useful to create hashtables of inputs or outputs. *) @@ -451,12 +461,12 @@ sig end (**/**) -(**{6 Internals}*) +(**{1 Internals}*) external noop : unit -> unit = "%ignore" (** - {7 Optimized access to fields} + {2 Optimized access to fields} *) val get_output : _ output -> (Bytes.t -> int -> int -> int) @@ -469,7 +479,7 @@ val lock : BatConcurrent.lock ref (** - {7 Facilities for debugging} + {2 Facilities for debugging} *) val get_output_id : _ output -> int diff --git a/src/batInnerPervasives.ml b/src/batInnerPervasives.ml index eeff518bc..4580f10b2 100644 --- a/src/batInnerPervasives.ml +++ b/src/batInnerPervasives.ml @@ -64,7 +64,7 @@ let forever f x = ignore (while true do ignore (f x) done) let ignore_exceptions f x = try ignore (f x) with _ -> () - (** {6 Operators}*) + (** {1 Operators}*) ##V<4## let ( |> ) x f = f x ##V>=4## external (|>) : 'a -> ('a -> 'b) -> 'b = "%revapply" diff --git a/src/batInnerWeaktbl.mli b/src/batInnerWeaktbl.mli index 69ed66298..eaea2af7d 100644 --- a/src/batInnerWeaktbl.mli +++ b/src/batInnerWeaktbl.mli @@ -21,7 +21,7 @@ *) -(** {6 Generic interface} *) +(** {1 Generic interface} *) type ('a, 'b) t @@ -99,7 +99,7 @@ val length : ('a, 'b) t -> int gives the number of times [Weaktbl.iter] calls its first argument. *) -(** {6 Functorial interface} *) +(** {1 Functorial interface} *) module type HashedType = sig type t diff --git a/src/batInt.mli b/src/batInt.mli index 7f5b067c2..fe43eb58a 100644 --- a/src/batInt.mli +++ b/src/batInt.mli @@ -199,14 +199,14 @@ val ( --- ) : t -> t -> t BatEnum.t external of_int : int -> int = "%identity" external to_int : int -> int = "%identity" -(** {6 Submodules regrouping all infix operations} *) +(** {1 Submodules regrouping all infix operations} *) module Infix : BatNumber.Infix with type bat__infix_t = t module Compare : BatNumber.Compare with type bat__compare_t = t -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print: 'a BatInnerIO.output -> int -> unit (** prints as decimal string *) @@ -217,7 +217,7 @@ val print_hex: 'a BatInnerIO.output -> int -> unit (* val bprint: 'a BatInnerIO.output -> t -> unit (** prints as binary string *) *) -(** {7 Compare} *) +(** {2 Compare} *) val compare: t -> t -> int (** The comparison function for integers, with the same specification as @@ -374,12 +374,12 @@ module Safe_int : sig external of_int : int -> t = "%identity" external to_int : t -> int = "%identity" - (** {6 Submodules regrouping all infix operations on safe integers} *) + (** {1 Submodules regrouping all infix operations on safe integers} *) module Infix : BatNumber.Infix with type bat__infix_t = t module Compare : BatNumber.Compare with type bat__compare_t = t - (** {6 Boilerplate code}*) + (** {1 Boilerplate code}*) val print: 'a BatInnerIO.output -> t -> unit diff --git a/src/batInt32.mli b/src/batInt32.mli index 007c5cccf..f2add0e7d 100644 --- a/src/batInt32.mli +++ b/src/batInt32.mli @@ -46,6 +46,7 @@ @author Gabriel Scherer @author David Teller *) + type t = int32 val zero : int32 @@ -281,7 +282,7 @@ val ord : t -> t -> BatOrd.order (**/**) -(** {6 Deprecated functions} *) +(** {1 Deprecated functions} *) external format : string -> int32 -> string = "caml_int32_format" (** [Int32.format fmt n] return the string representation of the @@ -308,7 +309,7 @@ val ( ** ) : t -> t -> t *) val operations : t BatNumber.numeric -(** {6 Submodules grouping all infix operators} *) +(** {1 Submodules grouping all infix operators} *) module Infix : BatNumber.Infix with type bat__infix_t = t module Compare : BatNumber.Compare with type bat__compare_t = t @@ -316,9 +317,9 @@ module Compare : BatNumber.Compare with type bat__compare_t = t include BatNumber.Bounded with type bounded = t -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print: 'a BatInnerIO.output -> t -> unit (** prints as decimal string *) diff --git a/src/batInt64.mli b/src/batInt64.mli index e20228fd3..66ff25b51 100644 --- a/src/batInt64.mli +++ b/src/batInt64.mli @@ -258,14 +258,14 @@ val equal : t -> t -> bool val ord : t -> t -> BatOrd.order -(** {6 Submodules grouping all infix operators} *) +(** {1 Submodules grouping all infix operators} *) module Infix : BatNumber.Infix with type bat__infix_t = t module Compare: BatNumber.Compare with type bat__compare_t = t (**/**) -(** {6 Deprecated functions} *) +(** {1 Deprecated functions} *) external format : string -> int64 -> string = "caml_int64_format" (** [Int64.format fmt n] return the string representation of the @@ -295,9 +295,9 @@ val ( ** ) : t -> t -> t *) val operations : t BatNumber.numeric -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print: 'a BatInnerIO.output -> t -> unit (** prints as decimal string *) diff --git a/src/batLazyList.mli b/src/batLazyList.mli index e6b3a0af6..7b0d23cc3 100644 --- a/src/batLazyList.mli +++ b/src/batLazyList.mli @@ -42,7 +42,7 @@ @author David Teller *) -(** {6 Exceptions} *) +(** {1 Exceptions} *) exception Empty_list (** [Empty_list] is raised when an operation applied on an empty list @@ -59,7 +59,7 @@ exception Different_list_size of string exception No_more_elements (** See {!from} and {!from_loop} for more information on this exception.*) -(**{6 Type} +(**{1 Type} {b Note} The types are kept concrete so as to allow pattern-matching. However, it is generally easier to manipulate {!nil} and {!cons}.*) @@ -73,7 +73,7 @@ and 'a node_t = | Nil | Cons of 'a * 'a t include BatEnum.Enumerable with type 'a enumerable = 'a t include BatInterfaces.Mappable with type 'a mappable = 'a t -(** {6 Access } *) +(** {1 Access } *) val nil : 'a t (**The empty list.*) @@ -91,7 +91,7 @@ val get : 'a t -> ('a * 'a t) option (**[get l] returns the head and tail of [l], if [l] is not empty.*) (** - {6 List creation} + {1 List creation} *) @@ -155,7 +155,7 @@ val range : int -> int -> int t (** - {6 Higher-order functions} + {1 Higher-order functions} *) val iter : ('a -> 'b) -> 'a t -> unit @@ -245,7 +245,7 @@ val lazy_fold_right : @since 2.1 *) -(** {6 Finding}*) +(** {1 Finding}*) val mem : 'a -> 'a t -> bool (** [mem x l] determines if [x] is part of [l]. @@ -300,7 +300,7 @@ val rindex_ofq : 'a -> 'a t -> int option physical equality*) (** - {6 Common functions} + {1 Common functions} *) val next : 'a t -> 'a node_t @@ -321,13 +321,17 @@ val would_at_fail: 'a t -> int -> bool than [n] elements, [false] otherwise*) val hd : 'a t -> 'a -(**Return the first element of the given list. @raise Empty_list if the list is empty. +(**Return the first element of the given list. + + @raise Empty_list if the list is empty. Note: this function does not comply with the usual exceptionless error-management recommendations, as doing so would essentially render it useless.*) val tl : 'a t -> 'a t -(**Return the given list without its first element. @raise Empty_list if the list is empty. +(**Return the given list without its first element. + + @raise Empty_list if the list is empty. Note: this function does not comply with the usual exceptionless error-management recommendations, as doing so would essentially render it useless.*) @@ -336,19 +340,23 @@ val first : 'a t -> 'a (** As [hd]*) val last : 'a t -> 'a -(** Returns the last element of the list. @raise Empty_list if - the list is empty. This function takes linear time and causes the +(** Returns the last element of the list. + + @raise Empty_list if the list is empty. + + This function takes linear time and causes the evaluation of all elements of the list*) val at : 'a t -> int -> 'a (** [at l n] returns the element at index [n] (starting from [0]) in - the list [l]. @raise Invalid_index is the index is outside of - [l] bounds. *) + the list [l]. + + @raise Invalid_index is the index is outside of [l] bounds. *) val nth : 'a t -> int -> 'a (** Obsolete. As [at]*) -(** {6 Association lists} +(** {1 Association lists} These lists behave essentially as {!HashMap}, although they are typically faster for short number of associations, and much @@ -375,7 +383,7 @@ val mem_assq : 'a -> ('a * 'b) t -> bool val rev : 'a t -> 'a t (** Eager list reversal.*) -(** {6 Transformations} *) +(** {1 Transformations} *) val eager_append : 'a t -> 'a t -> 'a t (**Evaluate a list and append another list after this one. @@ -406,13 +414,14 @@ val flatten : ('a t) list -> 'a t val split_at : int -> 'a t -> 'a t * 'a t (** [split_at n l] returns two lists [l1] and [l2], [l1] containing the - first [n] elements of [l] and [l2] the others. @raise Invalid_index if - [n] is outside of [l] size bounds. *) + first [n] elements of [l] and [l2] the others. + + @raise Invalid_index if [n] is outside of [l] size bounds. *) val split_nth : int -> 'a t -> 'a t * 'a t (** Obsolete. As [split_at]. *) -(**{6 Dropping elements}*) +(**{1 Dropping elements}*) val unique : ?cmp:('a -> 'a -> int) -> 'a t -> 'a t (** [unique cmp l] returns the list [l] without any duplicate element. @@ -460,7 +469,7 @@ val drop_while : ('a -> bool) -> 'a t -> 'a t (** - {6 Combinatorics} + {1 Combinatorics} *) val combinations : 'a list -> ('a list) t @@ -474,7 +483,7 @@ val permutations : 'a list -> ('a list) t a different order. There are [factorial (length l)] permutations. *) (** - {6 Conversions} + {1 Conversions} *) val to_list : 'a t -> 'a list @@ -514,7 +523,7 @@ val of_array : 'a array -> 'a t (**Eager conversion from array*) (** - {6 Predicates} + {1 Predicates} *) val filter : ('a -> bool) -> 'a t -> 'a t @@ -551,23 +560,25 @@ val filter_map : ('a -> 'b option) -> 'a t -> 'b t | None -> [^ ^] ].*) -(**{6 Misc.}*) +(**{1 Misc.}*) val eternity : unit t (** An infinite list of nothing*) -(**{6 Sorting}*) +(**{1 Sorting}*) val sort : ?cmp:('a -> 'a -> int) -> 'a t -> 'a t (** Sort the list using optional comparator (by default [compare]). *) val stable_sort : ('a -> 'a -> int) -> 'a t -> 'a t -(**{6 Operations on two lists}*) +(**{1 Operations on two lists}*) val map2 : ('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t (** [map2 f [^ a0; a1; ...^] [^ b0; b1; ... ^]] is [[^ f a0 b0; f a1 - b1; ... ^]]. @raise Different_list_size if the two lists have + b1; ... ^]]. + + @raise Different_list_size if the two lists have different lengths. Not tail-recursive, lazy. In particular, the exception is raised only after the shortest list has been entirely consumed. *) @@ -633,20 +644,20 @@ val combine : 'a t -> 'b t -> ('a * 'b) t val uncombine : ('a * 'b) t -> 'a t * 'b t (** Divide a list of pairs into a pair of lists. *) -(** {6 Infix submodule regrouping all infix operators} *) +(** {1 Infix submodule regrouping all infix operators} *) module Infix : sig val ( ^:^ ) : 'a -> 'a t -> 'a t val ( ^@^ ) : 'a t -> 'a t -> 'a t end -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string ->('a BatInnerIO.output -> 'b -> unit) -> 'a BatInnerIO.output -> 'b t -> unit -(** {6 Override modules}*) +(** {1 Override modules}*) (** The following modules replace functions defined in {!LazyList} with functions diff --git a/src/batLexing.mli b/src/batLexing.mli index 7fa6335b6..50e1f5c32 100644 --- a/src/batLexing.mli +++ b/src/batLexing.mli @@ -30,7 +30,7 @@ (** The run-time library for lexers generated by [ocamllex]. *) -(** {6 Positions} *) +(** {1 Positions} *) type position = Lexing.position = { pos_fname : string; @@ -55,7 +55,7 @@ val dummy_pos : position *) -(** {6 Lexer buffers} *) +(** {1 Lexer buffers} *) type lexbuf = Lexing.lexbuf = @@ -150,7 +150,7 @@ type lexbuf = Lexing.lexbuf = ##V>=4.08## re-enable the [with_position] mode and degrade performances. ##V>=4.08##*) -(** {6 Functions for lexer semantic actions} *) +(** {1 Functions for lexer semantic actions} *) (** The following functions can be called from the semantic actions @@ -195,7 +195,7 @@ val new_line : lexbuf -> unit @since 3.11.0 *) -(** {6 Miscellaneous functions} *) +(** {1 Miscellaneous functions} *) val flush_input : lexbuf -> unit (** Discard the contents of the buffer and reset the current @@ -204,8 +204,6 @@ val flush_input : lexbuf -> unit (**/**) -(** {6 } *) - (** The following definitions are used by the generated scanners only. They are not intended to be used by user programs. *) @@ -230,7 +228,7 @@ type lex_tables = Lexing.lex_tables = val engine : lex_tables -> int -> lexbuf -> int val new_engine : lex_tables -> int -> lexbuf -> int -(** {6 Deprecated}*) +(** {1 Deprecated}*) val from_channel : BatIO.input -> lexbuf (** @deprecated As {!from_input}*) diff --git a/src/batList.mli b/src/batList.mli index a41de5b7f..22b23be1e 100644 --- a/src/batList.mli +++ b/src/batList.mli @@ -68,7 +68,7 @@ include BatEnum.Enumerable with type 'a enumerable = 'a t include BatInterfaces.Mappable with type 'a mappable = 'a t -(**{6 Base operations}*) +(**{1 Base operations}*) val is_empty : 'a list -> bool @@ -78,8 +78,9 @@ val cons : 'a -> 'a list -> 'a list (** [cons h t] returns the list starting with [h] and continuing as [t]. *) val hd : 'a list -> 'a -(** Returns the first element of the list, or @raise Failure if - the list is empty. *) +(** Returns the first element of the list. + + @raise Failure if the list is empty. *) val first : 'a list -> 'a @@ -90,8 +91,11 @@ val tl : 'a list -> 'a list @raise Failure if the list is empty. *) val last : 'a list -> 'a -(** Returns the last element of the list, or @raise Invalid_argument if - the list is empty. This function takes linear time. *) +(** Returns the last element of the list. + + @raise Invalid_argument if the list is empty. + + This function takes linear time. *) val length : 'a list -> int (** Return the length (number of elements) of the given list. *) @@ -158,7 +162,7 @@ val singleton : 'a -> 'a list *) -(**{6 Constructors}*) +(**{1 Constructors}*) val make : int -> 'a -> 'a list @@ -219,7 +223,7 @@ val unfold_exc : (unit -> 'a) -> 'a list * exn @deprecated use {!unfold_exn} @since 2.3.0 *) -##V>=4.12##(**{6 Comparison}*) +##V>=4.12##(**{1 Comparison}*) ##V>=4.12## ##V>=4.12##val equal : ('a -> 'a -> bool) -> 'a list -> 'a list -> bool ##V>=4.12##(** [equal eq [a1; ...; an] [b1; ..; bm]] holds when @@ -235,7 +239,7 @@ val unfold_exc : (unit -> 'a) -> 'a list * exn ##V>=4.12## @since 3.3.0 and 4.12.0 ##V>=4.12##*) -(**{6 Iterators}*) +(**{1 Iterators}*) val iter : ('a -> unit) -> 'a list -> unit (** [List.iter f [a0; a1; ...; an]] applies function [f] in turn to @@ -366,7 +370,7 @@ val min_max : ?cmp:('a -> 'a -> int) -> 'a list -> 'a * 'a ##V>=4.07##(** Create a list from the iterator ##V>=4.07## @since 2.10.0 and OCaml 4.07 *) -(** {6 Iterators on two lists} *) +(** {1 Iterators on two lists} *) val iter2 : ('a -> 'b -> unit) -> 'a list -> 'b list -> unit @@ -408,7 +412,7 @@ val fold_right2 : ('a -> 'b -> 'c -> 'c) -> 'a list -> 'b list -> 'c -> 'c Tail-recursive. *) -(**{6 List scanning}*) +(**{1 List scanning}*) val mem : 'a -> 'a list -> bool (** [mem a l] is true if and only if [a] is equal @@ -423,7 +427,7 @@ val memq : 'a -> 'a list -> bool (** Same as {!List.mem}, but uses physical equality instead of structural equality to compare list elements. *) -(**{7 Unary predicate, One list}*) +(**{2 Unary predicate, One list}*) val for_all : ('a -> bool) -> 'a list -> bool (** [for_all p [a0; a1; ...; an]] checks if all elements of the list @@ -435,7 +439,7 @@ val exists : ('a -> bool) -> 'a list -> bool the list satisfies the predicate [p]. That is, it returns [(p a0) || (p a1) || ... || (p an)]. *) -(**{7 Binary predicate, Two lists}*) +(**{2 Binary predicate, Two lists}*) val for_all2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool (** Same as {!List.for_all}, but for a two-argument predicate. @@ -455,7 +459,7 @@ val subset : ('a -> 'b -> int) -> 'a list -> 'b list -> bool *) -(**{6 List searching}*) +(**{1 List searching}*) val find : ('a -> bool) -> 'a list -> 'a (** [find p l] returns the first element of the list [l] @@ -483,14 +487,18 @@ val find_exn : ('a -> bool) -> exn -> 'a list -> 'a val findi : (int -> 'a -> bool) -> 'a list -> (int * 'a) (** [findi p l] returns the first element [ai] of [l] along with its - index [i] such that [p i ai] is true, or @raise Not_found if no - such element has been found. *) + index [i] such that [p i ai] is true. + + @raise Not_found if no such element has been found. *) val find_map : ('a -> 'b option) -> 'a list -> 'b (** [find_map pred list] finds the first element of [list] for which [pred element] returns [Some r]. It returns [r] immediately - once found or @raise Not_found if no element matches the - predicate. See also {!filter_map}. *) + once found. + + @raise Not_found if no element matches the predicate. + + See also {!filter_map}. *) ##V>=4.10##val concat_map : ('a -> 'b list) -> 'a list -> 'b list ##V>=4.10##(** [List.concat_map f l] gives the same result as @@ -501,7 +509,9 @@ val find_map : ('a -> 'b option) -> 'a list -> 'b val rfind : ('a -> bool) -> 'a list -> 'a (** [rfind p l] returns the last element [x] of [l] such as [p x] returns - [true] or @raise Not_found if such element as not been found. *) + [true]. + + @raise Not_found if such element as not been found. *) val filter : ('a -> bool) -> 'a list -> 'a list (** [filter p l] returns all the elements of the list [l] @@ -613,7 +623,7 @@ val unique_hash : ?hash:('a -> int) -> ?eq:('a -> 'a -> bool) -> 'a list -> 'a l @since 2.0.0 *) -(**{6 Association lists}*) +(**{1 Association lists}*) val assoc : 'a -> ('a * 'b) list -> 'b (** [assoc a l] returns the value associated with key [a] in the list of @@ -688,7 +698,7 @@ val modify_opt : 'a -> ('b option -> 'b option) -> ('a * 'b) list -> ('a * 'b) l @since 2.1 *) -(** {6 List transformations}*) +(** {1 List transformations}*) val modify_at : int -> ('a -> 'a) -> 'a list -> 'a list (** [modify_at n f l] returns the same list as [l] @@ -707,8 +717,9 @@ val modify_opt_at : int -> ('a -> 'a option) -> 'a list -> 'a list val split_at : int -> 'a list -> 'a list * 'a list (** [split_at n l] returns two lists [l1] and [l2], [l1] containing the - first [n] elements of [l] and [l2] the others. @raise Invalid_argument if - [n] is outside of [l] size bounds. *) + first [n] elements of [l] and [l2] the others. + + @raise Invalid_argument if [n] is outside of [l] size bounds. *) val split_nth : int -> 'a list -> 'a list * 'a list (** Obsolete. As [split_at]. *) @@ -821,7 +832,7 @@ val interleave : ?first:'a -> ?last:'a -> 'a -> 'a list -> 'a list [first; a0; sep; a1; sep; a2; sep; ...; sep; an; last]. *) -(** {6 BatEnum functions} +(** {1 BatEnum functions} Abstraction layer.*) @@ -848,7 +859,7 @@ val of_backwards : 'a BatEnum.t -> 'a list -(** {6 List of pairs}*) +(** {1 List of pairs}*) val split : ('a * 'b) list -> 'a list * 'b list (** Transform a list of pairs into a pair of lists: @@ -865,7 +876,7 @@ val combine : 'a list -> 'b list -> ('a * 'b) list Tail-recursive. *) -(** {6 Sorting}*) +(** {1 Sorting}*) val sort : ('a -> 'a -> int) -> 'a list -> 'a list @@ -921,7 +932,7 @@ val sort_unique : ('a -> 'a -> int) -> 'a list -> 'a list (** synonym for [sort_uniq] *) -(** {6 Utilities}*) +(** {1 Utilities}*) val group : ('a -> 'a -> int) -> 'a list -> 'a list list @@ -957,9 +968,9 @@ val transpose : 'a list list -> 'a list list @since 2.0.0 *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'b -> unit) -> 'a BatInnerIO.output -> 'b list -> unit @@ -979,7 +990,7 @@ module Comp (T : Comp) : Comp with type t = T.t list -(** {6 Obsolete functions} *) +(** {1 Obsolete functions} *) val nth : 'a list -> int -> 'a (** Obsolete. As [at]. *) @@ -998,7 +1009,7 @@ val takewhile : ('a -> bool) -> 'a list -> 'a list val dropwhile : ('a -> bool) -> 'a list -> 'a list (** obsolete, as {!drop_while} *) -(** {6 Override modules}*) +(** {1 Override modules}*) (** The following modules replace functions defined in {!List} with functions @@ -1102,7 +1113,7 @@ module Exceptionless : sig *) end -(** {6 Infix submodule regrouping all infix operators} *) +(** {1 Infix submodule regrouping all infix operators} *) module Infix : sig val ( @ ) : 'a list -> 'a list -> 'a list end diff --git a/src/batLog.mli b/src/batLog.mli index 85626ff16..b6f32cda3 100644 --- a/src/batLog.mli +++ b/src/batLog.mli @@ -21,6 +21,7 @@ (** Simple logging @author Edgar Friendly *) + open BatIO (** This ref holds the output channel for simple logging. Defaults to diff --git a/src/batLogger.mli b/src/batLogger.mli index 6235b408c..1a52b8047 100644 --- a/src/batLogger.mli +++ b/src/batLogger.mli @@ -26,7 +26,7 @@ * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ******************************************************************************) -(** {1 Logging Library} +(** Logging Library. This module defines functions which implement a flexible error logging system for applications. @@ -35,7 +35,7 @@ *) (******************************************************************************) -(** {6 log modules} *) +(** {1 log modules} *) type log type level = NONE | FATAL | ERROR | WARN | NOTICE | INFO | DEBUG @@ -57,7 +57,7 @@ val log_enabled : log -> level -> bool currently enabled for the logger. *) (******************************************************************************) -(** {6 log events} *) +(** {1 log events} *) type event = string * (string * string) list (** A log [event] consists of an event name and a list of key-value @@ -97,7 +97,7 @@ val with_log : log -> level -> (unit -> event) -> ?result:('a -> string) -> parameter. *) (******************************************************************************) -(** {6 log formatters} *) +(** {1 log formatters} *) type formatter = log -> level -> event -> float -> unit (** the type of a log formatter is a function that takes the @@ -175,7 +175,7 @@ val dbg_formatter : formatter events are raised. *) (******************************************************************************) -(** {6 logger initialization} *) +(** {1 logger initialization} *) val init : (string * level) list -> formatter -> unit (** [init name_level_list formatter] initializes the logging @@ -199,7 +199,7 @@ val init_from_string : string -> formatter -> unit [register_formatter]). *) (******************************************************************************) -(** {6 log utilities} *) +(** {1 log utilities} *) val level_of_name : string -> level (** [level_of_name str] returns the [level] associated with [str]. *) diff --git a/src/batMap.mli b/src/batMap.mli index bf0efd35c..5f0a325fa 100644 --- a/src/batMap.mli +++ b/src/batMap.mli @@ -70,6 +70,7 @@ @author David Rajchenbach-Teller @author Gabriel Scherer *) + module type S = sig type key @@ -450,9 +451,9 @@ sig val of_list : (key * 'a) list -> 'a t val add_to_list: key -> 'a -> 'a list t -> 'a list t - (** {6 Boilerplate code}*) + (** {1 Boilerplate code}*) - (** {7 Printing}*) + (** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string -> ?kvsep:string -> ('a BatInnerIO.output -> key -> unit) -> @@ -461,7 +462,7 @@ sig (** Output signature of the functor {!Map.Make}. *) - (** {6 Override modules}*) + (** {1 Override modules}*) (** The following modules replace functions defined in {!Map} with functions @@ -519,7 +520,7 @@ module Make (Ord : BatInterfaces.OrderedType) : S with type key = Ord.t given a totally ordered type. *) -(** {6 Common instantiations} **) +(** {1 Common instantiations} **) module Int : S with type key = int module Int32 : S with type key = int32 @@ -947,9 +948,9 @@ val bindings : ('key, 'a) t -> ('key * 'a) list *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string -> ?kvsep:string -> ('a BatInnerIO.output -> 'b -> unit) -> @@ -1392,9 +1393,9 @@ module PMap : sig Added for compatibility with stdlib 3.12 *) - (** {6 Boilerplate code}*) + (** {1 Boilerplate code}*) - (** {7 Printing}*) + (** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string -> ?kvsep:string -> ('a BatInnerIO.output -> 'b -> unit) -> diff --git a/src/batMarshal.mli b/src/batMarshal.mli index 5fd3c2b32..d904dd305 100644 --- a/src/batMarshal.mli +++ b/src/batMarshal.mli @@ -165,7 +165,7 @@ val data_size : Bytes.t -> int -> int val total_size : Bytes.t -> int -> int (** See {!Marshal.header_size}.*) -(** {6 Deprecated} *) +(** {1 Deprecated} *) val to_channel : _ BatInnerIO.output -> 'a -> extern_flags list -> unit (** @deprecated Use {!output} instead *) diff --git a/src/batMultiMap.mli b/src/batMultiMap.mli index 3597354e9..224003509 100644 --- a/src/batMultiMap.mli +++ b/src/batMultiMap.mli @@ -134,9 +134,9 @@ module Infix : sig [add key value map] *) end -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string -> ?kvsep:string -> ('a BatInnerIO.output -> 'b -> unit) -> diff --git a/src/batMultiPMap.mli b/src/batMultiPMap.mli index 0569ebd1f..5bffdcd25 100644 --- a/src/batMultiPMap.mli +++ b/src/batMultiPMap.mli @@ -138,9 +138,9 @@ module Infix : sig [add key value map] *) end -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string -> ?kvsep:string -> ('a BatInnerIO.output -> 'b -> unit) -> diff --git a/src/batNativeint.mli b/src/batNativeint.mli index aafc84dbb..aaeb17fd6 100644 --- a/src/batNativeint.mli +++ b/src/batNativeint.mli @@ -74,8 +74,11 @@ external mul : nativeint -> nativeint -> nativeint = "%nativeint_mul" (** Multiplication. *) external div : nativeint -> nativeint -> nativeint = "%nativeint_div" -(** Integer division. @raise Division_by_zero if the second - argument is zero. This division rounds the real quotient of +(** Integer division. + + @raise Division_by_zero if the second argument is zero. + + This division rounds the real quotient of its arguments towards zero, as specified for {!Pervasives.(/)}. *) ##V>=4.08##val unsigned_div : nativeint -> nativeint -> nativeint @@ -282,21 +285,21 @@ val operations : t BatNumber.numeric include BatNumber.Bounded with type bounded = t -(** {6 Submodules grouping all infix operators} *) +(** {1 Submodules grouping all infix operators} *) module Infix : BatNumber.Infix with type bat__infix_t = t module Compare : BatNumber.Compare with type bat__compare_t = t -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print : (t,_) BatIO.printer (**/**) -(** {6 Deprecated functions} *) +(** {1 Deprecated functions} *) external format : string -> nativeint -> string = "caml_nativeint_format" (** [Nativeint.format fmt n] return the string representation of the diff --git a/src/batNum.mli b/src/batNum.mli index 1025e2a2a..27561071d 100644 --- a/src/batNum.mli +++ b/src/batNum.mli @@ -45,7 +45,7 @@ type num = Num.num = type t = num -(** {6 Usual operations}*) +(** {1 Usual operations}*) val zero : num val one : num val neg : num -> num @@ -93,7 +93,7 @@ val ( ** ) : num -> num -> num val max_num : num -> num -> num val min_num : num -> num -> num -(** {6 Additional operations}*) +(** {1 Additional operations}*) val quo : num -> num -> num (**Euclidian divisiom*) @@ -123,7 +123,7 @@ val operations : num BatNumber.numeric -(** {6 Comparisons between numbers} *) +(** {1 Comparisons between numbers} *) val ( =/ ) : num -> num -> bool val ( num -> bool @@ -141,7 +141,7 @@ val ge_num : num -> num -> bool -(** {6 Coercions with strings} *) +(** {1 Coercions with strings} *) @@ -159,7 +159,7 @@ val approx_num_exp : int -> num -> string -(** {6 Coercions between numerical types} *) +(** {1 Coercions between numerical types} *) val nat_of_num : num -> nat val num_of_nat : nat -> num val num_of_big_int : big_int -> num @@ -168,12 +168,12 @@ val ratio_of_num : num -> ratio val num_of_ratio : ratio -> num val float_of_num : num -> float -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print: 'a BatInnerIO.output -> t -> unit -(** {6 Submodules grouping all infix operators} *) +(** {1 Submodules grouping all infix operators} *) module TaggedInfix : sig val ( =/ ) : num -> num -> bool @@ -208,7 +208,7 @@ end module Compare : BatNumber.Compare with type bat__compare_t = t -(** {6 Deprecated} *) +(** {1 Deprecated} *) val ( +/ ) : num -> num -> num val add_num : num -> num -> num diff --git a/src/batNumber.mli b/src/batNumber.mli index 236197cf9..367173919 100644 --- a/src/batNumber.mli +++ b/src/batNumber.mli @@ -111,7 +111,9 @@ module type Compare = sig end (** Reference operators ala C. Mutates a reference value. [x -= y] is - the same as [x := !x - y]. @since 2.0 *) + the same as [x := !x - y]. + + @since 2.0 *) module type RefOps = sig type bat__refops_t @@ -187,7 +189,7 @@ end (**/**) -(** {6 Utilities}*) +(** {1 Utilities}*) (** The smallest set of operations supported by every set of numbers @@ -199,7 +201,7 @@ sig val zero : t val one : t - (** {6 Arithmetic operations} + (** {1 Arithmetic operations} Depending on the implementation, some of these operations {i may} raise exceptions at run-time to represent over/under-flows.*) @@ -215,7 +217,7 @@ sig val pow : t -> t -> t val compare : t -> t -> int - (** {6 Conversions} *) + (** {1 Conversions} *) val of_int : int -> t (** Convert this number to the closest integer.*) @@ -224,7 +226,9 @@ sig val of_string : string -> t (** Convert the representation of a number to the corresponding - number. @raise Invalid_argument if the string does not represent + number. + + @raise Invalid_argument if the string does not represent a valid number of type [t]*) val to_string : t -> string diff --git a/src/batOptParse.mli b/src/batOptParse.mli index 5e0c74879..2e0414adc 100644 --- a/src/batOptParse.mli +++ b/src/batOptParse.mli @@ -33,7 +33,7 @@ module Opt : sig - (** {6 Exceptions} *) + (** {1 Exceptions} *) exception No_value (** [No_value] gets raised by {!OptParse.Opt.get} when an option @@ -55,7 +55,7 @@ sig attempt to catch it. *) - (** {6 Types} *) + (** {1 Types} *) type 'a t = { option_set : string -> string list -> unit; @@ -96,7 +96,7 @@ sig *) - (** {6 Option value retrieval} *) + (** {1 Option value retrieval} *) val get : 'a t -> 'a (** Get the value of an option. @@ -129,7 +129,7 @@ sig - (** {6 Option creation} *) + (** {1 Option creation} *) val value_option : string -> 'a option -> (string -> 'a) -> (exn -> string -> string) -> @@ -174,7 +174,7 @@ end module StdOpt : sig - (** {6 Flag options} *) + (** {1 Flag options} *) val store_const : ?default: 'a -> 'a -> 'a Opt.t (** [store_const ?default const] returns a flag option which @@ -211,7 +211,7 @@ sig (** Exactly identical to [count_option ~dest:dest ~increment:(-1) ()]. *) - (** {6 Value options} *) + (** {1 Value options} *) val int_option : ?default: int -> ?metavar: string -> unit -> int Opt.t (** [int_option ?default ?metavar ()] returns an option which takes @@ -236,7 +236,7 @@ sig [default] is the default value of the option. If [None], the option has no default value. *) - (** {6 Callback options} *) + (** {1 Callback options} *) val int_callback : ?metavar: string -> (int -> unit) -> unit Opt.t (** [int_callback ?metavar f] returns an option which takes a single @@ -250,7 +250,7 @@ sig (** See {!OptParse.StdOpt.int_callback}. *) - (** {6 Special options} *) + (** {1 Special options} *) val help_option : unit -> 'a Opt.t (** [help_option ()] returns the standard help option which @@ -287,7 +287,7 @@ sig string supplied by the user. *) - (** {6 Standard formatters} *) + (** {1 Standard formatters} *) val indented_formatter : @@ -321,7 +321,7 @@ sig the options. *) - (** {6 Low-level formatting} *) + (** {1 Low-level formatting} *) val wrap : ?initial_indent: int -> ?subsequent_indent: int -> @@ -353,7 +353,7 @@ end module OptParser : sig - (** {6 Exceptions} *) + (** {1 Exceptions} *) exception Option_conflict of string @@ -364,7 +364,7 @@ sig conflicting option names. *) - (** {6 Types} *) + (** {1 Types} *) type t @@ -374,7 +374,7 @@ sig (** The type of an option group. *) - (** {6 Option parser creation} *) + (** {1 Option parser creation} *) val make : ?usage: string -> ?description: string -> ?version: string -> ?suppress_usage: bool -> ?suppress_help: bool -> @@ -456,7 +456,7 @@ sig *) - (** {6 Output and error handling} *) + (** {1 Output and error handling} *) val error : t -> ?chn: out_channel -> ?status: int -> string -> unit (** Display an error message and exit the program. The error @@ -469,7 +469,7 @@ sig [Pervasives.stdout]) and return. *) - (** {6 Option parsing} *) + (** {1 Option parsing} *) val parse : t -> ?first: int -> ?last: int -> string array -> string list (** Parse arguments as if the arguments [args.(first)], diff --git a/src/batOption.mli b/src/batOption.mli index a38885552..9fb1b2918 100644 --- a/src/batOption.mli +++ b/src/batOption.mli @@ -131,7 +131,7 @@ val of_enum: 'a BatEnum.t -> 'a option (** [of_enum e] consumes the first element of [e], if it exists, and returns [Some e]. If [e] is empty, return [None]. *) -(** {6 The Option Monad} *) +(** {1 The Option Monad} *) (** This module provides everything needed to write and execute computations @@ -150,14 +150,14 @@ module Monad : sig [bind (Some 1) (fun x -> if x = 1 then Some 4 else None)] returns Some 4. *) end -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) open BatOrd val ord : 'a ord -> 'a option ord (** Comparison between optional values @since 2.2.0 *) -(** {7 Printing}*) +(** {2 Printing}*) val print : ('a BatInnerIO.output -> 'b -> unit) -> 'a BatInnerIO.output -> 'b t -> unit diff --git a/src/batParserCo.mli b/src/batParserCo.mli index 72a474be4..b8b2cf393 100644 --- a/src/batParserCo.mli +++ b/src/batParserCo.mli @@ -36,7 +36,7 @@ *) (** - {6 Base definitions} + {1 Base definitions} *) (**The current state of the parser. @@ -70,7 +70,7 @@ sig end -(** {6 Primitives} *) +(** {1 Primitives} *) type ('a, 'b, 'c) t (**A parser for elements of type ['a], producing @@ -169,8 +169,8 @@ val lookahead: ('a, 'b, 'c) t -> ('a, 'b option, 'c) t -(** {6 Utilities} *) -(** {7 Singletons} *) +(** {1 Utilities} *) +(** {2 Singletons} *) val exactly : 'a -> ('a, 'a, 'c) t (**Accept exactly one singleton.*) @@ -186,7 +186,7 @@ val none_of : 'a list -> ('a, 'a, 'c) t val range: 'a -> 'a -> ('a, 'a, 'c) t (**Accept any element from a given range.*) -(** {7 Repetitions} *) +(** {2 Repetitions} *) val zero_plus : ?sep:('a, _, 'c) t -> ('a, 'b, 'c) t -> ('a, 'b list, 'c) t (**Accept a (possibly empty) list of expressions.*) @@ -223,7 +223,7 @@ val should: ('a, 'b, 'c) t -> ('a, 'b, 'c) t (**Prevent backtracking.*) -(** {7 Maps}*) +(** {2 Maps}*) val post_map : ('b -> 'c) -> ('a, 'b, 'd) t -> ('a, 'c, 'd) t (**Pass the (successful) result of some parser through a map.*) @@ -235,7 +235,7 @@ val scan: ('a, _, 'c) t -> ('a, 'a list, 'c) t that list of tokens instead of whatever the original parser returned.*) -(** {7 Others}*) +(** {2 Others}*) val sat: ('a -> bool) -> ('a, unit, _) t (**[satisfy p] accepts one value [p x] such that [p x = true]*) @@ -243,7 +243,7 @@ val sat: ('a -> bool) -> ('a, unit, _) t val debug_mode : bool ref (**If set to [true], debugging information will be printed to the standard error.*) -(** {6 Infix submodule regrouping all infix operators} *) +(** {1 Infix submodule regrouping all infix operators} *) module Infix : sig val ( <|> ) : ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> ('a, 'b, 'c) t val ( ~? ): ('a, 'b, 'c) t -> ('a, 'b option, 'c) t diff --git a/src/batPathGen.mli b/src/batPathGen.mli index aad01d6ff..7b78dbe64 100644 --- a/src/batPathGen.mli +++ b/src/batPathGen.mli @@ -31,7 +31,7 @@ (** - {6 Functorized interface} + {1 Functorized interface} *) (* the part copied to PathGen.ml starts here *) @@ -137,7 +137,7 @@ module type PathType = sig val is_relative : t -> bool val is_absolute : t -> bool - (** {6 Construction} *) + (** {1 Construction} *) val root : t (** Root of the filesystem ([\[""\]]). It is minimal absolute path. Below it is called 'empty'. However it yields "/" or "\\" when converted to a string. @@ -267,7 +267,7 @@ module type PathType = sig @raise Malformed_path if normalization fails (see {!PathType.normalize}) *) - (** {6 Validation} *) + (** {1 Validation} *) exception Illegal_char (** Raised by {!PathType.of_string}, {!PathType.append} and {!PathType.Operators.(/:)} when used validator finds illegal character. *) @@ -289,7 +289,7 @@ module type PathType = sig On reserved names and ones ending with dot (except "." and "..") Illegal_name is raised. *) - (** {6 Conversions} *) + (** {1 Conversions} *) val to_ustring : t -> ustring (** Convert to the chosen [ustring] type. Empty relative path is converted to "." (single dot). @@ -309,7 +309,7 @@ module type PathType = sig @raise Illegal_char when a character not allowed in paths is found. *) - (** {7 Convenience aliases} *) + (** {2 Convenience aliases} *) val s : t -> string (** = {!to_string} *) @@ -317,7 +317,7 @@ module type PathType = sig val p : ustring -> t (** = {!of_string} *) - (** {6 Name related functions} + (** {1 Name related functions} These functions do not accept empty paths, i.e. [\[\]], [\[""\]] or [\["C:"\]]. *) @@ -461,7 +461,7 @@ module type PathType = sig ]} *) - (** {6 Supplementary functions} *) + (** {1 Supplementary functions} *) val drive_letter : t -> uchar option (** diff --git a/src/batPervasives.mli b/src/batPervasives.mli index 141086596..a929bf0bb 100644 --- a/src/batPervasives.mli +++ b/src/batPervasives.mli @@ -21,7 +21,7 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA *) -(** {6 Additional functions.} +(** Additional functions. @author Xavier Leroy (Base module) @author Nicolas Cannasse @@ -93,7 +93,7 @@ val print_any : 'b BatIO.output -> 'a -> unit string to the output. *) -(** {6 List operations} +(** {1 List operations} More list operations are provided in module {!List}. *) @@ -102,7 +102,7 @@ val ( @ ) : 'a list -> 'a list -> 'a list (** List concatenation. *) -(** {6 Input/output} +(** {1 Input/output} This section only contains the most common input/output operations. More operations may be found in modules {!BatIO} and {!File}. @@ -138,7 +138,7 @@ val flush_all : unit -> unit debugging, as it forces pending data to be written immediately. *) -(** {7 Output functions on standard output} *) +(** {2 Output functions on standard output} *) val print_bool : bool -> unit @@ -153,7 +153,7 @@ val print_guess : 'a BatIO.output -> 'b -> unit val print_all : input -> unit (** Print the contents of an input to the standard output.*) -(** {7 Output functions on standard error} *) +(** {2 Output functions on standard error} *) val prerr_bool : bool -> unit (** Print a boolean to stderr. *) @@ -166,7 +166,7 @@ val prerr_guess : 'a -> unit val prerr_all : input -> unit (** Print the contents of an input to the error output.*) -(** {7 General output functions} *) +(** {2 General output functions} *) val output_file : filename:string -> text:string -> unit (** creates a filename, write text into it and close it. *) @@ -275,7 +275,7 @@ val close_out : unit BatIO.output -> unit val close_out_noerr : unit BatIO.output -> unit (** Same as [close_out], but ignore all errors. *) -(** {7 General input functions} *) +(** {2 General input functions} *) val input_file : ?bin:bool -> string -> string (** returns the data of a given filename. *) @@ -347,7 +347,9 @@ val input : BatIO.input -> Bytes.t -> int -> int -> int val really_input : BatIO.input -> Bytes.t -> int -> int -> unit (** [really_input ic buf pos len] reads [len] characters from channel [ic], storing them in byte sequence [buf], starting at character - number [pos]. @raise End_of_file if the end of file is reached + number [pos]. + + @raise End_of_file if the end of file is reached before [len] characters have been read. @raise Invalid_argument if [pos] and [len] do not designate a valid subsequence of [buf]. *) @@ -389,7 +391,7 @@ val close_in_noerr : BatIO.input -> unit (** - {6 Fundamental functions and operators} + {1 Fundamental functions and operators} *) external identity : 'a -> 'a = "%identity" @@ -549,7 +551,7 @@ val exe : string (** - {6 Enumerations} + {1 Enumerations} In OCaml Batteries Included, all data structures are enumerable, which means that they support a number of standard operations, @@ -598,9 +600,7 @@ val foreach: 'a BatEnum.t -> ('a -> unit) -> unit *) (** - {7 General-purpose loops} - - {topic loops} + {2 General-purpose loops} The following functions are the three main general-purpose loops available in OCaml. By opposition to the loops available in @@ -748,7 +748,7 @@ val ( @// ) : ('a -> 'b option) -> 'a BatEnum.t -> 'b BatEnum.t *) (** - {7 Other operations on enumerations} + {2 Other operations on enumerations} *) val exists: ('a -> bool) -> 'a BatEnum.t -> bool @@ -835,7 +835,7 @@ val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.outp (** Print and consume the contents of an enumeration.*) (** - {6 Results} + {1 Results} *) (** This type represents the outcome of a function which has the @@ -872,7 +872,7 @@ val wrap : ('a -> 'b) -> 'a -> ('b, exn) result (** - {6 Thread-safety internals} + {1 Thread-safety internals} Unless you are attempting to adapt Batteries Included to a new model of concurrency, you probably won't need this. diff --git a/src/batPrintexc.mli b/src/batPrintexc.mli index 54334bd3e..ad3b39528 100644 --- a/src/batPrintexc.mli +++ b/src/batPrintexc.mli @@ -90,7 +90,7 @@ val print : _ BatInnerIO.output -> exn -> unit (** Print an exception. The stdlib [print] function is now named [!pass].*) -##V=4.1##(** {6 Raw backtraces} *) +##V=4.1##(** {1 Raw backtraces} *) ##V=4.1## ##V=4.1##type raw_backtrace = Printexc.raw_backtrace ##V=4.1## @@ -115,7 +115,7 @@ val print : _ BatInnerIO.output -> exn -> unit ##V>=4.5## @since 2.7.0 and OCaml 4.05.0 ##V>=4.5##*) -##V=4.1##(** {6 Current call stack} *) +##V=4.1##(** {1 Current call stack} *) ##V=4.1## ##V=4.1##val get_callstack: int -> raw_backtrace ##V=4.1## @@ -127,7 +127,7 @@ val print : _ BatInnerIO.output -> exn -> unit ##V=4.1## @since 2.2.0 and OCaml 4.01.0 ##V=4.1##*) -##V>=4.2##(** {6 Raw backtraces} *) +##V>=4.2##(** {1 Raw backtraces} *) ##V>=4.2## ##V>=4.2##type raw_backtrace = Printexc.raw_backtrace ##V>=4.2##(** The abstract type [raw_backtrace] stores a backtrace in @@ -167,7 +167,7 @@ val print : _ BatInnerIO.output -> exn -> unit ##V>=4.2## @since 2.2.0 and OCaml 4.01.0 ##V>=4.2##*) ##V>=4.2## -##V>=4.2##(** {6 Current call stack} *) +##V>=4.2##(** {1 Current call stack} *) ##V>=4.2## ##V>=4.2##val get_callstack: int -> raw_backtrace ##V>=4.10##external get_callstack : int -> raw_backtrace = "caml_get_current_callstack" @@ -179,7 +179,7 @@ val print : _ BatInnerIO.output -> exn -> unit ##V>=4.2## @since 2.2.0 and OCaml 4.01.0 ##V>=4.2##*) ##V>=4.2## -##V>=4.2##(** {6 Uncaught exceptions} *) +##V>=4.2##(** {1 Uncaught exceptions} *) ##V>=4.2## ##V>=4.11##val default_uncaught_exception_handler: exn -> raw_backtrace -> unit ##V>=4.11##(** [Printexc.default_uncaught_exception_handler] prints the exception and @@ -203,7 +203,7 @@ val print : _ BatInnerIO.output -> exn -> unit ##V>=4.2##*) ##V>=4.2## ##V>=4.2## -##V>=4.2##(** {6 Manipulation of backtrace information} +##V>=4.2##(** {1 Manipulation of backtrace information} ##V>=4.2## ##V>=4.2## Those function allow to traverse the slots of a raw backtrace, ##V>=4.2## extract information from them in a programmer-friendly format. @@ -304,7 +304,7 @@ val print : _ BatInnerIO.output -> exn -> unit ##V>=4.2##end ##V>=4.2## ##V>=4.2## -##V>=4.2##(** {6 Raw backtrace slots} *) +##V>=4.2##(** {1 Raw backtrace slots} *) ##V>=4.2## ##V>=4.2##type raw_backtrace_slot = Printexc.raw_backtrace_slot ##V>=4.2##(** This type allows direct access to raw backtrace slots, without any @@ -349,7 +349,7 @@ val print : _ BatInnerIO.output -> exn -> unit ##V>=4.4##*) -##V>=4.2##(** {6 Exception slots} *) +##V>=4.2##(** {1 Exception slots} *) ##V>=4.2## ##V>=4.2##val exn_slot_id: exn -> int ##V>=4.2##(** [Printexc.exn_slot_id] returns an integer which uniquely identifies diff --git a/src/batPrintf.mli b/src/batPrintf.mli index cf81c6574..b4106c24d 100644 --- a/src/batPrintf.mli +++ b/src/batPrintf.mli @@ -30,7 +30,7 @@ open BatInnerIO *) (** - {6 General overview} + {1 General overview} The functions of this module produce output according to a {!Pervasives.format}, as described below. Some functions write to @@ -78,7 +78,7 @@ open BatInnerIO (** - {6 Formats} + {1 Formats} *) type ('a, 'b, 'c) t = ('a, 'b, 'c) Pervasives.format @@ -89,7 +89,7 @@ type ('a, 'b, 'c) t = ('a, 'b, 'c) Pervasives.format of objects: plain characters, which are simply copied, and directives, each of which causes the conversion and printing of arguments. - {7 Simple directives} + {2 Simple directives} All directives start with the [%] character. In their simplest form, a directive is [%] followed by exactly one character: @@ -128,7 +128,7 @@ type ('a, 'b, 'c) t = ('a, 'b, 'c) Pervasives.format - [,]: the no-op delimiter for conversion specifications - {7 Unparsers} + {2 Unparsers} - [%a]: user-defined printer. Typically, this printer corresponds to two arguments: a printing function [f], with type ['a output -> 'c -> unit] @@ -146,7 +146,7 @@ type ('a, 'b, 'c) t = ('a, 'b, 'c) Pervasives.format or [('a, 'b, 'd, 'e) format4], function [f] must have type ['b -> 'd]. - {7 Formatting formats} + {2 Formatting formats} - [%\{ fmt %\}]: convert a {!format} to a string. The format argument must have the same type as the internal format string [fmt]. In other words, [printf "%\{ %s %\}"] accepts an argument @@ -159,7 +159,7 @@ type ('a, 'b, 'c) t = ('a, 'b, 'c) Pervasives.format whose type must be the same as that of format ["%s"], and uses that argument to print the following arguments. - {7 Additional options} + {2 Additional options} The general format of directives is [% \[flags\] \[width\] \[.precision\] type] @@ -192,7 +192,7 @@ type ('a, 'b, 'c) t = ('a, 'b, 'c) Pervasives.format *) -(** {6 Common functions}*) +(** {1 Common functions}*) val printf: ('b, 'a output, unit) t -> 'b (**The usual [printf] function, prints to the standard output {!stdout}, i.e. normally @@ -226,11 +226,11 @@ val sprintf2: ('a, 'b output, unit, string) format4 -> 'a i.e. should have type ['b output -> unit]. Warning: a partial application of this function can only be used once, - because the {!BatInnerIO.output} that it uses is closed afterwards. + because the {!BatInnerIO.type-output} that it uses is closed afterwards. Example: [let f = sprintf2 "%a" Int.print in [f 1; f 2]] will fail. *) -(** {6 General functions}*) +(** {1 General functions}*) val fprintf: 'a output -> ('b, 'a output, unit) t -> 'b (**General function. This function prints to any output. Typically, @@ -260,7 +260,7 @@ val bprintf2: Buffer.t -> ('b, 'a output, unit) t -> 'b {!bprintf}, only the result is changed with respect to {!printf}, not the inner workings.*) -(**{6 Functions with continuations}*) +(**{1 Functions with continuations}*) val kfprintf : ('a output -> 'b) -> 'a output -> ('c, 'a output, unit, 'b) format4 -> 'c (**Same as [fprintf], but instead of returning immediately, passes the [output] to its first @@ -288,13 +288,13 @@ val kprintf : (string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b (** - {6 About formats} + {1 About formats} You only need to read this if you intend to create your new printf-like functions, which happens generally by toying with {!mkprintf}. - {7 Format4} + {2 Format4} [('a, 'b, 'c, 'd) format4] is the type of arguments for [printf]-style functions such that @@ -324,10 +324,10 @@ val kprintf : (string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b - ['d] is the final return value of the function once all arguments have been printed - {7 Format} + {2 Format} [('a, 'b, 'c) format] or [('a, 'b, 'c) t] is just a shortcut for [('a, 'b, 'c, 'c) format4]. - {7 Important} + {2 Important} Note that {!Obj.magic} is involved behind this, so be careful. *) diff --git a/src/batQueue.mli b/src/batQueue.mli index 90ce161c0..a78fb45f0 100644 --- a/src/batQueue.mli +++ b/src/batQueue.mli @@ -157,9 +157,9 @@ val of_enum : 'a BatEnum.t -> 'a t ##V>=4.07##(** Create a queue from the generator ##V>=4.07## @since 2.10.0 and OCaml 4.07 *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'b -> unit) -> 'a BatInnerIO.output -> 'b t -> unit diff --git a/src/batRandom.mli b/src/batRandom.mli index c320ccd10..cd1ad9598 100644 --- a/src/batRandom.mli +++ b/src/batRandom.mli @@ -33,7 +33,7 @@ @documents Random *) -(** {6 Basic functions} *) +(** {1 Basic functions} *) val init : int -> unit (** Initialize the generator, using the argument as a seed. @@ -107,7 +107,7 @@ val full_range_int : unit -> int platforms, so is not portable. *) -(** {6 Enumerations of random values.} *) +(** {1 Enumerations of random values.} *) val enum_bits : unit -> int BatEnum.t @@ -127,7 +127,7 @@ val enum_char : unit -> char BatEnum.t (*val enum_uchar : unit -> UChar.t BatEnum.t*) -(** {6 Working with data structures.} *) +(** {1 Working with data structures.} *) val choice : 'a BatEnum.t -> 'a (** [choice e] returns a randomly-chosen element of [e]. @@ -167,7 +167,7 @@ val shuffle: 'a BatEnum.t -> 'a array ##V>=4.14## {!Nativeint.min_int} and {!Nativeint.max_int}. ##V>=4.14## @since 4.14.0 *) -(** {6 Advanced functions} *) +(** {1 Advanced functions} *) (** Manipulate the current state of the random generator. diff --git a/src/batRef.mli b/src/batRef.mli index 636a16579..6c2abbca0 100644 --- a/src/batRef.mli +++ b/src/batRef.mli @@ -112,7 +112,7 @@ val oget_exn : 'a option ref -> 'a (** Get a value from an option ref; @raise Not_found on [oget_exn (ref None)] *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) val print: ('b BatInnerIO.output -> 'a -> unit) -> 'b BatInnerIO.output -> 'a t -> unit diff --git a/src/batRefList.mli b/src/batRefList.mli index 41de883ac..349a72288 100644 --- a/src/batRefList.mli +++ b/src/batRefList.mli @@ -111,7 +111,7 @@ val tl : 'a t -> 'a t val rev : 'a t -> unit (** Reverses the ref list - O(n) *) -(** {6 Functional Operations} *) +(** {1 Functional Operations} *) val fold_left : ('a -> 'b -> 'a) -> 'a -> 'b t -> 'a (** [List.fold_left f a (ref [b0; b1; ...; bn])] is @@ -186,7 +186,7 @@ val remove_all : 'a t -> 'a -> unit (** Remove all elements equal to the specified element from the ref list *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) diff --git a/src/batResult.mli b/src/batResult.mli index d94a1ce9f..28aea223e 100644 --- a/src/batResult.mli +++ b/src/batResult.mli @@ -27,13 +27,13 @@ val default: 'a -> ('a, _) t -> 'a @since 2.0 *) val get_ok : ('a, 'e) t -> 'a -(** [get_ok r] is [v] if [r] is [Ok v] and @raise Invalid_argument - otherwise. +(** [get_ok r] is [v] if [r] is [Ok v]. + @raise Invalid_argument otherwise. @since 3.0.0 *) val get_error : ('a, 'e) t -> 'e -(** [get_error r] is [e] if [r] is [Error e] and @raise Invalid_argument - otherwise. +(** [get_error r] is [e] if [r] is [Error e]. + @raise Invalid_argument otherwise. @since 3.0.0 *) val get : ('a, exn) t -> 'a @@ -147,7 +147,7 @@ val to_seq : ('a, 'e) t -> 'a BatSeq.t containing [v] and [Error _] is the empty sequence. @since 3.0.0 *) -(** {6 The Result Monad} *) +(** {1 The Result Monad} *) (** This monad is very similar to the option monad, but instead of being [None] when an error occurs, the first error in the sequence is @@ -170,7 +170,7 @@ module Monad : sig val return : 'a -> ('a, _) t end -(** {6 Infix} *) +(** {1 Infix} *) (** This infix module provides the operator [(>>=)] *) module Infix : sig diff --git a/src/batScanf.mli b/src/batScanf.mli index ab78cd268..b9809ddbe 100644 --- a/src/batScanf.mli +++ b/src/batScanf.mli @@ -25,9 +25,9 @@ @author David Teller *) -(** {6 Introduction} *) +(** {1 Introduction} *) -(** {7 Functional input with format strings} *) +(** {2 Functional input with format strings} *) (** The module [Scanf] provides formatted input functions or {e scanners}. @@ -56,7 +56,7 @@ - [f] is a function that has as many arguments as the number of values to read in the input. *) -(** {7 A simple example} *) +(** {2 A simple example} *) (** As suggested above, the expression [bscanf ib "%d" f] reads a decimal integer [n] from the source of characters [ib] and returns [f n]. @@ -73,7 +73,7 @@ "%d" f], and then enter [41] at the keyboard, we get [42] as the final result. *) -(** {7 Formatted input as a functional feature} *) +(** {2 Formatted input as a functional feature} *) (** The OCaml scanning facility is reminiscent of the corresponding C feature. However, it is also largely different, simpler, and yet more powerful: @@ -87,7 +87,7 @@ polymorphic user-defined scanners. Furthermore, the OCaml formatted input facility is fully type-checked at compile time. *) -(** {6 Scanning buffers} *) +(** {1 Scanning buffers} *) module Scanning : sig type scanbuf = Scanf.Scanning.scanbuf @@ -153,16 +153,16 @@ module Scanning : sig for the scanning buffer [ib]. *) (** - {6 Obsolete} + {1 Obsolete} *) val from_channel : BatIO.input -> scanbuf - (** @obsolete use {!from_input}*) + (** @deprecated use {!from_input}*) end -(** {6 Type of formatted input functions} *) +(** {1 Type of formatted input functions} *) type ('a, 'b, 'c, 'd) scanner = ('a, Scanning.scanbuf, 'b, 'c, 'a -> 'd, 'd) format6 -> 'c @@ -188,7 +188,7 @@ exception Scan_failure of string (** The exception that formatted input functions raise when the input cannot be read according to the given format. *) -(** {6 The general formatted input function} *) +(** {1 The general formatted input function} *) val bscanf : Scanning.scanbuf -> ('a, 'b, 'c, 'd) scanner (** [bscanf ib fmt r1 ... rN f] reads arguments for the function [f], from the @@ -202,7 +202,7 @@ val bscanf : Scanning.scanbuf -> ('a, 'b, 'c, 'd) scanner Arguments [r1] to [rN] are user-defined input functions that read the argument corresponding to a [%r] conversion. *) -(** {6 Format string description} *) +(** {1 Format string description} *) (** The format is a character string which contains three types of objects: @@ -212,7 +212,7 @@ val bscanf : Scanning.scanbuf -> ('a, 'b, 'c, 'd) scanner one argument for the function [f], - scanning indications to specify boundaries of tokens. *) -(** {7 The space character in format strings} *) +(** {2 The space character in format strings} *) (** As mentioned above, a plain character in the format string is just matched with the characters of the input; however, one character is a @@ -228,7 +228,7 @@ val bscanf : Scanning.scanbuf -> ('a, 'b, 'c, 'd) scanner input with various whitespace in it, such as [Price = 1 $], [Price = 1 $], or even [Price=1$]. *) -(** {7 Conversion specifications in format strings} *) +(** {2 Conversion specifications in format strings} *) (** Conversion specifications consist in the [%] character, followed by an optional flag, an optional field width, and followed by one or @@ -335,7 +335,7 @@ val bscanf : Scanning.scanbuf -> ('a, 'b, 'c, 'd) scanner [Str]), stream parsers, [ocamllex]-generated lexers, [ocamlyacc]-generated parsers. *) -(** {7 Scanning indications in format strings} *) +(** {2 Scanning indications in format strings} *) (** Scanning indications appear just after the string conversions [%s] and [%\[ range \]] to delimit the end of the token. A scanning @@ -359,7 +359,7 @@ val bscanf : Scanning.scanbuf -> ('a, 'b, 'c, 'd) scanner or carefully double check the format strings that contain ['\@'] characters). *) -(** {7 Exceptions during scanning} *) +(** {2 Exceptions during scanning} *) (** Scanners may raise the following exceptions when the input cannot be read according to the format string: @@ -379,7 +379,7 @@ val bscanf : Scanning.scanbuf -> ('a, 'b, 'c, 'd) scanner [End_of_file]: if the end of input is reached the conversion succeeds and simply returns the characters read so far, or [""] if none were read. *) -(** {6 Specialized formatted input functions} *) +(** {1 Specialized formatted input functions} *) ##V<5##val fscanf : in_channel -> ('a, 'b, 'c, 'd) scanner ##V<5##(** Same as {!Scanf.bscanf}, but reads from the given channel. @@ -410,7 +410,7 @@ val kscanf : error handling function [ef] with the scanning buffer and the exception that aborted the scanning process. *) -(** {6 Reading format strings from input} *) +(** {1 Reading format strings from input} *) val bscanf_format : Scanning.scanbuf -> ('a, 'b, 'c, 'd, 'e, 'f) format6 -> diff --git a/src/batSeq.mli b/src/batSeq.mli index 5dbe5c5b3..a434b54e0 100644 --- a/src/batSeq.mli +++ b/src/batSeq.mli @@ -52,7 +52,7 @@ val enum : 'a t -> 'a BatEnum.t Since enumerations are consumable and sequence are not, it is not possible to have the inverse operations, i.e. [of_enum] *) -(** {6 Base operations} *) +(** {1 Base operations} *) val length : 'a t -> int (** Return the number of elements of the given sequence. This may @@ -93,7 +93,7 @@ val concat : 'a t t -> 'a t val flatten : 'a t t -> 'a t (** Same as {!concat}. *) -(** {6 Constructors} *) +(** {1 Constructors} *) val nil : 'a t (** [nil = fun () -> Nil] *) @@ -117,7 +117,9 @@ val make : int -> 'a -> 'a t val init : int -> (int -> 'a) -> 'a t (** [init n f] returns the sequence returning the results of [f 0], - [f 1].... [f (n-1)]. @raise Invalid_argument if [n < 0]. *) + [f 1].... [f (n-1)]. + + @raise Invalid_argument if [n < 0]. *) val of_list : 'a list -> 'a t (** Convenience function to build a seq from a list. @@ -144,7 +146,7 @@ val concat_map: ('a -> 'b t) -> 'a t -> 'b t (** Alias for {!flat_map}. @since 3.4.0 *) -(** {6 Iterators} *) +(** {1 Iterators} *) val iter : ('a -> unit) -> 'a t -> unit (** [iter f s] applies [f] to all the elements of the sequence. Eager. *) @@ -208,7 +210,7 @@ val equal : ?eq:('a -> 'a -> bool) -> 'a t -> 'a t -> bool @param eq optional equality function (default {!Pervasives.(=)}) @since 2.2.0 *) -(** {6 Sequence scanning} +(** {1 Sequence scanning} Most functions in the following sections have a shortcut semantic similar to the behavior of the usual (&&) and (||) operators : @@ -237,7 +239,7 @@ val mem : 'a -> 'a t -> bool [l]. Eager, shortcut. *) -(** {6 Sequence searching} *) +(** {1 Sequence searching} *) val find : ('a -> bool) -> 'a t -> 'a option (** [find p s] returns the first element of [s] such as [p e] @@ -269,13 +271,13 @@ val filter_map : ('a -> 'b option) -> 'a t -> 'b t mapped by [f]. Lazy. *) -(** {6 Association sequences} *) +(** {1 Association sequences} *) val assoc : 'a -> ('a * 'b) t -> 'b option (** [assoc a s] returns the value associated with key [a] in the sequence of pairs [s]. Eager, shortcut. *) -(** {6 Sequence transformations} *) +(** {1 Sequence transformations} *) val take : int -> 'a t -> 'a t (** [take n s] returns up to the [n] first elements from sequence @@ -293,7 +295,7 @@ val drop_while : ('a -> bool) -> 'a t -> 'a t (** [drop_while f s] returns the sequence [s] with the first elements satisfying the predicate [f] dropped. Lazy. *) -(** {6 Sequence of pairs} *) +(** {1 Sequence of pairs} *) val split : ('a * 'b) t -> 'a t * 'b t (** [split s = (map fst s, map snd s)]. Lazy. *) @@ -303,7 +305,7 @@ val combine : 'a t -> 'b t -> ('a * 'b) t @raise Invalid_argument if given sequences of different length. *) -(** {6 Printing} *) +(** {1 Printing} *) val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'b -> unit) -> 'a BatInnerIO.output -> 'b t -> unit (**Print the contents of a sequence*) diff --git a/src/batSet.mli b/src/batSet.mli index 31c1209ad..c5be93d7c 100644 --- a/src/batSet.mli +++ b/src/batSet.mli @@ -412,15 +412,15 @@ sig - (** {6 Boilerplate code}*) + (** {1 Boilerplate code}*) - (** {7 Printing}*) + (** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> elt -> unit) -> 'a BatInnerIO.output -> t -> unit - (** {6 Override modules}*) + (** {1 Override modules}*) (** The following modules replace functions defined in {!Set} with functions @@ -490,7 +490,7 @@ module Make2(O1 : OrderedType) (O2 : OrderedType) : sig (** cartesian product of the two sets *) end -(** {6 Common instantiations} *) +(** {1 Common instantiations} *) module Int : S with type elt = int module Int32 : S with type elt = int32 @@ -903,16 +903,16 @@ val of_seq : 'a BatSeq.t -> 'a t @since 3.3.0 *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'c -> unit) -> 'a BatInnerIO.output -> 'c t -> unit -(** {6 Incubator} *) +(** {1 Incubator} *) module Incubator : sig val op_map : ('a -> 'b) -> 'a t -> 'b t @@ -928,7 +928,7 @@ end module PSet : sig - (** {6 Polymorphic sets} + (** {1 Polymorphic sets} The definitions below describe the polymorphic set interface. @@ -1316,10 +1316,10 @@ module PSet : sig @since 3.3.0 *) - (** {6 Boilerplate code}*) + (** {1 Boilerplate code}*) - (** {7 Printing}*) + (** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'c -> unit) -> diff --git a/src/batStack.mli b/src/batStack.mli index b0e641feb..833931d25 100644 --- a/src/batStack.mli +++ b/src/batStack.mli @@ -41,12 +41,14 @@ val push : 'a -> 'a t -> unit (** [push x s] adds the element [x] at the top of stack [s]. *) val pop : 'a t -> 'a -(** [pop s] removes and returns the topmost element in stack [s], - or @raise Empty if the stack is empty. *) +(** [pop s] removes and returns the topmost element in stack [s]. + + @raise Empty if the stack is empty. *) val top : 'a t -> 'a -(** [top s] returns the topmost element in stack [s], - or @raise Empty if the stack is empty. *) +(** [top s] returns the topmost element in stack [s]. + + @raise Empty if the stack is empty. *) val clear : 'a t -> unit (** Discard all elements from a stack. *) @@ -87,9 +89,9 @@ val of_enum : 'a BatEnum.t -> 'a t Note: if [s] is a stack, [s <> of_enum (enum s)], as [of_enum] reverses the input order. *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) (* Prints the contents of the given stack *) val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'b -> unit) -> 'a BatInnerIO.output -> 'b t -> unit diff --git a/src/batStream.mli b/src/batStream.mli index 5ecba2a5e..3dbb2fbdc 100644 --- a/src/batStream.mli +++ b/src/batStream.mli @@ -59,7 +59,7 @@ exception Error of string accepted, but one of the following components is rejected. *) -(** {6 Stream builders} *) +(** {1 Stream builders} *) val from : (int -> 'a option) -> 'a t (** [Stream.from f] returns a stream built from the function [f]. @@ -84,7 +84,7 @@ val of_bytes : Bytes.t -> char t val of_channel : in_channel -> char t (** Return the stream of the characters read from the input channel. *) -(** {6 Other Stream builders} +(** {1 Other Stream builders} Warning: these functions create streams with fast access; it is illegal to mix them with streams built with [[< >]]; would raise [Failure] @@ -99,7 +99,7 @@ val of_fun : (unit -> 'a) -> 'a t stream. *) -(** {6 Stream iterator} *) +(** {1 Stream iterator} *) val iter : ('a -> unit) -> 'a t -> unit (** [Stream.iter f s] scans the whole stream s, applying function [f] @@ -130,17 +130,19 @@ val filter : ('a -> bool) -> 'a t -> 'a t and return the results in the same order as a stream. *) -(** {6 Predefined parsers} *) +(** {1 Predefined parsers} *) val next : 'a t -> 'a (** Return the first element of the stream and remove it from the - stream. @raise Stream.Failure if the stream is empty. *) + stream. + + @raise Stream.Failure if the stream is empty. *) val empty : 'a t -> unit (** Return [()] if the stream is empty, else raise [Stream.Failure]. *) -(** {6 Useful functions} *) +(** {1 Useful functions} *) val peek : 'a t -> 'a option (** Return [Some] of "the first element" of the stream, or [None] if @@ -160,7 +162,7 @@ val npeek : int -> 'a t -> 'a list elements are available. *) -(** {6 Conversion functions} *) +(** {1 Conversion functions} *) val enum : 'a t -> 'a BatEnum.t (** Convert a stream to an enumeration. @@ -188,13 +190,13 @@ val to_string_fmt : ('a -> string, unit, string) format -> 'a t -> string val to_string_fun : ('a -> string) -> 'a t -> string (** convert stream to string, using given conversion function *) -(** {6 Stream consumers} *) +(** {1 Stream consumers} *) val on_output: 'a BatIO.output-> char t -> unit (** Convert an [output] to a stream.*) -(** {6 Computation over stream} +(** {1 Computation over stream} All the functions in this part are lazy. *) @@ -248,7 +250,7 @@ val drop_while : ('a -> bool) -> 'a t -> 'a t (** [drop_while test stream] returns the remaining suffix of [take_while test stream]. *) -(** {6 Streams pair arithmetic} +(** {1 Streams pair arithmetic} All the functions in this part are lazy. *) @@ -287,7 +289,7 @@ val switch : ('a -> bool) -> 'a t -> 'a t * 'a t order of elements in the source stream is preserved. *) -(** {6 Stream arithmetic} +(** {1 Stream arithmetic} All the functions in this part are lazy.*) @@ -301,11 +303,13 @@ val is_empty : 'a t -> bool (** [is_empty stream] tests whether [stream] is empty. But note that it forces the evaluation of the head element if any. *) -(** {6 Predefined parsers} *) +(** {1 Predefined parsers} *) val next : 'a t -> 'a (** Return the first element of the stream and remove it from the - stream. @raise Stream.Failure if the stream is empty. *) + stream. + + @raise Stream.Failure if the stream is empty. *) diff --git a/src/batString.mli b/src/batString.mli index f05a67c56..0b8c762b1 100644 --- a/src/batString.mli +++ b/src/batString.mli @@ -336,7 +336,7 @@ val compare: t -> t -> int allows the module [String] to be passed as argument to the functors {!Set.Make} and {!Map.Make}. *) -(** {6 Conversions} *) +(** {1 Conversions} *) val enum : string -> char BatEnum.t (** Returns an enumeration of the characters of a string. @@ -402,9 +402,8 @@ val of_char : char -> string *) val to_int : string -> int -(** Returns the integer represented by the given string - or @raise Failure if the string does not represent an - integer. This follows OCaml's int literal rules, so "0x" +(** Returns the integer represented by the given string. + This follows OCaml's int literal rules, so "0x" prefixes hexadecimal integers, "0o" for octal and "0b" for binary. Underscores within the number are allowed for readability but ignored. @@ -416,8 +415,7 @@ val to_int : string -> int *) val to_float : string -> float -(** Returns the float represented by the given string - or @raise Failure if the string does not represent a float. +(** Returns the float represented by the given string. Decimal points aren't required in the given string, as they are for float literals in OCaml, but otherwise the rules for float literals apply. @@ -429,7 +427,7 @@ val to_float : string -> float @raise Failure if the string does not represent a float. *) -(** {6 String traversals} *) +(** {1 String traversals} *) val map : (char -> char) -> string -> string (** [map f s] returns a string where all characters [c] in [s] have been @@ -500,7 +498,7 @@ val iteri : (int -> char -> unit) -> string -> unit ]} *) -(** {6 Finding}*) +(** {1 Finding}*) @@ -597,12 +595,12 @@ val count_char : string -> char -> int *) -(** {6 Transformations}*) +(** {1 Transformations}*) val lchop : ?n:int -> string -> string (** Returns the same string but without the first [n] characters. By default [n] is 1. - If [n] is strictly less than zero @raise Invalid_argument. + @raise Invalid_argument If [n] is strictly less than zero. If the string has [n] or less characters, returns the empty string. Example: @@ -614,7 +612,7 @@ val lchop : ?n:int -> string -> string val rchop : ?n:int -> string -> string (** Returns the same string but without the last [n] characters. By default [n] is 1. - If [n] is strictly less than zero @raise Invalid_argument. + @raise Invalid_argument If [n] is strictly less than zero. If the string has [n] or less characters , returns the empty string. Example: @@ -725,7 +723,7 @@ val rev : string -> string @since 2.1 *) -(** {6 In-Place Transformations}*) +(** {1 In-Place Transformations}*) val rev_in_place : Bytes.t -> unit (** [rev_in_place s] mutates the byte sequence [s], so that its new value is @@ -735,7 +733,7 @@ val rev_in_place : Bytes.t -> unit val in_place_mirror : Bytes.t -> unit (** @deprecated Use {!String.rev_in_place} instead *) -(** {6 Splitting around}*) +(** {1 Splitting around}*) val split_on_char: char -> string -> string list (** [String.split_on_char sep s] returns the list of all (possibly empty) @@ -872,7 +870,7 @@ val implode : char list -> string Example: [String.implode ['b'; 'a'; 'r'] = "bar"] *) -##V>=4.07##(** {6 Iterators} *) +##V>=4.07##(** {1 Iterators} *) ##V>=4.07##val to_seq : t -> char Seq.t ##V>=4.07##(** Iterate on the string, in increasing index order. Modifications of the @@ -887,7 +885,7 @@ val implode : char list -> string ##V>=4.07##(** Create a string from the generator ##V>=4.07## @since 2.10.0 and OCaml 4.07 *) -(** {6 Binary decoding of integers} *) +(** {1 Binary decoding of integers} *) (** The functions in this section binary decode integers from strings. @@ -1027,7 +1025,7 @@ val get_uint8 : string -> int -> int ##V>=4.14##(** [is_valid_utf_16le b] is [true] if and only if [b] contains valid ##V>=4.14## UTF-16LE data. *) -(** {6 Comparisons}*) +(** {1 Comparisons}*) val equal : t -> t -> bool (** String equality *) @@ -1080,9 +1078,9 @@ val edit_distance : t -> t -> int @since 2.2.0 *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print: 'a BatInnerIO.output -> string -> unit (**Print a string. @@ -1217,7 +1215,7 @@ sig external create : int -> _ t = "caml_create_string" - (** {6 Constructors}*) + (** {1 Constructors}*) external of_string : Bytes.t -> _ t = "%identity" ##V>=4.2## [@@ocaml.deprecated "Use Cap.of_bytes instead"] @@ -1290,7 +1288,7 @@ sig val init : int -> (int -> char) -> _ t - (** {6 Conversions}*) + (** {1 Conversions}*) val enum : [> `Read] t -> char BatEnum.t val of_enum : char BatEnum.t -> _ t @@ -1313,7 +1311,7 @@ sig val to_float : [> `Read] t -> float - (** {6 String traversals}*) + (** {1 String traversals}*) val map : (char -> char) -> [>`Read] t -> _ t val mapi : (int -> char -> char) -> [>`Read] t -> _ t @@ -1332,7 +1330,7 @@ sig val iter : (char -> unit) -> [> `Read] t -> unit - (** {6 Finding}*) + (** {1 Finding}*) val index : [>`Read] t -> char -> int @@ -1364,7 +1362,7 @@ sig val count_char : [> `Read] t -> char -> int - (** {6 Transformations}*) + (** {1 Transformations}*) val lchop : ?n:int -> [> `Read] t -> _ t @@ -1411,7 +1409,7 @@ sig val repeat: [> `Read] t -> int -> _ t - (** {6 Splitting around}*) + (** {1 Splitting around}*) val split : [> `Read] t -> by:[> `Read] t -> _ t * _ t val rsplit : [> `Read] t -> by:[> `Read] t -> _ t * _ t @@ -1428,14 +1426,14 @@ sig val implode : char list -> _ t - (** {6 Comparisons}*) + (** {1 Comparisons}*) val compare: [> `Read] t -> [> `Read] t -> int val icompare: [> `Read] t -> [> `Read] t -> int - (** {7 Printing}*) + (** {2 Printing}*) val print: 'a BatInnerIO.output -> [> `Read] t -> unit @@ -1445,7 +1443,7 @@ sig (**/**) - (** {6 Undocumented operations} *) + (** {1 Undocumented operations} *) external unsafe_get : [> `Read] t -> int -> char = "%string_unsafe_get" external unsafe_set : [> `Write] t -> int -> char -> unit = "%string_unsafe_set" diff --git a/src/batSubstring.mli b/src/batSubstring.mli index d92b98684..ab87c3d52 100644 --- a/src/batSubstring.mli +++ b/src/batSubstring.mli @@ -85,14 +85,16 @@ val triml : int -> t -> t val trimr : int -> t -> t (** [trimr k sus] returns sus less its rightmost k characters; or the empty string at the beginning of sus if it has less than k - characters. @raise Invalid_argument if [k < 0], even in the partial - application [trimr k]. + characters. + + @raise Invalid_argument if [k < 0], even in the partial application [trimr k]. *) val get : t -> int -> char (** [get sus k] returns the k'th character of the substring; that - is, s(i+k) where sus = (s, i, n). @raise Invalid_argument if - [k<0] or [k>=n]. *) + is, s(i+k) where sus = (s, i, n). + + @raise Invalid_argument if [k<0] or [k>=n]. *) val size : t -> int (** [size (s, i, n)] returns the size of the substring, that is, [n]. @@ -107,8 +109,9 @@ val slice : t -> int -> int option -> t @raise Invalid_argument if [i' < 0] or [i' > n]. [slice sus i' (Some n')] returns the substring [(s, i+i', n')], - where [sus] = [(s, i, n)]. @raise Invalid_argument if [i' < 0] - or [n' < 0] or [i'+n' >= n]. + where [sus] = [(s, i, n)]. + + @raise Invalid_argument if [i' < 0] or [n' < 0] or [i'+n' >= n]. *) val concat : t list -> string @@ -146,8 +149,12 @@ val index : t -> char -> int val index_from : t -> int -> char -> int (** [index_from sus i c] returns the index of the first occurrence of [c] in - [sus] after the index [i] or @raise Not_found otherwise. If [i] is beyond - the range of [sus], @raise Invalid_argument. It is equivalent to [i + index (triml i sus) c]. *) + [sus] after the index [i]. + @raise Not_found otherwise. + @raise Invalid_argument If [i] is beyond + the range of [sus]. + + It is equivalent to [i + index (triml i sus) c]. *) val rindex : t -> char -> int (** [rindex sus c] returns the index of the last occurrence of [c] in [sus] or @@ -155,8 +162,12 @@ val rindex : t -> char -> int val rindex_from : t -> int -> char -> int (** [index_from sus i c] returns the index of the last occurrence of [c] in [sus] - before the index [i] or @raise Not_found otherwise. If [i] is beyond the - range of [sus], @raise Invalid_argument. It is equivalent to [rindex (trimr i sus) c]. *) + before the index [i]. + @raise Not_found otherwise. + @raise Invalid_argument If [i] is beyond the + range of [sus]. + + It is equivalent to [rindex (trimr i sus) c]. *) val contains : t -> char -> bool (** [contains s c] tests if character [c] appears in the substring [s]. @@ -229,8 +240,9 @@ val splitr : (char -> bool) -> t -> t * t val split_at : int -> t -> t * t (** [split_at sus k] returns the pair [(sus1, sus2)] of substrings, where [sus1] contains the first [k] characters of [sus], and - [sus2] contains the rest. @raise Invalid_argument if [k < 0] or - [k > size sus]. + [sus2] contains the rest. + + @raise Invalid_argument if [k < 0] or [k > size sus]. *) (* NOT IMPLEMENTED diff --git a/src/batSys.mli b/src/batSys.mli index d8fdfe93c..0d5a9390b 100644 --- a/src/batSys.mli +++ b/src/batSys.mli @@ -60,7 +60,9 @@ external rename : string -> string -> unit = "caml_sys_rename" external getenv : string -> string = "caml_sys_getenv" (** Return the value associated to a variable in the process - environment. @raise Not_found if the variable is unbound. *) + environment. + + @raise Not_found if the variable is unbound. *) val getenv_opt: string -> string option (** Return the value associated to a variable in the process @@ -115,7 +117,7 @@ val os_type : string ##V>=4.4## ##V>=4.4##val backend_type : backend_type ##V>=4.4##(** Backend type currently executing the OCaml program. -##V>=4.4## @ since 2.5.3 and 4.04 +##V>=4.4## @since 2.5.3 and 4.04 ##V>=4.4## *) ##V>=4.1##val unix : bool @@ -171,7 +173,7 @@ val max_array_length : int ##V>=5.1##external is_regular_file : string -> bool = "caml_sys_is_regular_file" -(** {6 Signal handling} *) +(** {1 Signal handling} *) type signal_behavior = Sys.signal_behavior = @@ -197,7 +199,7 @@ val set_signal : int -> signal_behavior -> unit (** Same as {!Sys.signal} but return value is ignored. *) -(** {7 Signal numbers for the standard POSIX signals.} *) +(** {2 Signal numbers for the standard POSIX signals.} *) val sigabrt : int (** Abnormal termination *) @@ -342,7 +344,7 @@ val files_of: string -> string BatEnum.t ##V>=4.3##(** Return whether runtime warnings are currently enabled. ##V>=4.3## @since 2.5.0 and OCaml 4.03 *) -(** {6 Optimization} *) +(** {1 Optimization} *) ##V>=4.3##external opaque_identity : 'a -> 'a = "%opaque" ##V=4.2##val opaque_identity : 'a -> 'a diff --git a/src/batText.mli b/src/batText.mli index 9cbeecad5..c13264a22 100644 --- a/src/batText.mli +++ b/src/batText.mli @@ -39,7 +39,7 @@ - concat, substring, insert, remove operations in amortized logarithmic time - access to and modification of ropes in logarithmic time - {8 Functional nature and persistence} + {3 Functional nature and persistence} All operations are non-destructive: the original rope is never modified. When a new rope is returned as the result of an operation, it will share as much data @@ -56,7 +56,7 @@ calling [balance] after each modification would defeat the purpose of amortization. - {8 Limitations} + {3 Limitations} The length of ropes is limited to approximately 700 Mb on 32-bit architectures, 220 Gb on 64 bit architectures. @@ -73,7 +73,7 @@ exception Out_of_bounds val max_length : int (** Maximum length of the rope (number of UTF-8 characters). *) -(** {6 Creation and conversions} *) +(** {1 Creation and conversions} *) val empty : t (** The empty rope. *) @@ -108,7 +108,7 @@ val implode : BatUChar.t list -> t the characters in the list [cs]. *) -(** {6 Properties } *) +(** {1 Properties } *) val is_empty : t -> bool (** Returns whether the rope is empty or not. *) @@ -125,7 +125,7 @@ val balance : t -> t automatically rebalanced when their height exceeds a given threshold, but [balance] allows to invoke that operation explicitly. *) -(** {6 Operations } *) +(** {1 Operations } *) val append : t -> t -> t (** [append r u] concatenates the [r] and [u] ropes. In general, it operates @@ -184,7 +184,7 @@ val concat : t -> t list -> t inserting the separator rope [sep] between each. *) -(** {6 Iteration} *) +(** {1 Iteration} *) val iter : (BatUChar.t -> unit) -> t -> unit (** [iter f r] applies [f] to all the characters in the [r] rope, @@ -244,7 +244,7 @@ val of_enum : BatUChar.t BatEnum.t -> t (** converts the enumeration into a rope @since 2.2.0 *) -(** {6 Finding}*) +(** {1 Finding}*) val index : t -> BatUChar.t -> int (** [index s c] returns the position of the leftmost @@ -412,7 +412,7 @@ val replace : str:t -> sub:t -> by:t -> bool * t within [str] has been replaced by the rope [by]. The boolean is [true] if a substitution has taken place, [false] otherwise. *) -(** {6 Splitting around}*) +(** {1 Splitting around}*) val split : t -> t -> t * t (** [split s sep] splits the rope [s] between the first diff --git a/src/batUnit.mli b/src/batUnit.mli index 973e2a0a5..e046aaab1 100644 --- a/src/batUnit.mli +++ b/src/batUnit.mli @@ -50,7 +50,7 @@ val ord : t -> t -> BatOrd.order val equal : t -> t -> bool (** Always returns true. *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {7 Printing}*) +(** {2 Printing}*) val print: 'a BatInnerIO.output -> unit -> unit diff --git a/src/batUnix.mli b/src/batUnix.mli index b765c669b..93a155c5e 100644 --- a/src/batUnix.mli +++ b/src/batUnix.mli @@ -34,7 +34,7 @@ @documents Unix *) -(** {6 Error report} *) +(** {1 Error report} *) type error = Unix.error = @@ -128,7 +128,7 @@ val handle_unix_error : ('a -> 'b) -> 'a -> 'b describing the error and exits with code 2. *) -(** {6 Access to the process environment} *) +(** {1 Access to the process environment} *) val environment : unit -> string array @@ -146,7 +146,10 @@ val environment : unit -> string array val getenv : string -> string (** Return the value associated to a variable in the process - environment. @raise Not_found if the variable is unbound. + environment. + + @raise Not_found if the variable is unbound. + (This function is identical to {!Sys.getenv}.) *) ##V>=4.6##val unsafe_getenv : string -> string @@ -170,7 +173,7 @@ val putenv : string -> string -> unit and [value] its new associated value. *) -(** {6 Process handling} *) +(** {1 Process handling} *) type process_status = Unix.process_status = @@ -276,7 +279,7 @@ val nice : int -> int lower priorities.) Return the new nice value. *) -(** {6 Basic file input/output} *) +(** {1 Basic file input/output} *) type file_descr = Unix.file_descr @@ -378,7 +381,7 @@ val single_write_substring : file_descr -> string -> int -> int -> int ##V>=5.2## (_, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t -> ##V>=5.2## int -> int -> int -(** {6 Interfacing with the standard input/output library} *) +(** {1 Interfacing with the standard input/output library} *) val in_channel_of_descr : file_descr -> in_channel (** Create an input channel reading from the given descriptor. @@ -397,7 +400,7 @@ val descr_of_out_channel : out_channel -> file_descr (** Return the descriptor corresponding to an output channel. *) -(** {6 Interfacing with the standard input/output library} *) +(** {1 Interfacing with the standard input/output library} *) val input_of_descr: ?autoclose:bool -> ?cleanup:bool -> file_descr -> BatInnerIO.input (** Create an {!type:input} reading from the given descriptor. @@ -455,7 +458,7 @@ val descr_of_output : unit BatInnerIO.output -> file_descr -(** {6 Seeking and truncating} *) +(** {1 Seeking and truncating} *) type seek_command = Unix.seek_command = @@ -476,7 +479,7 @@ val ftruncate : file_descr -> int -> unit to the given size. *) -(** {6 File status} *) +(** {1 File status} *) type file_kind = Unix.file_kind = @@ -519,7 +522,7 @@ val isatty : file_descr -> bool (** Return [true] if the given file descriptor refers to a terminal or console window, [false] otherwise. *) -(** {6 File operations on large files} *) +(** {1 File operations on large files} *) module LargeFile : sig @@ -555,7 +558,7 @@ end whose sizes are greater than [max_int]. *) -##V>=4.6##(** {6 Mapping files into memory} *) +##V>=4.6##(** {1 Mapping files into memory} *) ##V>=4.6## ##V=4.6##val map_file : ##V=4.6## file_descr -> ?pos:int64 -> ('a, 'b) CamlinternalBigarray.kind -> @@ -612,7 +615,7 @@ end ##V>=4.6## validation fails. ##V>=4.6## @since 2.8.0 and OCaml 4.06.0 *) -(** {6 Operations on file names} *) +(** {1 Operations on file names} *) val unlink : string -> unit @@ -647,7 +650,7 @@ val rename : string -> string -> unit ##V>=4.13## @since 3.4.0 and OCaml 4.13.0 *) -(** {6 File permissions and ownership} *) +(** {1 File permissions and ownership} *) type access_permission = Unix.access_permission = @@ -676,10 +679,12 @@ val umask : int -> int val access : string -> access_permission list -> unit (** Check that the process has the given permissions over the named - file. @raise Unix_error otherwise. *) + file. + @raise Unix_error otherwise. *) -(** {6 Operations on file descriptors} *) + +(** {1 Operations on file descriptors} *) val dup : @@ -717,7 +722,7 @@ val clear_close_on_exec : file_descr -> unit See {!Unix.set_close_on_exec}.*) -(** {6 Directories} *) +(** {1 Directories} *) val mkdir : string -> file_perm -> unit @@ -753,7 +758,7 @@ val closedir : dir_handle -> unit -(** {6 Pipes and redirections} *) +(** {1 Pipes and redirections} *) val pipe : ##V>=4.5## ?cloexec:bool -> @@ -766,7 +771,7 @@ val mkfifo : string -> file_perm -> unit (** Create a named pipe with the given permissions. *) -(** {6 High-level process and redirection management} *) +(** {1 High-level process and redirection management} *) val open_process_in : ?autoclose: bool -> ?cleanup:bool -> string -> BatInnerIO.input (** High-level pipe and process management. This function @@ -965,7 +970,7 @@ val create_process_env : [env] specifies the environment passed to the program. *) -(** {6 Symbolic links} *) +(** {1 Symbolic links} *) ##V<4.3##val symlink : string -> string -> unit ##V<4.3##(** [symlink source dest] creates the file [dest] as a symbolic link ##V<4.3## to the file [source]. *) @@ -1022,7 +1027,7 @@ val readlink : string -> string (** Read the contents of a link. *) -(** {6 Polling} *) +(** {1 Polling} *) val select : @@ -1039,7 +1044,7 @@ val select : and over which an exceptional condition is pending (third component). *) -(** {6 Locking} *) +(** {1 Locking} *) type lock_command = Unix.lock_command = @@ -1088,7 +1093,7 @@ val with_locked_file : kind:[`Read|`Write] -> string -> (file_descr -> 'a) -> 'a @param kind specifies whether the lock is read-only or read-write. *) -(** {6 Signals} +(** {1 Signals} Note: installation of signal handlers is performed via the functions {!Sys.signal} and {!Sys.set_signal}. *) @@ -1124,7 +1129,7 @@ val pause : unit -> unit (** Wait until a non-ignored, non-blocked signal is delivered. *) -(** {6 Time functions} *) +(** {1 Time functions} *) type process_times = Unix.process_times = @@ -1228,7 +1233,7 @@ val setitimer : after its next expiration. *) -(** {6 User id, group id} *) +(** {1 User id, group id} *) val getuid : unit -> int @@ -1302,7 +1307,7 @@ val getgrgid : int -> group_entry @raise Not_found if no such entry can be found. *) -(** {6 Internet addresses} *) +(** {1 Internet addresses} *) type inet_addr = Unix.inet_addr @@ -1313,8 +1318,9 @@ val inet_addr_of_string : string -> inet_addr address to its internal representation. The argument string consists of 4 numbers separated by periods ([XXX.YYY.ZZZ.TTT]) for IPv4 addresses, and up to 8 numbers separated by colons - for IPv6 addresses. @raise Failure when given a string that - does not match these formats. *) + for IPv6 addresses. + + @raise Failure when given a string that does not match these formats. *) val string_of_inet_addr : inet_addr -> string (** Return the printable representation of the given Internet address. @@ -1339,7 +1345,7 @@ val inet6_addr_loopback : inet_addr ##V>=4.12##(** Whether the given [inet_addr] is an IPv6 address. ##V>=4.12## @since 3.3.0 and 4.12.0 *) -(** {6 Sockets} *) +(** {1 Sockets} *) type socket_domain = Unix.socket_domain = @@ -1456,7 +1462,7 @@ val sendto_substring : -(** {6 Socket options} *) +(** {1 Socket options} *) type socket_bool_option = Unix.socket_bool_option = @@ -1536,7 +1542,7 @@ val getsockopt_error : file_descr -> error option (** Return the error condition associated with the given socket, and clear it. *) -(** {6 High-level network connection functions} *) +(** {1 High-level network connection functions} *) val open_connection : ?autoclose:bool -> sockaddr -> BatInnerIO.input * unit BatInnerIO.output (** Connect to a server at the given address. @@ -1587,7 +1593,7 @@ val establish_server : ?autoclose:bool -> ?cleanup:bool -> (BatInnerIO.input -> ensure proper cleanup. *) -(** {6 Host and protocol databases} *) +(** {1 Host and protocol databases} *) type host_entry = Unix.host_entry = @@ -1702,7 +1708,7 @@ val getnameinfo : sockaddr -> getnameinfo_option list -> name_info @raise Not_found if an error occurs. *) -(** {6 Terminal interface} *) +(** {1 Terminal interface} *) (** The following functions implement the POSIX standard terminal @@ -1817,7 +1823,7 @@ val setsid : unit -> int its controlling terminal. *) -(** {6 Small tools} *) +(** {1 Small tools} *) val is_directory : string -> bool (** [is_directory filename] returns true if [filename] refers to a directory (or symlink of a directory) *) @@ -1828,7 +1834,7 @@ val restart_on_EINTR : ('a -> 'b) -> 'a -> 'b (** - {6 Thread-safety internals} + {1 Thread-safety internals} Unless you are attempting to adapt Batteries Included to a new model of concurrency, you probably won't need this. @@ -1844,7 +1850,7 @@ val lock: BatConcurrent.lock ref concurrency model, set the lock appropriately. *) -(** {6 Obsolete stuff} *) +(** {1 Obsolete stuff} *) val in_channel_of_descr: file_descr -> BatInnerIO.input (** @deprecated use {!input_of_descr}*) diff --git a/src/batUref.mli b/src/batUref.mli index e9cbf8009..75306445c 100644 --- a/src/batUref.mli +++ b/src/batUref.mli @@ -47,7 +47,7 @@ val equal : 'a uref -> 'a uref -> bool urefs, either because they are physically the same or because they have been {!unite}d. *) -(** {6 Printing} *) +(** {1 Printing} *) val print : ('a, 'b) BatIO.printer -> ('a uref, 'b) BatIO.printer (** Print the uref. *) diff --git a/src/batVect.mli b/src/batVect.mli index f722e32ea..4fcb59f4f 100644 --- a/src/batVect.mli +++ b/src/batVect.mli @@ -43,7 +43,7 @@ - concat, substring, insert, remove operations in amortized logarithmic time - access to and modification of vectors in logarithmic time - {8 Functional nature and persistence} + {3 Functional nature and persistence} All operations but [destructive_set] (provided for efficient ephemeral usage) are non-destructive: the original vect is never modified. When a new vect is @@ -73,7 +73,7 @@ exception Out_of_bounds val max_length : int (** Maximum length of the vect. *) -(** {6 Creation and conversions} *) +(** {1 Creation and conversions} *) val empty : 'a t (** The empty vect. *) @@ -105,7 +105,7 @@ val init : int -> (int -> 'a) -> 'a t @raise Invalid_argument if [n < 0] or [n > max_length].*) -(** {6 Properties } *) +(** {1 Properties } *) val is_empty : 'a t -> bool (** Returns whether the vect is empty or not. *) @@ -116,7 +116,7 @@ val height : 'a t -> int val length : 'a t -> int (** Returns the length of the vect ([O(1)]). *) -(** {6 Operations } *) +(** {1 Operations } *) val balance : 'a t -> 'a t (** [balance r] returns a balanced copy of the [r] vect. Note that vects are @@ -181,7 +181,7 @@ val remove : int -> int -> 'a t -> 'a t [length r - n]. Operates in amortized [O(log(size r))] time. *) -(** {6 Conversion}*) +(** {1 Conversion}*) val enum : 'a t -> 'a BatEnum.t (** Returns an enumeration of the elements of the vector. @@ -197,7 +197,7 @@ val backwards : 'a t -> 'a BatEnum.t val of_backwards : 'a BatEnum.t -> 'a t (** Build a vector from an enumeration, from last to first.*) -(** {6 Iteration and higher-order functions } *) +(** {1 Iteration and higher-order functions } *) val iter : ('a -> unit) -> 'a t -> unit (** [iter f r] applies [f] to all the elements in the [r] vect, @@ -256,7 +256,7 @@ val mapi : (int -> 'a -> 'b) -> 'a t -> 'b t with [<>]. Operates in [O(n)] time. *) *) -(**{6 Predicates}*) +(**{1 Predicates}*) val for_all : ('a -> bool) -> 'a t -> bool (** [for_all p [a0; a1; ...; an]] checks if all elements of the vect @@ -313,7 +313,7 @@ val partition : ('a -> bool) -> 'a t -> 'a t * 'a t elements of [v] that do not satisfy [p]. The order of the elements in the input vect is preserved. *) -(** {6 Convenience Functions} *) +(** {1 Convenience Functions} *) val first : 'a t -> 'a val last : 'a t -> 'a @@ -325,7 +325,7 @@ val shift : 'a t -> 'a * 'a t val pop : 'a t -> 'a * 'a t (** Return the last element of a vector and its first [n-1] elements. *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'b -> unit) -> 'a BatInnerIO.output -> 'b t -> unit @@ -337,7 +337,7 @@ val ord : 'a BatOrd.ord -> 'a t BatOrd.ord val invariants : _ t -> unit (**/**) -(** {6 Override modules}*) +(** {1 Override modules}*) (** Operations on {!BatVect} with labels. @@ -379,7 +379,7 @@ module Labels : sig val partition : f:('a -> bool) -> 'a t -> 'a t * 'a t end -(** {6 Functorial interface} *) +(** {1 Functorial interface} *) module type RANDOMACCESS = sig @@ -422,7 +422,7 @@ module Make : operating on them. *) - (** {6 Creation and conversions} *) + (** {1 Creation and conversions} *) val empty : 'a t (** The empty vect. *) @@ -461,7 +461,7 @@ val init : int -> (int -> 'a) -> 'a t @raise Invalid_argument if [n < 0] or [n > max_length].*) -(** {6 Properties } *) +(** {1 Properties } *) val is_empty : 'a t -> bool (** Returns whether the vect is empty or not. *) @@ -472,7 +472,7 @@ val height : 'a t -> int val length : 'a t -> int (** Returns the length of the vect ([O(1)]). *) -(** {6 Operations } *) +(** {1 Operations } *) val balance : 'a t -> 'a t (** [balance r] returns a balanced copy of the [r] vect. Note that vects are @@ -537,7 +537,7 @@ val remove : int -> int -> 'a t -> 'a t [length r - n]. Operates in amortized [O(log(size r))] time. *) -(** {6 Conversion}*) +(** {1 Conversion}*) val enum : 'a t -> 'a BatEnum.t (** Returns an enumeration of the elements of the vector. @@ -553,7 +553,7 @@ val backwards : 'a t -> 'a BatEnum.t val of_backwards : 'a BatEnum.t -> 'a t (** Build a vector from an enumeration, from last to first.*) -(** {6 Iteration and higher-order functions } *) +(** {1 Iteration and higher-order functions } *) val iter : ('a -> unit) -> 'a t -> unit (** [iter f r] applies [f] to all the elements in the [r] vect, @@ -612,7 +612,7 @@ val mapi : (int -> 'a -> 'b) -> 'a t -> 'b t with [<>]. Operates in [O(n)] time. *) *) -(**{6 Predicates}*) +(**{1 Predicates}*) val for_all : ('a -> bool) -> 'a t -> bool (** [for_all p [a0; a1; ...; an]] checks if all elements of the vect @@ -670,7 +670,7 @@ val partition : ('a -> bool) -> 'a t -> 'a t * 'a t elements of [v] that do not satisfy [p]. The order of the elements in the input vect is preserved. *) -(** {6 Convenience Functions} *) +(** {1 Convenience Functions} *) val first : 'a t -> 'a @@ -683,9 +683,9 @@ val shift : 'a t -> 'a * 'a t val pop : 'a t -> 'a * 'a t (** Return the last element of a vector and its first [n-1] elements. *) -(** {6 Boilerplate code}*) +(** {1 Boilerplate code}*) -(** {6 Override modules}*) +(** {1 Override modules}*) (** Operations on {!BatVect} with labels. @@ -727,7 +727,7 @@ val pop : 'a t -> 'a * 'a t val partition : f:('a -> bool) -> 'a t -> 'a t * 'a t end -(** {7 Printing}*) +(** {2 Printing}*) val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'b -> unit) -> 'a BatInnerIO.output -> 'b t -> unit diff --git a/src/index.mld b/src/index.mld index 319edcfbb..c14f3bcb7 100644 --- a/src/index.mld +++ b/src/index.mld @@ -1,3 +1,4 @@ +{0 Batteries user guide} OCaml Batteries Included documentation. OCaml Batteries included (or simply "Batteries") is a community-driven effort to standardize on an consistent, documented, and comprehensive development platform for the OCaml programming language. @@ -31,42 +32,42 @@ repo}, and our {{:https://github.com/ocaml-batteries-team/batteries-included/issues?sort=created&direction=desc&state=open}Issue tracker}. -{6 New Data Structures in Batteries} +{1 New Data Structures in Batteries} {!modules: BatBitSet BatCache BatDeque BatDllist BatDynArray BatEnum BatFingerTree BatGlobal BatHashcons BatHeap BatIMap BatISet BatLazyList BatMultiPMap BatRefList BatSeq BatSplay BatText BatUChar BatUref BatUTF8 BatVect} -{6 New Modules in Batteries} +{1 New Modules in Batteries} {!modules: BatBase64 BatCharParser BatFile BatInterfaces BatIO BatLog BatLogger BatNumber BatOptParse BatParserCo BatResult BatReturn } -{6 Builtin Types as Modules} +{1 Builtin Types as Modules} {!modules: BatBool BatChar BatFloat BatInt BatInt32 BatInt64 BatNativeint BatOption BatRef BatTuple BatUnit } -{6 Extensions to the Standard Library} +{1 Extensions to the Standard Library} These modules have base library equivalents. When using [open Batteries], [BatFoo] will replace [Foo], so that the new functions are easily available without a [Bat] prefix on the module name. As well, [BatPervasives] is opened into the global namespace. Finally, the previous versions of replaced modules are available in the [Legacy] module, i.e. [Legacy.Unix] and [Legacy.Pervasives]. -{!modules: BatArray BatBigarray BatBig_int BatBuffer BatComplex +{!modules: BatArray BatBigarray BatBig_int BatBuffer BatBytes BatComplex BatDigest BatFormat BatGc BatGenlex BatHashtbl BatLexing BatList BatMap BatMarshal BatNum BatPervasives BatPrintexc BatPrintf BatQueue BatRandom BatScanf BatSet BatStack BatStream BatString BatSys BatUnix} -{6 Thread-related Modules} +{1 Thread-related Modules} These modules are available only when compiling with threads. To use them, do [open BatteriesThread] at the top of your code. {!modules: BatConcurrent BatMutex BatRMutex} -{6 Incubator} +{1 Incubator} These modules are available only inside [Batteries.Incubator]. Their interface is not guaranteed stable, and may be changed at any time, @@ -76,6 +77,6 @@ finalized and moved to batteries proper. {!modules: BatBounded BatOrd BatPathGen BatSubstring} -{6 Internal Modules} +{1 Internal Modules} {!modules: BatAvlTree BatInnerIO BatInnerWeaktbl}