diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs index e3fa0f2aee..94cfc8c9f5 100644 --- a/.git-blame-ignore-revs +++ b/.git-blame-ignore-revs @@ -10,3 +10,5 @@ c5b7900eb40a48e2877db4994a2b2f8d755531e4 1cf80035f66badcc8b4e667cbfd13cb483a7a773 # Upgrade to OCamlformat 0.26.1 1c015488b8d32a0571eaa144a92ab4725bad0b85 +# Upgrade to OCamlformat 0.27.0-preview1 +99333b9df5e71b17b58e50432d34bbea035a9fcf diff --git a/.ocamlformat b/.ocamlformat index 5626d8362a..d1f0849282 100644 --- a/.ocamlformat +++ b/.ocamlformat @@ -1,3 +1,3 @@ module-item-spacing=preserve -version=0.26.1 +version=0.27.0-preview1 ocaml-version=4.02 diff --git a/doc/examples/expansion.mli b/doc/examples/expansion.mli index 5a1923fadc..c642e264ef 100644 --- a/doc/examples/expansion.mli +++ b/doc/examples/expansion.mli @@ -1,7 +1,7 @@ (** Examples of different features of Expansion *) -(** For details on what each of the following examples is showing, -see the explanations in the {{!page-features}Features page} *) +(** For details on what each of the following examples is showing, see the + explanations in the {{!page-features} Features page} *) [@@@warning "-67"] module Simple : sig @@ -23,7 +23,8 @@ module Aliases : sig end module ModuleTypeAliases : sig - (** Demonstrates that module types are not expanded if they're a simple path to another. *) + (** Demonstrates that module types are not expanded if they're a simple path + to another. *) module type A = sig type t @@ -125,7 +126,8 @@ module DeepEquality : sig end module DeepEquality2 : sig - (** Demonstrates expansion involving an equation on a type in a submodule, but the submodule is already a simple signature *) + (** Demonstrates expansion involving an equation on a type in a submodule, but + the submodule is already a simple signature *) module type MODTYPE = sig module X : sig @@ -172,7 +174,8 @@ module ModuleTypeOf : sig end module ModuleTypeOfComplications : sig - (** Demonstrates the interaction of [module type of] and destructive module substitution *) + (** Demonstrates the interaction of [module type of] and destructive module + substitution *) module type S = sig module X : sig diff --git a/doc/examples/markup.mli b/doc/examples/markup.mli index fb05709a19..cfbe849bf3 100644 --- a/doc/examples/markup.mli +++ b/doc/examples/markup.mli @@ -1,21 +1,20 @@ (** Markup examples. *) (** The OCaml manual gives a -{{:https://ocaml.org/manual/ocamldoc.html#ss:ocamldoc-placement}comprehensive example} -of comment placement. This has been replicated in the module Foo below to -show how this is rendered by [odoc]. *) + {{:https://ocaml.org/manual/ocamldoc.html#ss:ocamldoc-placement} + comprehensive example} of comment placement. This has been replicated in + the module Foo below to show how this is rendered by [odoc]. *) module type Foo = sig - (** The first special comment of the file is the comment associated - with the whole module.*) + (** The first special comment of the file is the comment associated with the + whole module.*) - (** Special comments can be placed between elements and are kept - by the OCamldoc tool, but are not associated to any element. - [@]-tags in these comments are ignored.*) + (** Special comments can be placed between elements and are kept by the + OCamldoc tool, but are not associated to any element. [@]-tags in these + comments are ignored.*) (*******************************************************************) - (** Comments like the one above, with more than two asterisks, - are ignored. *) + (** Comments like the one above, with more than two asterisks, are ignored. *) (** The comment for function f. *) val f : int -> int -> int @@ -23,20 +22,20 @@ module type Foo = sig (* Hello, I'm a simple comment :-) *) exception My_exception of (int -> int) * int - (** Comment for exception My_exception, even with a simple comment - between the special comment and the exception.*) + (** Comment for exception My_exception, even with a simple comment between the + special comment and the exception.*) - (** Comment for type weather *) + (** Comment for type weather *) type weather = | Rain of int (** The comment for constructor Rain *) | Sun (** The comment for constructor Sun *) - (** Comment for type weather2 *) + (** Comment for type weather2 *) type weather2 = | Rain of int (** The comment for constructor Rain *) | Sun (** The comment for constructor Sun *) - (** I can continue the comment for type weather2 here - because there is already a comment associated to the last constructor.*) + (** I can continue the comment for type weather2 here because there is already + a comment associated to the last constructor.*) (** The comment for type my_record *) type my_record = { @@ -67,9 +66,8 @@ module type Foo = sig val toto : int (** The comment for attribute toto. *) - (** This comment is not attached to titi since - there is a blank line before titi, but is kept - as a comment in the class. *) + (** This comment is not attached to titi since there is a blank line before + titi, but is kept as a comment in the class. *) val titi : string @@ -126,8 +124,8 @@ module Stop : sig end val foo : string - (** This value appears in the documentation, since the Stop special comment - in the class does not affect the parent module of the class.*) + (** This value appears in the documentation, since the Stop special comment in + the class does not affect the parent module of the class.*) (**/**) @@ -137,14 +135,14 @@ module Stop : sig (**/**) type t = string - (** The type t appears since in the documentation since the previous stop comment - toggled off the "no documentation mode". *) + (** The type t appears since in the documentation since the previous stop + comment toggled off the "no documentation mode". *) end (** {2 Scoping rules} *) module Scope : sig - (** In this floating comment I can refer to type {!t} and value {!v} - declared later in the signature *) + (** In this floating comment I can refer to type {!t} and value {!v} declared + later in the signature *) type t @@ -155,12 +153,12 @@ module Scope : sig val y : int module A : sig - (** In this module I can refer to val {!x} declared above as well as - type {!u} declared later in the parent module. Elements declared - in this signature take priority, so {!y} refers to {!A.y} as - opposed to the [y] declared in the parent signature. - - @see 'markup.mli' for a good time *) + (** In this module I can refer to val {!x} declared above as well as type + {!u} declared later in the parent module. Elements declared in this + signature take priority, so {!y} refers to {!A.y} as opposed to the [y] + declared in the parent signature. + + @see 'markup.mli' for a good time *) val y : string end @@ -174,25 +172,27 @@ module Preamble_examples : sig (** This is the comment attached to the declaration of Hidden__Module *) module Hidden__Module : sig (** This is the top comment declared in the module Hidden__module. - - This is the second paragraph in the module Hidden__module. - - @canonical Odoc_examples.Markup.Module *) + + This is the second paragraph in the module Hidden__module. + + @canonical Odoc_examples.Markup.Module *) type t (** This is a comment on type t *) end module Module = Hidden__Module - (** This comment is on the declaration of Module as an alias of Hidden__Module *) + (** This comment is on the declaration of Module as an alias of Hidden__Module + *) - (** This is the comment attached to the declaration of module Hidden__Module2 *) + (** This is the comment attached to the declaration of module Hidden__Module2 + *) module Hidden__Module2 : sig (** This is the top comment declared in the module Hidden__module2. - - This is the second paragraph in the module Hidden__module2. - - @canonical Odoc_examples.Markup.Module2 *) + + This is the second paragraph in the module Hidden__module2. + + @canonical Odoc_examples.Markup.Module2 *) type t (** This is a comment on type t *) @@ -202,23 +202,22 @@ module Preamble_examples : sig module Nonhidden_module : sig (** This is the top comment declared in the module Hidden__module2. - - This is the second paragraph in the module Hidden__module2. - *) + + This is the second paragraph in the module Hidden__module2. *) end module Module3 = Nonhidden_module - (** This comment is on the declaration of Module3 as an alias of Nonhidden_module *) + (** This comment is on the declaration of Module3 as an alias of + Nonhidden_module *) module Nonhidden_module2 : sig (** This is the top comment declared in the module Hidden__module2. - - This is the second paragraph in the module Hidden__module2. - *) + + This is the second paragraph in the module Hidden__module2. *) end module Module4 = Nonhidden_module2 (** The [modules] special reference can be used to refer to a list of modules. -It uses the synopsis from the modules *) + It uses the synopsis from the modules *) end diff --git a/doc/examples/odoc_examples.ml b/doc/examples/odoc_examples.ml index 794b0e89fb..8b1cbd4db9 100644 --- a/doc/examples/odoc_examples.ml +++ b/doc/examples/odoc_examples.ml @@ -1,7 +1,7 @@ (** Examples of the output from [odoc] *) -(** These examples are intended to be viewed alongside the - source code. See {:https://github.com/ocaml/odoc/tree/master/doc/examples} *) +(** These examples are intended to be viewed alongside the source code. See + {:https://github.com/ocaml/odoc/tree/master/doc/examples} *) module Expansion = Expansion module Resolution = Resolution diff --git a/doc/examples/resolution.mli b/doc/examples/resolution.mli index 06b30790cb..94533a2cd9 100644 --- a/doc/examples/resolution.mli +++ b/doc/examples/resolution.mli @@ -1,8 +1,8 @@ (** Examples of Path, Fragment and Reference Resolution *) -(** This module contains examples of some of the features of Resolution -as described in the page {!page-features}. See the explanations there for -details on what each of these demonstrates. *) +(** This module contains examples of some of the features of Resolution as + described in the page {!page-features}. See the explanations there for + details on what each of these demonstrates. *) [@@@warning "-67"] @@ -28,7 +28,7 @@ end module HiddenAlias : sig (** Demonstrates a reference to an item in a module that's an alias of a - hidden module. *) + hidden module. *) (**/**) @@ -110,8 +110,9 @@ module References : sig end end - (** We can refer unambiguously to {!module-type-A.t} in module type [A] or {!module-A.t} in module [A], -and also where there are name clashes within the path: {!module-A.module-B.t} or {!module-A.module-type-B.t} *) + (** We can refer unambiguously to {!module-type-A.t} in module type [A] or + {!module-A.t} in module [A], and also where there are name clashes within + the path: {!module-A.module-B.t} or {!module-A.module-type-B.t} *) end module Complicated_1 : sig diff --git a/src/document/comment.ml b/src/document/comment.ml index 9522ec7f6f..ee603bacc1 100644 --- a/src/document/comment.ml +++ b/src/document/comment.ml @@ -117,7 +117,9 @@ module Reference = struct | Some s -> s and tooltip = (* Add a tooltip if the content is not the rendered reference. *) - match text with None -> None | Some _ -> Some rendered + match text with + | None -> None + | Some _ -> Some rendered in match Url.from_identifier ~stop_before:false id with | Ok url -> diff --git a/src/document/doctree.ml b/src/document/doctree.ml index cfdd2cfa4f..cba5dc056d 100644 --- a/src/document/doctree.ml +++ b/src/document/doctree.ml @@ -196,8 +196,8 @@ end module Headings : sig val fold : enter_subpages:bool -> ('a -> Heading.t -> 'a) -> 'a -> Page.t -> 'a - (** Fold over every headings, follow nested documentedsrc and - expansions, as well as subpages if [enter_subpages] is [true]. *) + (** Fold over every headings, follow nested documentedsrc and expansions, as + well as subpages if [enter_subpages] is [true]. *) val foldmap : enter_subpages:bool -> diff --git a/src/document/generator.ml b/src/document/generator.ml index c8850dd266..5b7ca44621 100644 --- a/src/document/generator.ml +++ b/src/document/generator.ml @@ -767,10 +767,10 @@ module Make (Syntax : SYNTAX) = struct intro @ variants @ ending let format_params : - 'row. - ?delim:[ `parens | `brackets ] -> - Odoc_model.Lang.TypeDecl.param list -> - text = + 'row. + ?delim:[ `parens | `brackets ] -> + Odoc_model.Lang.TypeDecl.param list -> + text = fun ?(delim = `parens) params -> let format_param { Odoc_model.Lang.TypeDecl.desc; variance; injectivity } = @@ -808,11 +808,11 @@ module Make (Syntax : SYNTAX) = struct ++ O.box_hv_no_indent (type_expr t2))) let format_manifest : - 'inner_row 'outer_row. - ?is_substitution:bool -> - ?compact_variants:bool -> - Odoc_model.Lang.TypeDecl.Equation.t -> - text * bool = + 'inner_row 'outer_row. + ?is_substitution:bool -> + ?compact_variants:bool -> + Odoc_model.Lang.TypeDecl.Equation.t -> + text * bool = fun ?(is_substitution = false) ?(compact_variants = true) equation -> let _ = compact_variants in (* TODO *) diff --git a/src/document/generator_signatures.ml b/src/document/generator_signatures.ml index a8a67a504d..d8dea2ab3f 100644 --- a/src/document/generator_signatures.ml +++ b/src/document/generator_signatures.ml @@ -5,8 +5,7 @@ type rendered_item = DocumentedSrc.t type text = Codefmt.t -(** HTML generation syntax customization module. See {!ML} and - {!Reason}. *) +(** HTML generation syntax customization module. See {!ML} and {!Reason}. *) module type SYNTAX = sig module Obj : sig val close_tag_closed : string diff --git a/src/document/targets.mli b/src/document/targets.mli index 7c44176187..465048c36a 100644 --- a/src/document/targets.mli +++ b/src/document/targets.mli @@ -1,9 +1,7 @@ -(** Collect all the urls of pages defined by a model. - - Roughly a simplified version of the normal process - to convert a model into a document, only for extracting Urls. - Used to determine the build targets. -*) +(** Collect all the urls of pages defined by a model. + + Roughly a simplified version of the normal process to convert a model into a + document, only for extracting Urls. Used to determine the build targets. *) open Odoc_model.Lang diff --git a/src/document/url.mli b/src/document/url.mli index 3aaef7b0bc..462994ac6e 100644 --- a/src/document/url.mli +++ b/src/document/url.mli @@ -28,8 +28,8 @@ module Path : sig val string_of_kind : kind -> string val pp_disambiguating_prefix : Format.formatter -> kind -> unit - (** Print the ["kind-"] prefix used to disambiguate urls in "flat modes": - e.g. latex labels and output files in [--flat] HTML and man output *) + (** Print the ["kind-"] prefix used to disambiguate urls in "flat modes": e.g. + latex labels and output files in [--flat] HTML and man output *) type t = { kind : kind; parent : t option; name : string } @@ -52,15 +52,14 @@ module Path : sig is_dir:(kind -> [ `Always | `Never | `IfNotLast ]) -> (kind * string) list -> (kind * string) list * (kind * string) list - (** [split is_dir path] splits the list [path] into a directory - and filename, based on the [is_dir] function. The function - [is_dir] should return whether or not the path element [kind] - should be a directory or not. If the function [is_dir] returns - [`IfNotLast] then the element will be a directory only if it - is not the last element in the path. The return value is a tuple - of directory-type elements and filename-type elements. If the - [is_dir] function can return [`Always], the caller must be prepared - to handle the case where the filename part is empty. *) + (** [split is_dir path] splits the list [path] into a directory and filename, + based on the [is_dir] function. The function [is_dir] should return + whether or not the path element [kind] should be a directory or not. If + the function [is_dir] returns [`IfNotLast] then the element will be a + directory only if it is not the last element in the path. The return value + is a tuple of directory-type elements and filename-type elements. If the + [is_dir] function can return [`Always], the caller must be prepared to + handle the case where the filename part is empty. *) end module Anchor : sig @@ -86,8 +85,8 @@ module Anchor : sig anchor : string; (** Anchor in {!field-page} where the element is attached *) kind : kind; - (** What kind of element the path points to. - e.g. "module", "module-type", "exception", ... *) + (** What kind of element the path points to. e.g. "module", + "module-type", "exception", ... *) } val from_identifier : Identifier.t -> (t, Error.t) result diff --git a/src/driver/library_names.mli b/src/driver/library_names.mli index 44048b3c6a..1c9481577f 100644 --- a/src/driver/library_names.mli +++ b/src/driver/library_names.mli @@ -12,12 +12,12 @@ val process_meta_file : Fpath.t -> t file. *) val libname_of_archive : t -> string Fpath.map -(** [libname_of_archive meta_dir libraries] computes a map from the fully-qualified - archive path to the name of the library. [meta_path] is the path of the - directory where the META file is found, and [libraries] are the libraries - defined in that META file. *) +(** [libname_of_archive meta_dir libraries] computes a map from the + fully-qualified archive path to the name of the library. [meta_path] is the + path of the directory where the META file is found, and [libraries] are the + libraries defined in that META file. *) val directories : t -> Fpath.set -(** [directories meta_dir libraries] computes a set of directories - containing the libraries in [libraries] defined in the META file - found in [meta_path]. *) +(** [directories meta_dir libraries] computes a set of directories containing + the libraries in [libraries] defined in the META file found in [meta_path]. +*) diff --git a/src/driver/odoc_driver.ml b/src/driver/odoc_driver.ml index fc82a8a4a5..d8459ac17b 100644 --- a/src/driver/odoc_driver.ml +++ b/src/driver/odoc_driver.ml @@ -483,8 +483,18 @@ let render_stats env nprocs = ++ dline "HTML" (total_impls + non_hidden + total_mlds) ++ line (procs nprocs) ++ descriptions) - (fun comp compimpl compmld compassets link linkimpl linkmld indexes html - procs descr -> + (fun comp + compimpl + compmld + compassets + link + linkimpl + linkmld + indexes + html + procs + descr + -> let rec inner (a, b, c, j, d, e, f, i, g, h) = Eio.Time.sleep clock 0.1; let a' = Atomic.get Stats.stats.compiled_units in diff --git a/src/driver/voodoo.ml b/src/driver/voodoo.ml index 15b5926b29..a8e8bc1816 100644 --- a/src/driver/voodoo.ml +++ b/src/driver/voodoo.ml @@ -91,8 +91,10 @@ let assets_and_mlds_of_pkg pkg_path pkg = else Some (`A - { Packages.asset_path = path; asset_rel_path = rel_path }) - ) + { + Packages.asset_path = path; + asset_rel_path = rel_path; + })) | "doc" :: pkg_name :: "odoc-assets" :: _ :: _ -> ( check_name pkg_name >>= fun () -> match Fpath.rem_prefix asset_prefix p with diff --git a/src/driver/worker_pool.mli b/src/driver/worker_pool.mli index 72faba4674..d5b975684b 100644 --- a/src/driver/worker_pool.mli +++ b/src/driver/worker_pool.mli @@ -2,7 +2,7 @@ val submit : string -> Bos.Cmd.t -> Fpath.t option -> (string list, exn) result (** Submit a command to be executed by a worker. [submit desc cmd output_file] returns the list of output lines. [desc] is a - description of the command. *) + description of the command. *) val start_workers : Eio_unix.Stdenv.base -> Eio.Switch.t -> int -> unit (** Start the given number of new workers. *) diff --git a/src/html/html_fragment_json.ml b/src/html/html_fragment_json.ml index 1deffdecf8..8d244fc849 100644 --- a/src/html/html_fragment_json.ml +++ b/src/html/html_fragment_json.ml @@ -51,16 +51,16 @@ let make ~config ~preamble ~url ~breadcrumbs ~sidebar ~toc ~uses_katex Format.pp_print_string ppf (json_to_string (`Object - [ - ("type", `String "documentation"); - ("uses_katex", `Bool uses_katex); - ("breadcrumbs", json_of_breadcrumbs breadcrumbs); - ("toc", json_of_toc toc); - ("global_toc", global_toc); - ("source_anchor", source_anchor); - ("preamble", `String (json_of_html preamble)); - ("content", `String (json_of_html content)); - ])) + [ + ("type", `String "documentation"); + ("uses_katex", `Bool uses_katex); + ("breadcrumbs", json_of_breadcrumbs breadcrumbs); + ("toc", json_of_toc toc); + ("global_toc", global_toc); + ("source_anchor", source_anchor); + ("preamble", `String (json_of_html preamble)); + ("content", `String (json_of_html content)); + ])) in { Odoc_document.Renderer.filename; content; children } @@ -73,13 +73,13 @@ let make_src ~config ~url ~breadcrumbs content = Format.pp_print_string ppf (json_to_string (`Object - [ - ("type", `String "source"); - ("breadcrumbs", json_of_breadcrumbs breadcrumbs); - ( "content", - `String - (String.concat "" - (List.map (Format.asprintf "%a" htmlpp) content)) ); - ])) + [ + ("type", `String "source"); + ("breadcrumbs", json_of_breadcrumbs breadcrumbs); + ( "content", + `String + (String.concat "" + (List.map (Format.asprintf "%a" htmlpp) content)) ); + ])) in { Odoc_document.Renderer.filename; content; children = [] } diff --git a/src/latex/generator.ml b/src/latex/generator.ml index 515a6cbe32..ec8f427572 100644 --- a/src/latex/generator.ml +++ b/src/latex/generator.ml @@ -130,13 +130,11 @@ let entity ~in_source ~verbatim x = if in_source && not verbatim then Ligaturable (escape_entity x) else Txt [ escape_entity x ] -(** Tables with too many rows are hard to typeset correctly on - the same page. +(** Tables with too many rows are hard to typeset correctly on the same page. Splitting tables on multiple pages is unreliable with longtable + hyperref. - Thus we limit the height of the tables that we render as latex tables. - This variable is kept separated because we may want to make it tunable - by the user. -*) + Thus we limit the height of the tables that we render as latex tables. This + variable is kept separated because we may want to make it tunable by the + user. *) let small_table_height_limit = 10 let rec pp_elt ppf = function diff --git a/src/latex/raw.ml b/src/latex/raw.ml index ac6816d1b3..f1781420e4 100644 --- a/src/latex/raw.ml +++ b/src/latex/raw.ml @@ -1,8 +1,7 @@ (** Raw latex primitives: - macro definitions - env defitions - - text escaping -*) + - text escaping *) type pr = Format.formatter -> unit diff --git a/src/latex/raw.mli b/src/latex/raw.mli index c6c2196d26..0616ae350c 100644 --- a/src/latex/raw.mli +++ b/src/latex/raw.mli @@ -1,10 +1,9 @@ (** Raw latex primitives: - macro and environment definitions - - text escaping -*) + - text escaping *) type pr = Format.formatter -> unit -(** {1 Helper types } *) +(** {1 Helper types} *) type 'a with_options = ?options:pr list -> 'a @@ -12,7 +11,7 @@ type ('a, 'b) tr = 'a Fmt.t -> 'b Fmt.t type 'a t = ('a, 'a) tr -(** {1 Helper functions } *) +(** {1 Helper functions} *) module Escape : sig val text : code_hyphenation:bool -> string -> string @@ -67,10 +66,9 @@ val small_table : ('a, Types.alignment list option * 'a list list) tr val input : Fpath.t Fmt.t -(** {1 Required OCaml-specific primitives } - All the macro should be implemented as "ocaml"-suffixed macro - in the latex preamble - *) +(** {1 Required OCaml-specific primitives} + All the macro should be implemented as "ocaml"-suffixed macro in the latex + preamble *) val inline_code : 'a t (** {2 Code block customization} *) @@ -79,7 +77,7 @@ val code_fragment : 'a t val code_block : 'a t -(** {2 Package-dependent primitives }*) +(** {2 Package-dependent primitives}*) val indent : 'a t (** expected to be implemented with changepage/adjustwidth*) @@ -87,12 +85,11 @@ val indent : 'a t val ocamltabular : column_desc:pr -> 'a t (** Any tabular implementation that works well with at most 10 rows *) -(** {2 Tags } *) +(** {2 Tags} *) val ocamltag : string -> 'a t (** tag (e.g keyword, type-var, ...) are rendered to -{v \ocamltag{tagname}{content} v} -*) + {v \ocamltag{tagname}{content} v} *) (** {2 Math mode} *) diff --git a/src/loader/doc_attr.mli b/src/loader/doc_attr.mli index 792015a8ad..a8fe253a86 100644 --- a/src/loader/doc_attr.mli +++ b/src/loader/doc_attr.mli @@ -38,8 +38,8 @@ val page : Location.t -> string -> Odoc_model.Comment.docs_or_stop -(** The parent identifier is used to define labels in the given string (i.e. - for things like [{1:some_section Some title}]) and the location is used for +(** The parent identifier is used to define labels in the given string (i.e. for + things like [{1:some_section Some title}]) and the location is used for error messages. This function is meant to be used to read arbitrary files containing text in @@ -67,7 +67,8 @@ val extract_top_comment : val extract_top_comment_class : Lang.ClassSignature.item list -> Lang.ClassSignature.item list * (Comment.docs * Comment.docs) -(** Extract the first comment of a class signature. Returns the remaining items. *) +(** Extract the first comment of a class signature. Returns the remaining items. +*) val read_location : Location.t -> Odoc_model.Location_.span diff --git a/src/loader/implementation.mli b/src/loader/implementation.mli index b2cc7c99be..0a71505535 100644 --- a/src/loader/implementation.mli +++ b/src/loader/implementation.mli @@ -9,7 +9,7 @@ val read_cmt_infos : Lang.Compilation_unit.Import.t list -> Lang.Implementation.t (** Extract all implementation information from a [cmt]: the shape, and the - {{!Odoc_model.Lang.Source_info.infos}source infos} (local and global + {{!Odoc_model.Lang.Source_info.infos} source infos} (local and global definitions and occurrences). In OCaml version below 4.14, the information is always empty. *) diff --git a/src/model/fold.mli b/src/model/fold.mli index e5fc4a1473..a44c97d6bd 100644 --- a/src/model/fold.mli +++ b/src/model/fold.mli @@ -19,11 +19,11 @@ type item = | ModuleType of ModuleType.t | Doc of Paths.Identifier.LabelParent.t * Comment.docs_or_stop -(** Below are the folding functions. For items that may contain - others, such as [signature], it folds recursively on the - sub-items. It does not recurse into internal items. +(** Below are the folding functions. For items that may contain others, such as + [signature], it folds recursively on the sub-items. It does not recurse into + internal items. - The LabelParent identifier is used to give an id to the doc entries. *) + The LabelParent identifier is used to give an id to the doc entries. *) val unit : f:('a -> item -> 'a) -> 'a -> Compilation_unit.t -> 'a val page : f:('a -> item -> 'a) -> 'a -> Page.t -> 'a diff --git a/src/model/lang.ml b/src/model/lang.ml index e1184c3b40..0dce6a7603 100644 --- a/src/model/lang.ml +++ b/src/model/lang.ml @@ -26,7 +26,8 @@ module rec Module : sig type t = { id : Identifier.Module.t; source_loc : Identifier.SourceLocation.t option; - (** Identifier.SourceLocation might not be set when the module is artificially constructed from a functor argument. *) + (** Identifier.SourceLocation might not be set when the module is + artificially constructed from a functor argument. *) doc : Comment.docs; type_ : decl; canonical : Path.Module.t option; diff --git a/src/model/names.mli b/src/model/names.mli index 54d2814ec1..1a4ad2c07c 100644 --- a/src/model/names.mli +++ b/src/model/names.mli @@ -1,10 +1,9 @@ (** Typed names for paths, identifiers, references and fragments. This module contains a module per type of named object in our internal - representation of the langage, each containing an opaque type [t]. - This allows us to ensure that, for example, we never mistake a module - name for a module type name. -*) + representation of the langage, each containing an opaque type [t]. This + allows us to ensure that, for example, we never mistake a module name for a + module type name. *) val parenthesise : string -> string val contains_double_underscore : string -> bool @@ -12,13 +11,12 @@ val contains_double_underscore : string -> bool val set_unique_ident : string -> unit -(** Name is the signature for names that could possibly be hidden. Hidden - names occur when we generate items that don't have a path that will be - exposed in the generated HTML. This can occur for a few reasons: - - 1. explicitly hidden by the user with stop comments - 2. generalised opens - 3. shadowed identifiers +(** Name is the signature for names that could possibly be hidden. Hidden names + occur when we generate items that don't have a path that will be exposed in + the generated HTML. This can occur for a few reasons: + + 1. explicitly hidden by the user with stop comments 2. generalised opens 3. + shadowed identifiers In cases 1 and 2 the identifiers are available for use later in the signature (or more generally) whereas for case 3 they aren't, and it's diff --git a/src/model/paths.mli b/src/model/paths.mli index f1abf58777..86fce24957 100644 --- a/src/model/paths.mli +++ b/src/model/paths.mli @@ -58,8 +58,8 @@ module Identifier : sig val functor_arg_pos : t -> int (** Gets the index in which the functor argument is, in the argument list. - Useful to turn identifiers into unique anchors, since multiple arguments - can have the same name. *) + Useful to turn identifiers into unique anchors, since multiple arguments + can have the same name. *) end module ModuleType : @@ -307,10 +307,11 @@ module Identifier : sig val extension_decl : Signature.t * (ExtensionName.t * ExtensionName.t) -> [> `ExtensionDecl of Signature.t * ExtensionName.t * ExtensionName.t ] id - (** [extension_decl (sg, e1, eN)] defines an extension declaration where [sg] is the parent, - [e1] is the first constructor of the extension, and [eN] is the constructor the Id is created for. - [e1] will be used for the url, and [eN] will be the one displayed. - The first constructor of the extension will always be used to reference the extension point. *) + (** [extension_decl (sg, e1, eN)] defines an extension declaration where + [sg] is the parent, [e1] is the first constructor of the extension, and + [eN] is the constructor the Id is created for. [e1] will be used for the + url, and [eN] will be the one displayed. The first constructor of the + extension will always be used to reference the extension point. *) val exception_ : Signature.t * ExceptionName.t -> diff --git a/src/model/paths_types.ml b/src/model/paths_types.ml index 0da86d1554..ddac0f8ab9 100644 --- a/src/model/paths_types.ml +++ b/src/model/paths_types.ml @@ -26,7 +26,7 @@ module Identifier = struct type source_page_pv = [ `SourcePage of container_page * string ] (** The second argument is the filename. - @canonical Odoc_model.Paths.Identifier.SourcePage.t_pv *) + @canonical Odoc_model.Paths.Identifier.SourcePage.t_pv *) type source_page = source_page_pv id (** @canonical Odoc_model.Paths.Identifier.SourcePage.t *) @@ -34,7 +34,7 @@ module Identifier = struct type asset_file_pv = [ `AssetFile of page * AssetName.t ] (** The second argument is the filename. - @canonical Odoc_model.Paths.Identifier.AssetFile.t_pv *) + @canonical Odoc_model.Paths.Identifier.AssetFile.t_pv *) type asset_file = asset_file_pv id (** @canonical Odoc_model.Paths.Identifier.AssetFile.t *) diff --git a/src/model/predefined.ml b/src/model/predefined.ml index 03594099e5..884bd1f52d 100644 --- a/src/model/predefined.ml +++ b/src/model/predefined.ml @@ -128,10 +128,10 @@ let doc_of_core_type = elt `Space; elt (`Reference - ( `Module - ( `Root ("Array", `TModule), - ModuleName.make_std "Floatarray" ), - [] )); + ( `Module + ( `Root ("Array", `TModule), + ModuleName.make_std "Floatarray" ), + [] )); elt `Space; ] @ words diff --git a/src/model/root.mli b/src/model/root.mli index 5c4768e464..8ead2ad3bb 100644 --- a/src/model/root.mli +++ b/src/model/root.mli @@ -16,10 +16,9 @@ (** A root can be seen as a unique representative of a odoc file. - {{!t}Roots} are used by doc-ock (at the root of every resolved + {{!t} Roots} are used by doc-ock (at the root of every resolved path/identifier/reference) and present at the beginning of every [.odoc] - file. -*) + file. *) module Package : sig type t = string diff --git a/src/model/semantics.ml b/src/model/semantics.ml index 5f079b7352..bf65c72f97 100644 --- a/src/model/semantics.ml +++ b/src/model/semantics.ml @@ -10,8 +10,8 @@ type internal_tags_removed = (** {!Ast.block_element} without internal tags. *) type _ handle_internal_tags = - | Expect_status - : [ `Default | `Inline | `Open | `Closed ] handle_internal_tags + | Expect_status : + [ `Default | `Inline | `Open | `Closed ] handle_internal_tags | Expect_canonical : Reference.path option handle_internal_tags | Expect_none : unit handle_internal_tags @@ -325,7 +325,7 @@ let tag : | Result.Ok target -> ok (`Raise - (`Reference (target, []), nestable_block_elements status content)) + (`Reference (target, []), nestable_block_elements status content)) | Result.Error error -> Error.raise_warning error; let placeholder = `Code_span name in @@ -541,7 +541,8 @@ let strip_internal_tags ast : internal_tags_removed with_location list * _ = in loop [] [] ast -(** Append alerts at the end of the comment. Tags are favoured in case of alerts of the same name. *) +(** Append alerts at the end of the comment. Tags are favoured in case of alerts + of the same name. *) let append_alerts_to_comment alerts (comment : Comment.block_element with_location list) = let alerts = diff --git a/src/model/semantics.mli b/src/model/semantics.mli index 0a7eeaf015..253d894033 100644 --- a/src/model/semantics.mli +++ b/src/model/semantics.mli @@ -1,7 +1,7 @@ (** How to handle internal tags. *) type _ handle_internal_tags = - | Expect_status - : [ `Default | `Inline | `Open | `Closed ] handle_internal_tags + | Expect_status : + [ `Default | `Inline | `Open | `Closed ] handle_internal_tags | Expect_canonical : Reference.path option handle_internal_tags | Expect_none : unit handle_internal_tags diff --git a/src/model_desc/comment_desc.ml b/src/model_desc/comment_desc.ml index eaade4d676..47246528dc 100644 --- a/src/model_desc/comment_desc.ml +++ b/src/model_desc/comment_desc.ml @@ -161,7 +161,9 @@ and tag : general_tag t = let url_kind = Variant (function - | `Url -> C0 "`Url" | `File -> C0 "`File" | `Document -> C0 "`Document") + | `Url -> C0 "`Url" + | `File -> C0 "`File" + | `Document -> C0 "`Document") in Variant (function diff --git a/src/model_desc/lang_desc.ml b/src/model_desc/lang_desc.ml index 02f8ef1d86..ca4b342b39 100644 --- a/src/model_desc/lang_desc.ml +++ b/src/model_desc/lang_desc.ml @@ -58,7 +58,8 @@ and functorparameter_t = let open Lang.FunctorParameter in Variant (function - | Unit -> C0 "Unit" | Named x -> C ("Named", x, functorparameter_parameter)) + | Unit -> C0 "Unit" + | Named x -> C ("Named", x, functorparameter_parameter)) (** {3 ModuleType} *) @@ -420,7 +421,8 @@ and value_t = let value_value_t = Variant (function - | Abstract -> C0 "Abstract" | External x -> C ("External", x, List string)) + | Abstract -> C0 "Abstract" + | External x -> C ("External", x, List string)) in Record [ @@ -610,7 +612,8 @@ and typeexpr_label = let open Lang.TypeExpr in Variant (function - | Label x -> C ("Label", x, string) | Optional x -> C ("Optional", x, string)) + | Label x -> C ("Label", x, string) + | Optional x -> C ("Optional", x, string)) and typeexpr_t = let open Lang.TypeExpr in diff --git a/src/model_desc/type_desc.ml b/src/model_desc/type_desc.ml index 0b2d600ed3..a6d963c594 100644 --- a/src/model_desc/type_desc.ml +++ b/src/model_desc/type_desc.ml @@ -1,6 +1,6 @@ -(** Runtime representation of types. It is only useful for inspecting - values, not types, eg. it is possible to write a generic printer but - not to deserialize. *) +(** Runtime representation of types. It is only useful for inspecting values, + not types, eg. it is possible to write a generic printer but not to + deserialize. *) type 'a t = | Record : 'a field list -> 'a t | Variant : ('a -> case) -> 'a t diff --git a/src/ocamlary/ocamlary.mli b/src/ocamlary/ocamlary.mli index f5a8de70bd..824e165e47 100644 --- a/src/ocamlary/ocamlary.mli +++ b/src/ocamlary/ocamlary.mli @@ -17,68 +17,52 @@ (** This is an {i interface} with {b all} of the {e module system} features. This documentation demonstrates: -- comment formatting -- unassociated comments -- documentation sections -- module system documentation including - {ol - {- submodules} - {- module aliases} - {- module types} - {- module type aliases} - {- modules with signatures} - {- modules with aliased signatures} -} - -A numbered list: -+ 3 -+ 2 -+ 1 + {ul + {- comment formatting } + {- unassociated comments } + {- documentation sections } + {- module + system + documentation + including + + submodules + + module aliases + + module types + + module type aliases + + modules with signatures + + modules with aliased signatures + } + } + + A numbered list: + + 3 + + 2 + + 1 David Sheets is the author. - @author David Sheets -*) + @author David Sheets *) -(** - You may find more information about this HTML documentation renderer - at {{:https://github.com/dsheets/ocamlary} github.com/dsheets/ocamlary }. -*) +(** You may find more information about this HTML documentation renderer at + {{:https://github.com/dsheets/ocamlary} github.com/dsheets/ocamlary}. *) -(** - This is some verbatim text: - {v verbatim v} -*) +(** This is some verbatim text: + {v verbatim v} *) -(** - This is some verbatim text: - {v [][df[]]}} v} -*) +(** This is some verbatim text: + {v [][df[]]}} v} *) -(** - Here is some raw LaTeX: - {%latex: $e^{i\pi} = -1$ %} -*) +(** Here is some raw LaTeX: {%latex: $e^{i\pi} = -1$ %} *) -(** - Here is an index table of [Empty] modules: - {!modules: Empty EmptyAlias} -*) +(** Here is an index table of [Empty] modules: + {!modules:Empty EmptyAlias} *) -(** - Odoc doesn't support [{!indexlist}]. -*) +(** Odoc doesn't support [{!indexlist}]. *) -(** - Here is some superscript: x{^2} -*) +(** Here is some superscript: x{^ 2} *) -(** - Here is some subscript: x{_0} -*) +(** Here is some subscript: x{_ 0} *) -(** - Here are some escaped brackets: \{ \[ \@ \] \} -*) +(** Here are some escaped brackets: \{ \[ \@ \] \} *) (** Here is some {e emphasis} [followed by code]. *) @@ -86,13 +70,13 @@ A numbered list: (******************************************************************************) -(** {1 Level 1 } *) +(** {1 Level 1} *) -(** {2 Level 2 } *) +(** {2 Level 2} *) -(** {3 Level 3 } *) +(** {3 Level 3} *) -(** {4 Level 4 } *) +(** {4 Level 4} *) (** {3 Basic module stuff} *) @@ -110,7 +94,7 @@ module type MissingComment = sig type t end -(** {1:s9000 Section 9000 } *) +(** {1:s9000 Section 9000} *) module EmptyAlias = Empty (** A plain module alias of [Empty] *) @@ -122,7 +106,9 @@ module type EmptySig = sig end module type EmptySigAlias = EmptySig (** A plain, empty module signature alias of - {[EmptySig]} + {[ + EmptySig + ]} (preformatted). *) module ModuleWithSignature : EmptySig @@ -130,8 +116,7 @@ module ModuleWithSignature : EmptySig module ModuleWithSignatureAlias : EmptySigAlias (** A plain module with an alias signature - @deprecated I don't like this element any more. -*) + @deprecated I don't like this element any more. *) module One : sig type one @@ -172,12 +157,10 @@ module type SuperSig = sig module type SuperSig = sig end end -(** For a good time, see - {!SuperSig.SubSigA.subSig} or {!SuperSig.SubSigB.subSig} or - {!SuperSig.EmptySig}. Section {!s9000} is also - interesting. - {!section:emptySig} is the section and {!module-type:EmptySig} is the - module signature. *) +(** For a good time, see {!SuperSig.SubSigA.subSig} or + {!SuperSig.SubSigB.subSig} or {!SuperSig.EmptySig}. Section {!s9000} is also + interesting. {!section:emptySig} is the section and {!module-type:EmptySig} + is the module signature. *) (** References are resolved after everything, so [{!Buffer.t}] won't resolve. *) module Buffer : sig @@ -186,9 +169,9 @@ end (** Some text before exception title. - {3 Basic exception stuff} + {3 Basic exception stuff} - After exception title. *) + After exception title. *) exception Kaboom of unit (** Unary exception constructor *) @@ -200,24 +183,21 @@ exception Kapow of (unit * unit) (** Unary exception constructor over binary tuple *) exception EmptySig -(** {!module-type:EmptySig} is a module and - {!exception:EmptySig} is this exception. *) +(** {!module-type:EmptySig} is a module and {!exception:EmptySig} is this + exception. *) exception EmptySigAlias (** {!exception:EmptySigAlias} is this exception. *) -(** {3 Basic type and value stuff with advanced doc comments } *) +(** {3 Basic type and value stuff with advanced doc comments} *) type ('a, 'b) a_function = 'a -> 'b -(** {!type:a_function} is this type and - {!val:a_function} is the value below. *) +(** {!type:a_function} is this type and {!val:a_function} is the value below. *) val a_function : x:int -> int -(** - This is [a_function] with param and return type. - @param x the [x] coordinate - @return the [y] coordinate -*) +(** This is [a_function] with param and return type. + @param x the [x] coordinate + @return the [y] coordinate *) val fun_fun_fun : ((int, int) a_function, (unit, unit) a_function) a_function @@ -239,20 +219,16 @@ val some_doc : string (** @see "some_doc" The document called [some_doc] *) val since_mesozoic : unit -(** - This value was introduced in the Mesozoic era. - @since mesozoic -*) +(** This value was introduced in the Mesozoic era. + @since mesozoic *) val changing : unit -(** - This value has had changes in 1.0.0, 1.1.0, and 1.2.0. - @before 1.0.0 before 1.0.0 - @before 1.1.0 before 1.1.0 - @version 1.2.0 -*) +(** This value has had changes in 1.0.0, 1.1.0, and 1.2.0. + @before 1.0.0 before 1.0.0 + @before 1.1.0 before 1.1.0 + @version 1.2.0 *) -(** {3 Some Operators } *) +(** {3 Some Operators} *) val ( ~- ) : unit @@ -361,9 +337,8 @@ module type B = sig end (** This module type includes two signatures. - {ul - {- it includes {!module-type:A}} - {- it includes {!module-type:B} with some substitution}} *) + - it includes {!module-type:A} + - it includes {!module-type:B} with some substitution *) module type C = sig include A @@ -853,12 +828,11 @@ include IncludeInclude2 With odoc, everything should be resolved (and linked) but only toplevel units will be documented. - {!modules: Dep1.X Ocamlary.IncludeInclude1 Ocamlary} + {!modules:Dep1.X Ocamlary.IncludeInclude1 Ocamlary} {3 Weirder usages involving module types} - {!modules: IncludeInclude1.IncludeInclude2_M Dep4.X} -*) + {!modules:IncludeInclude1.IncludeInclude2_M Dep4.X} *) (** {1 Playing with \@canonical paths} *) @@ -898,8 +872,9 @@ module CanonicalTest : sig end (* val test : 'a CanonicalTest.Base__.List.t -> unit *) -(** Some ref to {!CanonicalTest.Base_Tests.C.t} and {!CanonicalTest.Base_Tests.L.id}. - But also to {!CanonicalTest.Base.List} and {!CanonicalTest.Base.List.t} *) +(** Some ref to {!CanonicalTest.Base_Tests.C.t} and + {!CanonicalTest.Base_Tests.L.id}. But also to {!CanonicalTest.Base.List} and + {!CanonicalTest.Base.List.t} *) (** {1:aliases Aliases again} *) @@ -1025,12 +1000,11 @@ end - [{!Aliases.incl}] : {!Aliases.incl} And just to make sure we do not mess up: - - [{{!section:indexmodules}A}] : {{!section:indexmodules}A} - - [{{!aliases}B}] : {{!aliases}B} + - [{{!section:indexmodules}A}] : {{!section:indexmodules} A} + - [{{!aliases}B}] : {{!aliases} B} - [{{!section:SuperSig.SubSigA.subSig}C}] : - {{!section:SuperSig.SubSigA.subSig}C} - - [{{!Aliases.incl}D}] : {{!Aliases.incl}D} -*) + {{!section:SuperSig.SubSigA.subSig} C} + - [{{!Aliases.incl}D}] : {{!Aliases.incl} D} *) (** {1 New reference syntax} *) diff --git a/src/occurrences/odoc_occurrences.mli b/src/occurrences/odoc_occurrences.mli index 99b55a10d9..2446c05f20 100644 --- a/src/occurrences/odoc_occurrences.mli +++ b/src/occurrences/odoc_occurrences.mli @@ -3,7 +3,8 @@ open Odoc_model.Lang module Table = Table val of_impl : include_hidden:bool -> Implementation.t -> Table.t -> unit -(** Add all occurrences from implementation of a compilation unit into a table *) +(** Add all occurrences from implementation of a compilation unit into a table +*) val aggregate : tbl:Table.t -> data:Table.t -> unit (** Aggregate [data] into [tbl] *) diff --git a/src/odoc/bin/main.ml b/src/odoc/bin/main.ml index 1379a5c0ea..40a22f75d5 100644 --- a/src/odoc/bin/main.ml +++ b/src/odoc/bin/main.ml @@ -65,7 +65,8 @@ module Antichain = struct in Fpath.normalize p - (** Check that a list of directories form an antichain: they are all disjoints *) + (** Check that a list of directories form an antichain: they are all disjoints + *) let check l = let l = List.map @@ -451,14 +452,14 @@ module Indexing = struct | Some file, `JSON when not (Fpath.has_ext "json" (Fpath.v file)) -> Error (`Msg - "When generating a json index, the output must have a .json file \ - extension") + "When generating a json index, the output must have a .json file \ + extension") | Some file, `Marshall when not (Fpath.has_ext "odoc-index" (Fpath.v file)) -> Error (`Msg - "When generating a binary index, the output must have a \ - .odoc-index file extension") + "When generating a binary index, the output must have a \ + .odoc-index file extension") | Some file, _ -> Ok (Fs.File.of_string file) | None, `JSON -> Ok (Fs.File.of_string "index.json") | None, `Marshall -> Ok (Fs.File.of_string "index.odoc-index") @@ -631,15 +632,15 @@ end = struct then Error (`Msg - "The package name specified with --current-package do not match \ - any package passed as a -P") + "The package name specified with --current-package do not match \ + any package passed as a -P") else match detected_package with | Some dpkg when dpkg <> curpkgnane -> Error (`Msg - "The package name specified with --current-package is not \ - consistent with the packages passed as a -P") + "The package name specified with --current-package is not \ + consistent with the packages passed as a -P") | _ -> Ok current_package) | None -> Ok detected_package @@ -1490,8 +1491,8 @@ module Occurrences = struct | [], [] -> Error (`Msg - "At least one of --file-list or a path to a file must be passed \ - to odoc aggregate-occurrences") + "At least one of --file-list or a path to a file must be passed \ + to odoc aggregate-occurrences") | _ -> dst_of_string dst >>= fun dst -> Occurrences.aggregate ~dst ~warnings_options files file_list diff --git a/src/odoc/compile.ml b/src/odoc/compile.ml index 9c2bf5fcb8..ed059ab15a 100644 --- a/src/odoc/compile.ml +++ b/src/odoc/compile.ml @@ -64,7 +64,7 @@ let is_module_name n = String.length n > 0 && Char.Ascii.is_upper n.[0] - [page-foo] child is a container or leaf page. - [srctree-foo] child is a source tree - Parses [...-"foo"] as [...-foo] for backward compatibility. *) + Parses [...-"foo"] as [...-foo] for backward compatibility. *) let parse_parent_child_reference s = let unquote s = let len = String.length s in diff --git a/src/odoc/depends.mli b/src/odoc/depends.mli index 8e97c743c5..0a773d6cce 100644 --- a/src/odoc/depends.mli +++ b/src/odoc/depends.mli @@ -33,5 +33,5 @@ val for_compile_step : Fs.File.t list -> Compile.t list val for_rendering_step : Fs.Directory.t -> (Odoc_model.Root.t list, [> msg ]) result (** Takes the directory where the .odoc files of a given package are stored and - returns the list of roots that need to be in odoc's load path to - render these .odoc files. *) + returns the list of roots that need to be in odoc's load path to render + these .odoc files. *) diff --git a/src/odoc/fs.ml b/src/odoc/fs.ml index 605159fbb7..8161eb0d57 100644 --- a/src/odoc/fs.ml +++ b/src/odoc/fs.ml @@ -79,7 +79,10 @@ module File = struct Result.Ok (Bytes.unsafe_to_string buf) in let input_stream file ic = - let bsize = 65536 (* IO_BUFFER_SIZE *) in + let bsize = + 65536 + (* IO_BUFFER_SIZE *) + in let buf = Buffer.create bsize in let rec loop () = match Buffer.add_channel buf ic bsize with diff --git a/src/odoc/fs.mli b/src/odoc/fs.mli index 30eb535545..113142749c 100644 --- a/src/odoc/fs.mli +++ b/src/odoc/fs.mli @@ -34,7 +34,7 @@ module Directory : sig val append : t -> t -> t val reach_from : dir:t -> string -> t - (** @raises Invalid_argument if [parent/name] exists but is not a directory. *) + (** @raise Invalid_argument if [parent/name] exists but is not a directory. *) val contains : parentdir:t -> file -> bool @@ -50,8 +50,8 @@ module Directory : sig val fold_files_rec : ?ext:string -> ('a -> file -> 'a) -> 'a -> t -> 'a (** [fold_files_rec_result ~ext f acc d] recursively folds [f] over the files - with extension matching [ext] (defaults to [""]) contained in [d] - and its sub directories. *) + with extension matching [ext] (defaults to [""]) contained in [d] and its + sub directories. *) val fold_files_rec_result : ?ext:string -> @@ -60,8 +60,8 @@ module Directory : sig t -> ('a, [> msg ]) result (** [fold_files_rec_result ~ext f acc d] recursively folds [f] over the files - with extension matching [ext] (defaults to [""]) contained in [d] - and its sub directories. Stop as soon as [f] returns [Error _]. *) + with extension matching [ext] (defaults to [""]) contained in [d] and its + sub directories. Stop as soon as [f] returns [Error _]. *) module Table : Hashtbl.S with type key = t end diff --git a/src/odoc/html_fragment.mli b/src/odoc/html_fragment.mli index da368a0f14..78b0d3f465 100644 --- a/src/odoc/html_fragment.mli +++ b/src/odoc/html_fragment.mli @@ -25,11 +25,11 @@ val from_mld : warnings_options:Odoc_model.Error.warnings_options -> Fs.File.t -> (unit, [> msg ]) result -(** [from_mld ~xref_base_uri ~resolver ~output input] parses the content of the [input] - file as a documentation page ({e i.e.} the ocamldoc syntax), generates the - equivalent HTML representation and writes the result into the [output] - file. The produced file is an HTML fragment that can be embedded into other - documents. +(** [from_mld ~xref_base_uri ~resolver ~output input] parses the content of the + [input] file as a documentation page ({e i.e.} the ocamldoc syntax), + generates the equivalent HTML representation and writes the result into the + [output] file. The produced file is an HTML fragment that can be embedded + into other documents. - Cross-reference resolution uses the provided [xref_base_uri] to locate docset - packages. *) + Cross-reference resolution uses the provided [xref_base_uri] to locate + docset packages. *) diff --git a/src/odoc/indexing.ml b/src/odoc/indexing.ml index 6f9a3dc515..2be3d2b4dc 100644 --- a/src/odoc/indexing.ml +++ b/src/odoc/indexing.ml @@ -22,8 +22,8 @@ let handle_file file ~unit ~page ~occ = | _ -> Error (`Msg - "Only pages and unit are allowed as input when generating an \ - index")) + "Only pages and unit are allowed as input when generating an \ + index")) let parse_input_file input = let is_sep = function '\n' | '\r' -> true | _ -> false in diff --git a/src/odoc/odoc_link.ml b/src/odoc/odoc_link.ml index 894cb25a8d..08750f9053 100644 --- a/src/odoc/odoc_link.ml +++ b/src/odoc/odoc_link.ml @@ -64,8 +64,8 @@ let handle_warnings ~input_warnings ~warnings_options ww = Odoc_model.Error.handle_warnings ~warnings_options ww >>= fun res -> Ok (res, input_warnings @ warnings) -(** Read the input file and write to the output file. - Also return the resulting tree. *) +(** Read the input file and write to the output file. Also return the resulting + tree. *) let from_odoc ~resolver ~warnings_options input output = let filename = Fs.File.to_string input in Odoc_file.load input >>= fun unit -> diff --git a/src/odoc/rendering.ml b/src/odoc/rendering.ml index a13deef882..58d8c0f586 100644 --- a/src/odoc/rendering.ml +++ b/src/odoc/rendering.ml @@ -23,13 +23,13 @@ let document_of_odocl ~syntax input = | Impl_content _ -> Error (`Msg - "Wrong kind of unit: Expected a page or module unit, got an \ - implementation. Use the dedicated command for implementation.") + "Wrong kind of unit: Expected a page or module unit, got an \ + implementation. Use the dedicated command for implementation.") | Asset_content _ -> Error (`Msg - "Wrong kind of unit: Expected a page or module unit, got an asset \ - unit. Use the dedicated command for assets.") + "Wrong kind of unit: Expected a page or module unit, got an asset \ + unit. Use the dedicated command for assets.") let document_of_input ~resolver ~warnings_options ~syntax input = let output = Fs.File.(set_ext ".odocl" input) in @@ -39,13 +39,13 @@ let document_of_input ~resolver ~warnings_options ~syntax input = | `Impl _ -> Error (`Msg - "Wrong kind of unit: Expected a page or module unit, got an \ - implementation. Use the dedicated command for implementation.") + "Wrong kind of unit: Expected a page or module unit, got an \ + implementation. Use the dedicated command for implementation.") | `Asset _ -> Error (`Msg - "Wrong kind of unit: Expected a page or module unit, got an asset \ - unit. Use the dedicated command for assets.") + "Wrong kind of unit: Expected a page or module unit, got an asset \ + unit. Use the dedicated command for assets.") let render_document renderer ~sidebar ~output:root_dir ~extra_suffix ~extra doc = diff --git a/src/odoc/resolver.ml b/src/odoc/resolver.ml index 347ad0e18e..c0147ecebc 100644 --- a/src/odoc/resolver.ml +++ b/src/odoc/resolver.ml @@ -164,7 +164,7 @@ end = struct | exception Not_found -> Error NoPackage end -let () = (ignore Named_roots.find_by_name [@warning "-5"]) +let () = ignore Named_roots.find_by_name [@warning "-5"] module Accessible_paths : sig type t @@ -295,8 +295,8 @@ let lookup_unit_with_digest ap target_name digest = | Some (m, _) -> Ok (Odoc_xref2.Env.Found m) | None -> Error `Not_found -(** Lookup a compilation unit matching a name. If there is more than one - result, report on stderr and return the first one. +(** Lookup a compilation unit matching a name. If there is more than one result, + report on stderr and return the first one. TODO: Correctly propagate warnings instead of printing. *) let lookup_unit_by_name ap target_name = @@ -332,8 +332,8 @@ let lookup_unit_by_name ap target_name = Some m | None -> None -(** Lookup an unit. First looks into [imports_map] then searches into the - paths. *) +(** Lookup an unit. First looks into [imports_map] then searches into the paths. +*) let lookup_unit_by_name ~important_digests ~imports_map ap target_name = let of_option f = match f with diff --git a/src/odoc/resolver.mli b/src/odoc/resolver.mli index b63cb16782..2176940666 100644 --- a/src/odoc/resolver.mli +++ b/src/odoc/resolver.mli @@ -38,11 +38,12 @@ val create : open_modules:string list -> roots:roots option -> t -(** Prepare the environment for a given list of - {{!Fs.Directory.t} include directories}, page roots and library roots. +(** Prepare the environment for a given list of {{!Fs.Directory.t} include + directories}, page roots and library roots. - @param important_digests indicate whether digests should be compared when - odoc_xref2 tries to lookup or fetch a unit. It defaults to [true]. *) + @param important_digests + indicate whether digests should be compared when odoc_xref2 tries to + lookup or fetch a unit. It defaults to [true]. *) val lookup_page : t -> string -> Lang.Page.t option diff --git a/src/odoc/source.ml b/src/odoc/source.ml index cd6ba6d35c..fa1d79418c 100644 --- a/src/odoc/source.ml +++ b/src/odoc/source.ml @@ -36,7 +36,7 @@ let compile ~resolver ~output ~warnings_options ~source_id input = | None -> Error (`Msg - "parent-id cannot be empty when compiling implementations.") + "parent-id cannot be empty when compiling implementations.") in parent >>= fun parent -> let source_id = diff --git a/src/odoc/support_files.mli b/src/odoc/support_files.mli index f61a81b558..7d9c42ec3c 100644 --- a/src/odoc/support_files.mli +++ b/src/odoc/support_files.mli @@ -3,8 +3,8 @@ val write : ?without_theme:bool -> Fs.Directory.t -> unit (** [write ?without_theme output_dir] copies the support files to the - [output_dir]. If [without_theme] is [true] the theme will {e not} be - copied, the default value is [false]. *) + [output_dir]. If [without_theme] is [true] the theme will {e not} be copied, + the default value is [false]. *) val print_filenames : ?without_theme:bool -> Fs.Directory.t -> unit (** Prints, to STDOUT, the names of the files that calling [Support_files.write] diff --git a/src/parser/ast.ml b/src/parser/ast.ml index 8662f68e8a..5836101fd7 100644 --- a/src/parser/ast.ml +++ b/src/parser/ast.ml @@ -1,18 +1,19 @@ (** Abstract syntax tree representing ocamldoc comments *) (** This is a syntactic representation of ocamldoc comments. See - {{:https://ocaml.org/releases/4.12/htmlman/ocamldoc.html}The manual} for a detailed - description of the syntax understood. Note that there is no attempt at semantic - analysis, and hence these types are capable of representing values that will - be rejected by further stages, for example, invalid references or headings that - are out of range. *) + {{:https://ocaml.org/releases/4.12/htmlman/ocamldoc.html} The manual} for a + detailed description of the syntax understood. Note that there is no attempt + at semantic analysis, and hence these types are capable of representing + values that will be rejected by further stages, for example, invalid + references or headings that are out of range. *) type 'a with_location = 'a Loc.with_location type style = [ `Bold | `Italic | `Emphasis | `Superscript | `Subscript ] type alignment = [ `Left | `Center | `Right ] type reference_kind = [ `Simple | `With_text ] -(** References in doc comments can be of two kinds: [{!simple}] or [{{!ref}With text}]. *) +(** References in doc comments can be of two kinds: [{!simple}] or + [{{!ref}With text}]. *) type inline_element = [ `Space of string @@ -25,10 +26,10 @@ type inline_element = | `Link of string * inline_element with_location list | `Math_span of string (** @since 2.0.0 *) ] (** Inline elements are equivalent to what would be found in a [span] in HTML. - Mostly these are straightforward. The [`Reference] constructor takes a triple - whose second element is the reference itself, and the third the replacement - text. Similarly the [`Link] constructor has the link itself as first parameter - and the second is the replacement text. *) + Mostly these are straightforward. The [`Reference] constructor takes a + triple whose second element is the reference itself, and the third the + replacement text. Similarly the [`Link] constructor has the link itself as + first parameter and the second is the replacement text. *) type 'a cell = 'a with_location list * [ `Header | `Data ] type 'a row = 'a cell list @@ -63,18 +64,18 @@ and nestable_block_element = | `Math_block of string (** @since 2.0.0 *) | `Media of reference_kind * media_href with_location * string * media (** @since 3.0.0 *) ] -(** Some block elements may be nested within lists or tags, but not all. - The [`List] constructor has a parameter of type [\[`Light | `Heavy\]]. - This corresponds to the syntactic constructor used (see the - {{:https://ocaml.org/releases/4.12/htmlman/ocamldoc.html#sss:ocamldoc-list}manual}). - *) +(** Some block elements may be nested within lists or tags, but not all. The + [`List] constructor has a parameter of type [[`Light | `Heavy]]. This + corresponds to the syntactic constructor used (see the + {{:https://ocaml.org/releases/4.12/htmlman/ocamldoc.html#sss:ocamldoc-list} + manual}). *) and table = nestable_block_element abstract_table * [ `Light | `Heavy ] type internal_tag = [ `Canonical of string with_location | `Inline | `Open | `Closed | `Hidden ] -(** Internal tags are used to exercise fine control over the output of odoc. They - are never rendered in the output *) +(** Internal tags are used to exercise fine control over the output of odoc. + They are never rendered in the output *) type ocamldoc_tag = [ `Author of string @@ -89,7 +90,9 @@ type ocamldoc_tag = | `Since of string | `Before of string * nestable_block_element with_location list | `Version of string ] -(** ocamldoc tags are those that are specified in the {{:https://ocaml.org/releases/4.12/htmlman/ocamldoc.html#ss:ocamldoc-tags}manual}) *) +(** ocamldoc tags are those that are specified in the + {{:https://ocaml.org/releases/4.12/htmlman/ocamldoc.html#ss:ocamldoc-tags} + manual}) *) type tag = [ ocamldoc_tag | internal_tag ] type heading = int * string option * inline_element with_location list diff --git a/src/parser/loc.mli b/src/parser/loc.mli index ad8dedb77a..d9772d2abc 100644 --- a/src/parser/loc.mli +++ b/src/parser/loc.mli @@ -1,7 +1,7 @@ (** Locations in files. *) -(** This module concerns locations in source files, both points indicating a specific - character and spans between two points. *) +(** This module concerns locations in source files, both points indicating a + specific character and spans between two points. *) (** {2 Basic types} *) @@ -12,16 +12,17 @@ type span = { file : string; start : point; end_ : point } (** A range of characters between [start] and [end_] in a particular file *) val span : span list -> span -(** [span spans] takes a list of spans and returns a single {!type-span} starting - at the start of the first span and ending at the end of the final span *) +(** [span spans] takes a list of spans and returns a single {!type-span} + starting at the start of the first span and ending at the end of the final + span *) val nudge_start : int -> span -> span -(** This adjusts only the column number, implicitly assuming that the offset does - not move the location across a newline character. *) +(** This adjusts only the column number, implicitly assuming that the offset + does not move the location across a newline character. *) val nudge_end : int -> span -> span -(** This adjusts only the column number, implicitly assuming that the offset does - not move the location across a newline character. *) +(** This adjusts only the column number, implicitly assuming that the offset + does not move the location across a newline character. *) (** {2 Located values} *) @@ -41,9 +42,9 @@ val map : ('a -> 'b) -> 'a with_location -> 'b with_location (** Map over a located value without changing its location *) val same : _ with_location -> 'b -> 'b with_location -(** [same x y] retuns the value y wrapped in a {!with_location} whose - location is that of [x] *) +(** [same x y] retuns the value y wrapped in a {!with_location} whose location + is that of [x] *) val spans_multiple_lines : _ with_location -> bool -(** [spans_multiple_lines x] checks to see whether [x] is located - on a single line or whether it covers more than one. *) +(** [spans_multiple_lines x] checks to see whether [x] is located on a single + line or whether it covers more than one. *) diff --git a/src/parser/odoc_parser.mli b/src/parser/odoc_parser.mli index 5dbd4a0815..c3d38078cd 100644 --- a/src/parser/odoc_parser.mli +++ b/src/parser/odoc_parser.mli @@ -22,15 +22,14 @@ module Loc = Loc (** Warnings produced during parsing. *) module Warning : sig type t = Warning.t = { location : Loc.span; message : string } - (** Warnings are represented as record containing the human-readable text - of the warning alongside the location of the offending text in the source *) + (** Warnings are represented as record containing the human-readable text of + the warning alongside the location of the offending text in the source *) val pp : Format.formatter -> t -> unit (** Pretty printer for {!t} *) val to_string : t -> string - (** [to_string] will format the location and warning as text to be - printed. *) + (** [to_string] will format the location and warning as text to be printed. *) end val warnings : t -> Warning.t list @@ -41,6 +40,6 @@ val ast : t -> Ast.t val position_of_point : t -> Loc.point -> Lexing.position (** Helper function to turn the internal representation of positions back into - the usual representation in the Lexing module. Note that this relies on - the information passed in {!parse_comment}, and hence requires the result - of that call in addition to the {!Loc.point} being converted. *) + the usual representation in the Lexing module. Note that this relies on the + information passed in {!parse_comment}, and hence requires the result of + that call in addition to the {!Loc.point} being converted. *) diff --git a/src/parser/syntax.ml b/src/parser/syntax.ml index 8d8c490400..c220093cfe 100644 --- a/src/parser/syntax.ml +++ b/src/parser/syntax.ml @@ -325,7 +325,8 @@ and delimited_inline_element_list : requires_leading_whitespace:bool -> input -> Ast.inline_element with_location list * Loc.span = - fun ~parent_markup ~parent_markup_location ~requires_leading_whitespace input -> + fun ~parent_markup ~parent_markup_location ~requires_leading_whitespace + input -> (* [~at_start_of_line] is used to interpret [`Minus] and [`Plus]. These are word tokens if not the first non-whitespace tokens on their line. Then, they are allowed in a non-link element list. *) @@ -584,8 +585,7 @@ type ('block, 'stops_at_which_tokens) context = (* This is a no-op. It is needed to prove to the type system that nestable block elements are acceptable block elements in all contexts. *) -let accepted_in_all_contexts : - type block stops_at_which_tokens. +let accepted_in_all_contexts : type block stops_at_which_tokens. (block, stops_at_which_tokens) context -> Ast.nestable_block_element -> block = @@ -628,8 +628,7 @@ let tag_to_words = function - tables, - lists, and - section headings. *) -let rec block_element_list : - type block stops_at_which_tokens. +let rec block_element_list : type block stops_at_which_tokens. (block, stops_at_which_tokens) context -> parent_markup:[< Token.t | `Comment ] -> input -> @@ -949,12 +948,12 @@ let rec block_element_list : let block = accepted_in_all_contexts context (`Code_block - { - Ast.meta; - delimiter; - content = { value = s; location = v_loc }; - output; - }) + { + Ast.meta; + delimiter; + content = { value = s; location = v_loc }; + output; + }) in let block = Loc.at location block in let acc = block :: acc in diff --git a/src/parser/token.ml b/src/parser/token.ml index 4db3b14eb5..f78fd1510d 100644 --- a/src/parser/token.ml +++ b/src/parser/token.ml @@ -74,7 +74,8 @@ type t = | `Begin_style of style | `Begin_paragraph_style of paragraph_style | (* Other inline element markup. *) - `Simple_reference of string + `Simple_reference of + string | `Begin_reference_with_replacement_text of string | `Simple_link of string | `Begin_link_with_replacement_text of string @@ -88,7 +89,8 @@ type t = | `Verbatim of string | `Modules of string | (* List markup. *) - `Begin_list of [ `Unordered | `Ordered ] + `Begin_list of + [ `Unordered | `Ordered ] | `Begin_list_item of [ `Li | `Dash ] | (* Table markup. *) `Begin_table_light diff --git a/src/search/html.ml b/src/search/html.ml index 2f1db78e03..5fbfc4ba22 100644 --- a/src/search/html.ml +++ b/src/search/html.ml @@ -16,7 +16,9 @@ let url { Entry.id; kind; doc = _ } = Values, types, ... are not sensitive to [stop_before], allowing us to shorten the match. *) - match kind with Doc _ -> false | _ -> true + match kind with + | Doc _ -> false + | _ -> true in match Odoc_document.Url.from_identifier ~stop_before id with | Ok url -> diff --git a/src/search/html.mli b/src/search/html.mli index dd66127908..91f2995079 100644 --- a/src/search/html.mli +++ b/src/search/html.mli @@ -22,17 +22,16 @@ val of_strings : html list val names_of_id : Paths.Identifier.t -> string * string -(** [names_of_id id] is [("X.Y", "foo")] if [id] corresponds to [X.Y.foo]. - The tuple is intended to be given respectively to the [prefix_name] and - [name] arguments of {!Odoc_html_frontend.of_strings}. *) +(** [names_of_id id] is [("X.Y", "foo")] if [id] corresponds to [X.Y.foo]. The + tuple is intended to be given respectively to the [prefix_name] and [name] + arguments of {!Odoc_html_frontend.of_strings}. *) val of_doc : Comment.docs -> html (** [of_doc d] returns the HTML associated of the documentation comment [d], generated correctly for search (no links or anchors). *) val html_string_of_doc : Comment.docs -> string -(** [html_string_of_doc d] is the same as {!of_doc} converted to a - string. *) +(** [html_string_of_doc d] is the same as {!of_doc} converted to a string. *) (** Right-hand sides *) diff --git a/src/search/json_index/json_search.ml b/src/search/json_index/json_search.ml index 0301e4039e..e93a917d40 100644 --- a/src/search/json_index/json_search.ml +++ b/src/search/json_index/json_search.ml @@ -185,8 +185,8 @@ let of_entry ({ Entry.id; doc; kind } as entry) html occurrences = | Result.Ok display -> Result.Ok (`Object - ([ ("id", j_id); ("doc", doc); ("kind", kind); ("display", display) ] - @ occurrences)) + ([ ("id", j_id); ("doc", doc); ("kind", kind); ("display", display) ] + @ occurrences)) | Error _ as e -> e let output_json ppf first entries = diff --git a/src/search/odoc_html_frontend.mli b/src/search/odoc_html_frontend.mli index 7e1c135d20..eff8e87e1f 100644 --- a/src/search/odoc_html_frontend.mli +++ b/src/search/odoc_html_frontend.mli @@ -1,12 +1,11 @@ -(** This library is intended for search engine that do not use the Json output +(** This library is intended for search engine that do not use the Json output but Odoc as a library. Most search engine will use their own representation instead of {!Entry.t}, and may not want to store the whole HTML in their - database. - This library contains functions that are useful for the frontend of such - search engines. - These functions would have their place in Odoc_searc.html, but putting them - there means that you need to link to a lot of dependencies to use them, and - js-of-ocaml is unable to detect when these dependencies are unused. *) + database. This library contains functions that are useful for the frontend + of such search engines. These functions would have their place in + Odoc_searc.html, but putting them there means that you need to link to a lot + of dependencies to use them, and js-of-ocaml is unable to detect when these + dependencies are unused. *) val of_strings : kind:string -> @@ -16,10 +15,10 @@ val of_strings : typedecl_params:string option -> doc:string -> string -(** [of_string] generates the html of an entry using strings associated to - the relevant parts of the entry. If the strings have the correct values, - it will return the same HTML as {!Odoc_search.Html.of_entry}. Correct values - are given by {!Odoc_search.Html}, and for kinds, bellow. *) +(** [of_string] generates the html of an entry using strings associated to the + relevant parts of the entry. If the strings have the correct values, it will + return the same HTML as {!Odoc_search.Html.of_entry}. Correct values are + given by {!Odoc_search.Html}, and for kinds, bellow. *) val kind_doc : string (** Kinds *) diff --git a/src/xref2/component.ml b/src/xref2/component.ml index d3eb1e2bca..3fa60907ed 100644 --- a/src/xref2/component.ml +++ b/src/xref2/component.ml @@ -592,8 +592,7 @@ module Fmt = struct and in [wrap2r] we pick [p2]. If [short_paths] is not set, we print a string representing the constructor, and one or both paths with brackets. *) - let wrap : - type a. + let wrap : type a. config -> string -> (config -> Format.formatter -> a -> unit) -> @@ -604,8 +603,7 @@ module Fmt = struct if c.short_paths then Format.fprintf ppf "%a" (fn c) x else Format.fprintf ppf "%s(%a)" txt (fn c) x - let wrap2 : - type a b. + let wrap2 : type a b. config -> string -> (config -> Format.formatter -> a -> unit) -> @@ -618,8 +616,7 @@ module Fmt = struct if c.short_paths then Format.fprintf ppf "%a" (fn1 c) x else Format.fprintf ppf "%s(%a,%a)" txt (fn1 c) x (fn2 c) y - let wrap2r : - type a b. + let wrap2r : type a b. config -> string -> (config -> Format.formatter -> a -> unit) -> @@ -784,8 +781,7 @@ module Fmt = struct in Format.fprintf ppf "%a%a" inner sg.items removed_fmt sg.removed - and option : - type a. + and option : type a. config -> (config -> Format.formatter -> a -> unit) -> Format.formatter -> @@ -1014,7 +1010,8 @@ module Fmt = struct and type_decl_constructor_arg c ppf = let open TypeDecl.Constructor in function - | Tuple ts -> type_tuple c ppf ts | Record fs -> type_decl_fields c ppf fs + | Tuple ts -> type_tuple c ppf ts + | Record fs -> type_decl_fields c ppf fs and type_decl_field c ppf t = let open TypeDecl.Field in @@ -1737,15 +1734,13 @@ end module LocalIdents = struct open Odoc_model - (** The purpose of this module is to extract identifiers - that could be referenced in Paths - that is, modules, - module types, types, classes and class types. That way - we can assign them an Ident.t ahead of time and be - self-consistent. Because we don't need _all_ of the - identifiers we don't traverse the entire structure. - Additionally, we stop at (class_)signature boundaries - since identifiers within these won't be referenced - except within them, so we only do that on demand. *) + (** The purpose of this module is to extract identifiers that could be + referenced in Paths - that is, modules, module types, types, classes and + class types. That way we can assign them an Ident.t ahead of time and be + self-consistent. Because we don't need _all_ of the identifiers we don't + traverse the entire structure. Additionally, we stop at (class_)signature + boundaries since identifiers within these won't be referenced except + within them, so we only do that on demand. *) type t = { modules : Paths.Identifier.Module.t list; diff --git a/src/xref2/component.mli b/src/xref2/component.mli index 5e009dc2d6..12c6af3593 100644 --- a/src/xref2/component.mli +++ b/src/xref2/component.mli @@ -10,12 +10,12 @@ module ValueMap : Map.S with type key = Ident.value module IdentMap : Map.S with type key = Ident.any -(** Delayed is a bit like Lazy.t but may in the future offer the chance to peek inside - to be able to optimize the calculation *) +(** Delayed is a bit like Lazy.t but may in the future offer the chance to peek + inside to be able to optimize the calculation *) module Delayed : sig val eager : bool ref (** If [eager] is true then no delaying is done. Most useful for testing and - documentation *) + documentation *) type 'a t = { mutable v : 'a option; mutable get : (unit -> 'a) option } @@ -31,29 +31,30 @@ module Opt : sig end (** {2 Components} - - The modules/types here are very similar to those in {!module:Odoc_model.Lang}, - in most cases the only difference being that we have {{!module:Ident}Idents} - (which are local) rather than {{!module:Odoc_model.Paths.Identifier}Identifiers} - (which are global), {{!module:Cpath}Cpaths} instead of {{!module:Odoc_model.Paths.Path}Paths}, - and {{!module:Cfrag}Cfrags} rather than {{!module:Odoc_model.Paths.Fragment}Fragments}. - All of these are to support the use of local idents. - - Note that we still use global {{!module:Odoc_model.Paths.Reference}References} - rather than local ones - this is because at the point these components are being - used all the references are unresolved, and hence do not contain any resolved - global identifiers. When resolving references, we construct paths in parallel, - which also helps avoid the need for local references. - - These idents of items are kept outside of the types themselves in - order to help with laziness. + + The modules/types here are very similar to those in + {!module:Odoc_model.Lang}, in most cases the only difference being that we + have {{!module:Ident} Idents} (which are local) rather than + {{!module:Odoc_model.Paths.Identifier} Identifiers} (which are global), + {{!module:Cpath} Cpaths} instead of {{!module:Odoc_model.Paths.Path} Paths}, + and {{!module:Cfrag} Cfrags} rather than + {{!module:Odoc_model.Paths.Fragment} Fragments}. All of these are to support + the use of local idents. + + Note that we still use global {{!module:Odoc_model.Paths.Reference} + References} rather than local ones - this is because at the point these + components are being used all the references are unresolved, and hence do + not contain any resolved global identifiers. When resolving references, we + construct paths in parallel, which also helps avoid the need for local + references. + + These idents of items are kept outside of the types themselves in order to + help with laziness. There are a few other minor differences: - - - Signatures keep track of removed items. These items are removed during - destructive substitution. -*) + - Signatures keep track of removed items. These items are removed during + destructive substitution. *) module rec Module : sig type decl = diff --git a/src/xref2/env.ml b/src/xref2/env.ml index 87ae379795..9aaa9d9cc2 100644 --- a/src/xref2/env.ml +++ b/src/xref2/env.ml @@ -529,8 +529,7 @@ let lookup_root_module_fallback name t = match lookup_root_module (ModuleName.make_std name) t with | Some (Resolved (_, id, m)) -> Some - (`Module - ((id :> Identifier.Path.Module.t), Component.Delayed.put_val m)) + (`Module ((id :> Identifier.Path.Module.t), Component.Delayed.put_val m)) | Some Forward | None -> None let lookup_page_or_root_module_fallback name t = diff --git a/src/xref2/link.ml b/src/xref2/link.ml index e61f4958ba..772c24f3b2 100644 --- a/src/xref2/link.ml +++ b/src/xref2/link.ml @@ -350,8 +350,7 @@ and comment_block_element env parent ~loc (x : Comment.block_element) = `Heading h | `Tag t -> `Tag (comment_tag env parent ~loc t) -and with_location : - type a. +and with_location : type a. (loc:_ -> a -> a) -> a Location_.with_location -> a Location_.with_location = fun fn { value; location = loc } -> diff --git a/src/xref2/lookup_failures.mli b/src/xref2/lookup_failures.mli index b0fc8a28f9..741acacf21 100644 --- a/src/xref2/lookup_failures.mli +++ b/src/xref2/lookup_failures.mli @@ -1,7 +1,8 @@ (** Report non-fatal errors. The main difference with {!Odoc_model.Error} is that no precise location is - attached to each failures, instead a filename is given to {!catch_failures}. *) + attached to each failures, instead a filename is given to {!catch_failures}. +*) open Odoc_model @@ -21,7 +22,8 @@ val report_warning : ('fmt, Format.formatter, unit, unit) format4 -> 'fmt (** Warnings are user errors. *) val with_location : Location_.span -> (unit -> 'a) -> 'a -(** Failures reported indirectly by this function will have a location attached. *) +(** Failures reported indirectly by this function will have a location attached. +*) val with_context : ('fmt, Format.formatter, unit, (unit -> 'a) -> 'a) format4 -> 'fmt diff --git a/src/xref2/ref_tools.ml b/src/xref2/ref_tools.ml index f41da8c2d5..b377f76f2e 100644 --- a/src/xref2/ref_tools.ml +++ b/src/xref2/ref_tools.ml @@ -223,7 +223,7 @@ module M = struct | Error _ -> Error (`Parent - (`Parent_module (`Lookup_failure_root (ModuleName.make_std name)))) + (`Parent_module (`Lookup_failure_root (ModuleName.make_std name)))) end module Path = struct @@ -457,9 +457,10 @@ module ED = struct let id_parent = match id.iv with `Extension (p, _) -> p in Ok (`Identifier - (Identifier.Mk.extension_decl - ( id_parent, - (ExtensionName.make_std c.name, ExtensionName.make_std name) ))) + (Identifier.Mk.extension_decl + ( id_parent, + (ExtensionName.make_std c.name, ExtensionName.make_std name) + ))) let in_signature _env ((parent', parent_cp, sg) : signature_lookup_result) name = @@ -533,7 +534,7 @@ module CS = struct | `In_type (typ_name, _, `FPoly cs) -> Ok (`PolyConstructor - (`Type (parent', typ_name), ConstructorName.make_std cs.name)) + (`Type (parent', typ_name), ConstructorName.make_std cs.name)) | `In_type (typ_name, _, `FConstructor _) -> Ok (`Constructor (`Type (parent', typ_name), name))) | `T (parent', t) -> ( @@ -542,20 +543,20 @@ module CS = struct | `FPoly cs -> Ok (`PolyConstructor - ( (parent' : Resolved.DataType.t), - ConstructorName.make_std cs.name )) + ( (parent' : Resolved.DataType.t), + ConstructorName.make_std cs.name )) | `FConstructor _ -> Ok (`Constructor ((parent' : Resolved.DataType.t), name))) let of_component _env parent name = Ok (`Constructor - ((parent : Resolved.DataType.t), ConstructorName.make_std name)) + ((parent : Resolved.DataType.t), ConstructorName.make_std name)) let poly_of_component _env parent name = Ok (`PolyConstructor - ((parent : Resolved.DataType.t), ConstructorName.make_std name)) + ((parent : Resolved.DataType.t), ConstructorName.make_std name)) end module F = struct @@ -582,7 +583,7 @@ module F = struct | `In_type (typ_name, _, `FField _) -> Ok (`Field - ((`Type (parent', typ_name) :> Resolved.FieldParent.t), name))) + ((`Type (parent', typ_name) :> Resolved.FieldParent.t), name))) | `T (parent', t) -> ( find Find.any_in_type t (fun x -> x) name_s >>= function | `FConstructor _ -> got_a_constructor name_s @@ -592,8 +593,8 @@ module F = struct let of_component _env parent name = Ok (`Field - ( (parent : Resolved.DataType.t :> Resolved.FieldParent.t), - FieldName.make_std name )) + ( (parent : Resolved.DataType.t :> Resolved.FieldParent.t), + FieldName.make_std name )) end module MM = struct diff --git a/src/xref2/tools.ml b/src/xref2/tools.ml index 9fa365a8fa..c9b65400a6 100644 --- a/src/xref2/tools.ml +++ b/src/xref2/tools.ml @@ -64,13 +64,13 @@ let c_ty_poss env p = unresolved path, returns an ordered list of all possible unresolved paths starting with the shortest and including the longest one. *) let canonical_helper : - 'unresolved 'resolved. - Env.t -> - (Env.t -> 'unresolved -> ('resolved * 'result, _) result) -> - ('resolved -> Odoc_model.Paths.Path.Resolved.t) -> - (Env.t -> 'unresolved -> 'unresolved list) -> - 'unresolved -> - ('resolved * 'result) option = + 'unresolved 'resolved. + Env.t -> + (Env.t -> 'unresolved -> ('resolved * 'result, _) result) -> + ('resolved -> Odoc_model.Paths.Path.Resolved.t) -> + (Env.t -> 'unresolved -> 'unresolved list) -> + 'unresolved -> + ('resolved * 'result) option = fun env resolve lang_of possibilities p2 -> let resolve p = match resolve env p with Ok rp -> Some rp | Error _ -> None @@ -749,11 +749,11 @@ and lookup_type_gpath : by the next clause. They are already resolved. *) Ok (`FType - ( name, - Component.Of_Lang.( - type_decl (empty ()) - (Odoc_model.Predefined.type_of_core_type - (TypeName.to_string name))) )) + ( name, + Component.Of_Lang.( + type_decl (empty ()) + (Odoc_model.Predefined.type_of_core_type + (TypeName.to_string name))) )) | `Identifier ({ iv = `Type _; _ } as i) -> of_option ~error:(`Lookup_failureT i) (Env.(lookup_by_id s_datatype) i env) @@ -1588,8 +1588,8 @@ and handle_signature_with_subs : (fun sg_opt sub -> sg_opt >>= fun sg -> fragmap env sub sg) (Ok sg) subs -and assert_not_functor : - type err. expansion -> (Component.Signature.t, err) Result.result = function +and assert_not_functor : type err. + expansion -> (Component.Signature.t, err) Result.result = function | Signature sg -> Ok sg | _ -> assert false @@ -1652,7 +1652,8 @@ and expansion_of_simple_expansion : | Functor (arg, e) -> Functor (arg, helper e) in function - | Signature sg -> Signature sg | Functor (arg, e) -> Functor (arg, helper e) + | Signature sg -> Signature sg + | Functor (arg, e) -> Functor (arg, helper e) and expansion_of_module_type_expr : Env.t -> @@ -1714,7 +1715,9 @@ and expansion_of_module : let sg = (* Override the signature's documentation when the module also has a comment attached. *) - match m.doc with [] -> sg | doc -> { sg with doc } + match m.doc with + | [] -> sg + | doc -> { sg with doc } in Ok (Signature sg) | Functor _ as f -> Ok f diff --git a/src/xref2/tools.mli b/src/xref2/tools.mli index bc54c338ca..c0793e9b2c 100644 --- a/src/xref2/tools.mli +++ b/src/xref2/tools.mli @@ -1,9 +1,8 @@ (** Tools for manipulating the component data structures - This module contains tools for manipulating the {!module:Component} - data structures, for example, resolving paths and fragments, obtaining - signatures, handling fragment substitution and others. -*) + This module contains tools for manipulating the {!module:Component} data + structures, for example, resolving paths and fragments, obtaining + signatures, handling fragment substitution and others. *) open Errors.Tools_error open Odoc_model.Names @@ -14,32 +13,33 @@ type expansion = (** {2 Lookup and resolve functions} *) -(** The following lookup and resolve functions take {{!module:Cpath.Resolved}resolved paths} - (for lookup) or {{!module:Cpath.Cpath}unresolved paths} (for resolve) - and an {{!type:Env.t}environment} and return the representation of the - component. The resolve functions additionally return the resolved path. - There are some common arguments: - - - {!type:Env.t} is the environment that maps from {{!type:Odoc_model.Paths.Identifier.t}Identifiers} - to {{!module:Component}Components}. - - [mark_substituted] indicates that all paths in the resulting module - that are the result of a substitution, either via a functor - application or via a `with module..` construct, will be marked with a - [`Substituted] constructor +(** The following lookup and resolve functions take {{!module:Cpath.Resolved} + resolved paths} (for lookup) or {{!module:Cpath.Cpath} unresolved paths} + (for resolve) and an {{!type:Env.t} environment} and return the + representation of the component. The resolve functions additionally return + the resolved path. There are some common arguments: + + - {!type:Env.t} is the environment that maps from + {{!type:Odoc_model.Paths.Identifier.t} Identifiers} to + {{!module:Component} Components}. + - [mark_substituted] indicates that all paths in the resulting module that + are the result of a substitution, either via a functor application or via + a `with module..` construct, will be marked with a [`Substituted] + constructor - [add_canonical] asks for [`Canonical] constructors to be added to modules - for which there is a defined canonical path. If the - - If the path is a 'Forward' path, that is, a path to a module that has not yet been - compiled, then it may not be possible to resolve the path if this is being called - during the 'compile' phase, in which case the function will return an unresolved path with no - component. Resolution should be attempted again during the link phase. - - On entry the assumption is that all {{!type:Odoc_model.Paths.Identifier.t}Identifiers} - in the paths are available in [env], except where there are forward paths. If the - environment does not contain all the required modules (for example, if odoc has not - been called on all of the dependent modules), an unresolved path will be returned - with no component. -*) + for which there is a defined canonical path. If the + + If the path is a 'Forward' path, that is, a path to a module that has not + yet been compiled, then it may not be possible to resolve the path if this + is being called during the 'compile' phase, in which case the function will + return an unresolved path with no component. Resolution should be attempted + again during the link phase. + + On entry the assumption is that all {{!type:Odoc_model.Paths.Identifier.t} + Identifiers} in the paths are available in [env], except where there are + forward paths. If the environment does not contain all the required modules + (for example, if odoc has not been called on all of the dependent modules), + an unresolved path will be returned with no component. *) val lookup_module : Env.t -> @@ -47,34 +47,32 @@ val lookup_module : ( Component.Module.t Component.Delayed.t, simple_module_lookup_error ) Result.result -(** [lookup_module ~mark_substituted env p] takes a resolved module cpath [p] and - an environment and returns a representation of the module. -*) +(** [lookup_module ~mark_substituted env p] takes a resolved module cpath [p] + and an environment and returns a representation of the module. *) val lookup_module_type : Env.t -> Cpath.Resolved.module_type -> (Component.ModuleType.t, simple_module_type_lookup_error) Result.result (** [lookup_module_type ~mark_substituted env p] takes a resolved module type - cpath and an environment and returns a representation of the module type. -*) + cpath and an environment and returns a representation of the module type. *) val lookup_type : Env.t -> Cpath.Resolved.type_ -> (Find.careful_type, simple_type_lookup_error) Result.result -(** [lookup_type env p] takes a resolved type path and an environment and returns - a representation of the type. The type can be an ordinary type, a class type - or a class. If the type has been destructively substituted, the path to the - replacement type will be returned instead. *) +(** [lookup_type env p] takes a resolved type path and an environment and + returns a representation of the type. The type can be an ordinary type, a + class type or a class. If the type has been destructively substituted, the + path to the replacement type will be returned instead. *) val lookup_class_type : Env.t -> Cpath.Resolved.class_type -> (Find.careful_class, simple_type_lookup_error) Result.result -(** [lookup_class_type env p] takes a resolved class type path and an environment and returns - a representation of the class type. The type can be a class type - or a class. *) +(** [lookup_class_type env p] takes a resolved class type path and an + environment and returns a representation of the class type. The type can be + a class type or a class. *) val resolve_module : Env.t -> @@ -92,9 +90,10 @@ val resolve_module_type : ( Cpath.Resolved.module_type * Component.ModuleType.t, simple_module_type_lookup_error ) Result.result -(** [resolve_module_type ~mark_substituted ~add_canonical env p] takes an unresolved module - type path and an environment and returns a tuple of the resolved module type - path alongside a representation of the module type itself. *) +(** [resolve_module_type ~mark_substituted ~add_canonical env p] takes an + unresolved module type path and an environment and returns a tuple of the + resolved module type path alongside a representation of the module type + itself. *) val resolve_type : Env.t -> @@ -102,12 +101,11 @@ val resolve_type : ( Cpath.Resolved.type_ * Find.careful_type, simple_type_lookup_error ) Result.result -(** [resolve_type env p] takes an unresolved - type path and an environment and returns a tuple of the resolved type - path alongside a representation of the type itself. As with {!val:lookup_type} - the returned type is either the type, class or class type, or if has been - destructively substituted the return value is the path - to the replaced type, class or class type. *) +(** [resolve_type env p] takes an unresolved type path and an environment and + returns a tuple of the resolved type path alongside a representation of the + type itself. As with {!val:lookup_type} the returned type is either the + type, class or class type, or if has been destructively substituted the + return value is the path to the replaced type, class or class type. *) val resolve_class_type : Env.t -> @@ -115,18 +113,19 @@ val resolve_class_type : ( Cpath.Resolved.class_type * Find.careful_class, simple_type_lookup_error ) Result.result -(** [resolve_class_type env p] takes an unresolved - class type path and an environment and returns a tuple of the resolved class type - path alongside a representation of the class type itself. As with {!val:lookup_type} - the returned type is either the class or class type. *) +(** [resolve_class_type env p] takes an unresolved class type path and an + environment and returns a tuple of the resolved class type path alongside a + representation of the class type itself. As with {!val:lookup_type} the + returned type is either the class or class type. *) -(** {3 Convenience functions } *) +(** {3 Convenience functions} *) -(** The following functions are convenience functions called from {!module:Compile} - or {!module:Link}, and simply call the [resolve_*] functions above and ignore - the component. For the cases of modules and module types, these functions will - additionally prepend an [OpaqueModule] or [OpaqueModuleType] constructor to the - path if the module or module type cannot be expanded *) +(** The following functions are convenience functions called from + {!module:Compile} or {!module:Link}, and simply call the [resolve_*] + functions above and ignore the component. For the cases of modules and + module types, these functions will additionally prepend an [OpaqueModule] or + [OpaqueModuleType] constructor to the path if the module or module type + cannot be expanded *) val resolve_module_path : Env.t -> @@ -155,10 +154,10 @@ val resolve_class_type_path : (** {2 Re-resolve functions} *) -(** The re-resolve functions are called during the link phase to resolve canonical - paths. They take as input only resolved paths. If any path remains unresolved - as link phase, the path should be resolved via a call to {!resolve_module} or - similar, and then passed to {!reresolve_module} *) +(** The re-resolve functions are called during the link phase to resolve + canonical paths. They take as input only resolved paths. If any path remains + unresolved as link phase, the path should be resolved via a call to + {!resolve_module} or similar, and then passed to {!reresolve_module} *) val reresolve_module : Env.t -> Cpath.Resolved.module_ -> Cpath.Resolved.module_ @@ -174,9 +173,9 @@ val reresolve_class_type : (** {2 Ref_tools helpers} *) -(** The following functions are exposed for use in the {!module:Ref_tools} module - only, allowing that module to reuse the machinery in this module for the - resolution of {{!module:Odoc_model.Paths.Reference}References} *) +(** The following functions are exposed for use in the {!module:Ref_tools} + module only, allowing that module to reuse the machinery in this module for + the resolution of {{!module:Odoc_model.Paths.Reference} References} *) val reresolve_parent : Env.t -> Cpath.Resolved.parent -> Cpath.Resolved.parent @@ -233,27 +232,29 @@ val expansion_of_module_type_expr : Env.t -> Component.ModuleType.expr -> (expansion, expansion_of_module_error) Result.result -(** The following functions are use for the resolution of {{!type:Odoc_model.Paths.Fragment.t}Fragments} - Whilst resolving fragments it is necessary to process them in order, applying - the 'with' expression of module or type equality or substitution, before resolving - the next fragment. The function [signature_of_module_type_expr] is used to supply - the signature for the first fragment. For this purpose, [mark_substituted] should - be [true]. As for the path resolution functions above, the resolve functions may - be called during compile or link, whereas the reresolve functions should only be called - during the link phase. *) +(** The following functions are use for the resolution of + {{!type:Odoc_model.Paths.Fragment.t} Fragments} Whilst resolving fragments + it is necessary to process them in order, applying the 'with' expression of + module or type equality or substitution, before resolving the next fragment. + The function [signature_of_module_type_expr] is used to supply the signature + for the first fragment. For this purpose, [mark_substituted] should be + [true]. As for the path resolution functions above, the resolve functions + may be called during compile or link, whereas the reresolve functions should + only be called during the link phase. *) val signature_of_u_module_type_expr : Env.t -> Component.ModuleType.U.expr -> (Component.Signature.t, expansion_of_module_error) Result.result -(** The following functions are use for the resolution of {{!type:Odoc_model.Paths.Fragment.t}Fragments} - Whilst resolving fragments it is necessary to process them in order, applying - the 'with' expression of module or type equality or substitution, before resolving - the next fragment. The function [signature_of_module_type_expr] is used to supply - the signature for the first fragment. For this purpose, [mark_substituted] should - be [true]. As for the path resolution functions above, the resolve functions may - be called during compile or link, whereas the reresolve functions should only be called - during the link phase. *) +(** The following functions are use for the resolution of + {{!type:Odoc_model.Paths.Fragment.t} Fragments} Whilst resolving fragments + it is necessary to process them in order, applying the 'with' expression of + module or type equality or substitution, before resolving the next fragment. + The function [signature_of_module_type_expr] is used to supply the signature + for the first fragment. For this purpose, [mark_substituted] should be + [true]. As for the path resolution functions above, the resolve functions + may be called during compile or link, whereas the reresolve functions should + only be called during the link phase. *) val resolve_module_fragment : Env.t -> @@ -284,45 +285,44 @@ val reresolve_module_type_fragment : (** {2 Fragmap functions} *) -(** The following functions take a signature and apply a transformation to - it corresponding to one item in a [with type|module] module type. The - functions construct a representation that is self-contained, meaning - correct even without having to remember that it is the result of a - fragment modification. For example: +(** The following functions take a signature and apply a transformation to it + corresponding to one item in a [with type|module] module type. The functions + construct a representation that is self-contained, meaning correct even + without having to remember that it is the result of a fragment modification. + For example: {[ - module type S = sig - type t - end - module type T = sig - module M : S - end - module type Z = T with type M.t = int + module type S = sig + type t + end + module type T = sig + module M : S + end + module type Z = T with type M.t = int ]} these functions should return a representation of [Z] as: {[ - module type T = sig - module M : S with type t = int - end + module type T = sig + module M : S with type t = int + end ]} - In particular, it will also handle [include] statements such that if - a type or module introduced by an [include] is the subject of a fragment modification, - the [include] statement will be marked as having a fragment modifier - applied. -*) + In particular, it will also handle [include] statements such that if a type + or module introduced by an [include] is the subject of a fragment + modification, the [include] statement will be marked as having a fragment + modifier applied. *) val fragmap : Env.t -> Component.ModuleType.substitution -> Component.Signature.t -> (Component.Signature.t, expansion_of_module_error) Result.result -(** [fragmap ~mark_substituted env sub sg] takes an environment [env] - and signature [sg], and a fragment substitution (e.g. - [ModuleSubst] to destructively substitute a module), and returns the substituted - signature. *) +(** [fragmap ~mark_substituted env sub sg] takes an environment [env] and + signature [sg], and a fragment substitution (e.g. [ModuleSubst] to + destructively substitute a module), and returns the substituted signature. +*) val handle_signature_with_subs : Env.t -> @@ -334,8 +334,8 @@ val handle_signature_with_subs : (** {2 Cache handling} *) -(** In order to resolve paths quickly, several imperative caches are used. - The following functions are used to manipulate the caches *) +(** In order to resolve paths quickly, several imperative caches are used. The + following functions are used to manipulate the caches *) val reset_caches : unit -> unit (** Empty the caches completely *)