PR#7363: start documentation headers at {1

Author: Octachron

manual/tools/caml_tex2.ml

@@ -87,13 +87,13 @@ module Output = struct
     | Ok -> Printf.fprintf ppf "an ok"
     | Warning n -> Printf.fprintf ppf "a warning %d" n
 
-  (** {2 Related latex environment } *)
+  (** {1 Related latex environment } *)
   let env = function
     | Error -> error
     | Warning _ -> warning
     | Ok -> ok_output
 
-  (** {2 Exceptions } *)
+  (** {1 Exceptions } *)
   exception Parsing_error of kind * string
 
   type source = { file:string; lines:int * int; phrase:string; output:string }
@@ -141,7 +141,7 @@ module Output = struct
            and [@@expect warning n] (with n a warning number).\n" s
 
 
-  (** {2 Output analysis} *)
+  (** {1 Output analysis} *)
   let catch_error s =
     if string_match ~!{|Error:|} s 0 then Some Error else None
 
@@ -156,7 +156,7 @@ module Output = struct
     | None, Some e -> e
     | None, None -> Ok
 
-  (** {2 Parsing caml_example options } *)
+  (** {1 Parsing caml_example options } *)
 
   (** Parse [warning=n] options for caml_example options *)
   let parse_warning s =

ocamldoc/odoc_class.ml

@@ -94,7 +94,7 @@ and t_class_type = {
   }
 
 
-(** {2 Functions} *)
+(** {1 Functions} *)
 
 (** Returns the text associated to the given parameter label
    in the given class, or None. *)

ocamldoc/odoc_info.mli

@@ -135,7 +135,7 @@ module Name :
 (** Representation and manipulation of method / function / class / module parameters.*)
 module Parameter :
   sig
-    (** {3 Types} *)
+    (** {2 Types} *)
 
     (** Representation of a simple parameter name *)
     type simple_name = Odoc_parameter.simple_name =
@@ -154,7 +154,7 @@ module Parameter :
     (** A parameter is just a param_info.*)
     type parameter = param_info
 
-    (** {3 Functions} *)
+    (** {2 Functions} *)
 
     (** Access to the name as a string. For tuples, parentheses and commas are added. *)
     val complete_name : parameter -> string
@@ -343,7 +343,7 @@ module Value :
 (** Representation and manipulation of classes and class types.*)
 module Class :
   sig
-    (** {3 Types} *)
+    (** {2 Types} *)
 
     (** To keep the order of elements in a class. *)
     type class_element = Odoc_class.class_element =
@@ -429,7 +429,7 @@ module Class :
           mutable clt_loc : location ;
         }
 
-    (** {3 Functions} *)
+    (** {2 Functions} *)
 
     (** Access to the elements of a class. *)
     val class_elements : ?trans:bool -> t_class -> class_element list
@@ -465,7 +465,7 @@ module Class :
 (** Representation and manipulation of modules and module types. *)
 module Module :
   sig
-    (** {3 Types} *)
+    (** {2 Types} *)
 
     (** To keep the order of elements in a module. *)
     type module_element = Odoc_module.module_element =
@@ -570,7 +570,7 @@ module Module :
           mutable mt_loc : location ;
         }
 
-    (** {3 Functions for modules} *)
+    (** {2 Functions for modules} *)
 
     (** Access to the elements of a module. *)
     val module_elements : ?trans:bool -> t_module -> module_element list
@@ -620,7 +620,7 @@ module Module :
     (** The list of module comments. *)
     val module_comments : ?trans:bool-> t_module -> text list
 
-    (** {3 Functions for module types} *)
+    (** {2 Functions for module types} *)
 
     (** Access to the elements of a module type. *)
     val module_type_elements : ?trans:bool-> t_module_type -> module_element list
@@ -669,7 +669,7 @@ module Module :
   end
 
 
-(** {3 Getting strings from values} *)
+(** {2 Getting strings from values} *)
 
 (** This function is used to reset the names of type variables.
    It must be called when printing the whole type of a function,
@@ -749,7 +749,7 @@ val string_of_attribute : Value.t_attribute -> string
 (** @return a string to describe the given method. *)
 val string_of_method : Value.t_method -> string
 
-(** {3 Miscellaneous functions} *)
+(** {2 Miscelaneous functions} *)
 
 (** Return the first sentence (until the first dot followed by a blank
    or the first blank line) of a text.
@@ -1036,7 +1036,7 @@ module Dep :
     val deps_of_types : ?kernel: bool -> Type.t_type list -> (Type.t_type * (Name.t list)) list
   end
 
-(** {2 Some global variables} *)
+(** {1 Some global variables} *)
 
 module Global :
   sig

ocamldoc/odoc_module.ml

@@ -107,7 +107,7 @@ and t_module_type = {
   }
 
 
-(** {2 Functions} *)
+(** {1 Functions} *)
 
 (** Returns the list of values from a list of module_element. *)
 let values l =
@@ -543,7 +543,7 @@ let module_type_simple_values ?(trans=true) mt =
     (fun v -> not (Odoc_value.is_function v))
     (values (module_type_elements ~trans mt))
 
-(** {2 Functions for modules and module types} *)
+(** {1 Functions for modules and module types} *)
 
 (** The list of classes defined in this module and all its modules, functors, ....
   @param trans indicates if, for aliased modules, we must perform a transitive search.*)

ocamldoc/odoc_texi.ml

@@ -29,7 +29,7 @@ let info_section = ref "OCaml"
 
 let info_entry = ref []
 
-(** {2 Some small helper functions} *)
+(** {1 Some small helper functions} *)
 
 let puts_nl chan s =
   output_string chan s ;
@@ -240,12 +240,13 @@ end
 
 
 
-(** {2 Generation of Texinfo code} *)
+(** {1 Generation of Texinfo code} *)
 
 (** This class generates Texinfo code from text structures *)
 class text =
   object(self)
 
+
   (** Associations between a title number and texinfo code. *)
     val titles = [
       0, "@chapter " ;
@@ -283,7 +284,7 @@ class text =
         (List.map self#texi_of_text_element t)
 
 
-    (** {3 Conversion methods}
+    (** {2 Conversion methods}
        [texi_of_????] converts a [text_element] to a Texinfo string. *)
 
     (** Return the Texinfo code for the [text_element] in parameter. *)
@@ -401,7 +402,7 @@ class texi =
     inherit text
     inherit Odoc_to_text.to_text as to_text
 
-    (** {3 Small helper stuff.} *)
+    (** {2 Small helper stuff.} *)
 
     val maxdepth = 4
 
@@ -455,7 +456,7 @@ class texi =
             | Raw s -> Raw (Str.global_replace re rep s)
             | txt -> txt) t
 
-    (** {3 [text] values generation}
+    (** {2 [text] values generation}
        Generates [text] values out of description parts.
        Redefines some of methods of {! Odoc_to_text.to_text}. *)
 
@@ -567,7 +568,7 @@ class texi =
     method texi_of_info i =
       self#texi_of_text (self#text_of_info i)
 
-    (** {3 Conversion of [module_elements] into Texinfo strings}
+    (** {2 Conversion of [module_elements] into Texinfo strings}
        The following functions convert [module_elements] and their
        description to [text] values then to Texinfo strings using the
        functions above. *)
@@ -909,7 +910,7 @@ class texi =
           self#texi_of_text (Newline :: t @ [Newline])
       )
 
-    (** {3 Generating methods }
+    (** {2 Generating methods }
        These methods write Texinfo code to an [out_channel] *)
 
     (** Generate the Texinfo code for the given list of inherited classes.*)

otherlibs/bigarray/bigarray.mli

@@ -32,7 +32,7 @@
      and {!Pervasives.input_value}).
 *)
 
-(** {6 Element kinds} *)
+(** {1 Element kinds} *)
 
 (** Big arrays can contain elements of the following kinds:
 - IEEE single precision (32 bits) floating-point numbers
@@ -179,7 +179,7 @@ val kind_size_in_bytes : ('a, 'b) kind -> int
 
    @since 4.03.0 *)
 
-(** {6 Array layouts} *)
+(** {1 Array layouts} *)
 
 type c_layout = CamlinternalBigarray.c_layout = C_layout_typ (**)
 (** See {!Bigarray.fortran_layout}.*)
@@ -224,7 +224,7 @@ val c_layout : c_layout layout
 val fortran_layout : fortran_layout layout
 
 
-(** {6 Generic arrays (of arbitrarily many dimensions)} *)
+(** {1 Generic arrays (of arbitrarily many dimensions)} *)
 
 module Genarray :
   sig
@@ -447,7 +447,7 @@ Note that Bigarray.Genarray.map_file raises Sys_error while\n\
 Unix.map_file raises Unix_error."]
   end
 
-(** {6 Zero-dimensional arrays} *)
+(** {1 Zero-dimensional arrays} *)
 
 (** Zero-dimensional arrays. The [Array0] structure provides operations
    similar to those of {!Bigarray.Genarray}, but specialized to the case
@@ -504,7 +504,7 @@ module Array0 : sig
 end
 
 
-(** {6 One-dimensional arrays} *)
+(** {1 One-dimensional arrays} *)
 
 (** One-dimensional arrays. The [Array1] structure provides operations
    similar to those of
@@ -611,7 +611,7 @@ Unix.map_file raises Unix_error."]
 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
@@ -734,7 +734,7 @@ Unix.map_file raises Unix_error."]
 
 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
@@ -882,7 +882,7 @@ Unix.map_file raises Unix_error."]
 
 end
 
-(** {6 Coercions between generic big arrays and fixed-dimension big arrays} *)
+(** {1 Coercions between generic big arrays and fixed-dimension big arrays} *)
 
 external genarray_of_array0 :
   ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genarray.t = "%identity"
@@ -926,7 +926,7 @@ val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array3.t
    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

otherlibs/dynlink/dynlink.mli

@@ -19,7 +19,7 @@ val is_native: bool
 (** [true] if the program is native,
     [false] if the program is bytecode. *)
 
-(** {6 Dynamic loading of compiled files} *)
+(** {1 Dynamic loading of compiled files} *)
 
 val loadfile : string -> unit
 (** In bytecode: load the given bytecode object file ([.cmo] file) or
@@ -42,7 +42,7 @@ val adapt_filename : string -> string
 (** In bytecode, the identity function. In native code, replace the last
     extension with [.cmxs]. *)
 
-(** {6 Access control} *)
+(** {1 Access control} *)
 
 val allow_only: string list -> unit
 (** [allow_only units] restricts the compilation units that
@@ -81,7 +81,7 @@ val allow_unsafe_modules : bool -> unit
     not allowed. In native code, this function does nothing; object files
     with external functions are always allowed to be dynamically linked. *)
 
-(** {6 Deprecated, low-level API for access control} *)
+(** {1 Deprecated, low-level API for access control} *)
 
 (** @deprecated  The functions [add_interfaces], [add_available_units]
     and [clear_available_units] should not be used in new programs,
@@ -109,13 +109,13 @@ val clear_available_units : unit -> unit
 (** Empty the list of compilation units accessible to dynamically-linked
     programs. *)
 
-(** {6 Deprecated, initialization} *)
+(** {1 Deprecated, initialization} *)
 
 val init : unit -> unit
 (** @deprecated Initialize the [Dynlink] library. This function is called
     automatically when needed. *)
 
-(** {6 Error reporting} *)
+(** {1 Error reporting} *)
 
 type linking_error =
     Undefined_global of string
@@ -143,6 +143,6 @@ val error_message : error -> string
 
 (**/**)
 
-(** {6 Internal functions} *)
+(** {1 Internal functions} *)
 
 val digest_interface : string -> string list -> Digest.t