From 1b7e6ffcd3316fe8011d7326d3fa62f784c442ac Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Fri, 6 Dec 2024 13:45:36 +0100 Subject: [PATCH] ocamlformat: Enable formatting of docstrings --- .ocamlformat | 1 - doc/examples/expansion.mli | 13 +- doc/examples/markup.mli | 97 ++++++------ doc/examples/odoc_examples.ml | 4 +- doc/examples/resolution.mli | 13 +- src/document/doctree.ml | 4 +- src/document/generator_signatures.ml | 3 +- src/document/targets.mli | 10 +- src/document/url.mli | 43 +++--- src/driver/library_names.mli | 14 +- src/driver/voodoo.mli | 17 ++- src/driver/worker_pool.mli | 2 +- src/index/page_hierarchy.mli | 2 +- src/latex/generator.ml | 10 +- src/latex/raw.ml | 3 +- src/latex/raw.mli | 21 ++- src/loader/doc_attr.mli | 7 +- src/model/lang.ml | 3 +- src/model/names.mli | 20 ++- src/model/paths.mli | 13 +- src/model/paths_types.ml | 4 +- src/model/root.mli | 3 +- src/model/semantics.ml | 3 +- src/model_desc/type_desc.ml | 6 +- src/ocamlary/ocamlary.mli | 169 +++++++++----------- src/occurrences/odoc_occurrences.mli | 3 +- src/odoc/bin/main.ml | 3 +- src/odoc/compile.ml | 2 +- src/odoc/depends.mli | 4 +- src/odoc/fs.mli | 10 +- src/odoc/html_fragment.mli | 14 +- src/odoc/odoc_link.ml | 4 +- src/odoc/resolver.ml | 8 +- src/odoc/resolver.mli | 5 +- src/odoc/support_files.mli | 4 +- src/parser/ast.ml | 37 ++--- src/parser/loc.mli | 25 +-- src/parser/odoc_parser.mli | 13 +- src/search/html.mli | 9 +- src/search/odoc_html_frontend.mli | 21 ++- src/xref2/component.ml | 16 +- src/xref2/component.mli | 43 +++--- src/xref2/lookup_failures.mli | 6 +- src/xref2/tools.mli | 220 ++++++++++++++------------- 44 files changed, 452 insertions(+), 480 deletions(-) diff --git a/.ocamlformat b/.ocamlformat index 0274bdea45..8fa1b7a31a 100644 --- a/.ocamlformat +++ b/.ocamlformat @@ -1,4 +1,3 @@ module-item-spacing=preserve version=0.27.0 ocaml-version=4.02 -parse-docstrings=false diff --git a/doc/examples/expansion.mli b/doc/examples/expansion.mli index 5a1923fadc..bf78e9754c 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..7184787740 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/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_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 b7361e9cc4..712039e5c1 100644 --- a/src/document/url.mli +++ b/src/document/url.mli @@ -17,8 +17,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 } @@ -41,15 +41,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 @@ -75,8 +74,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 @@ -102,18 +101,18 @@ val from_path : Path.t -> t val from_identifier : stop_before:bool -> Identifier.t -> t (** [from_identifier] turns an identifier to an url. - Some identifiers can be accessed in different ways. For instance, - submodules generate a dedicated page, but they can also be linked to at - their parent page, using a hash to the declaration. + Some identifiers can be accessed in different ways. For instance, submodules + generate a dedicated page, but they can also be linked to at their parent + page, using a hash to the declaration. - The [stop_before] boolean controls that: with [~stop_before:true], the url - will point to the parent page when applicable. + The [stop_before] boolean controls that: with [~stop_before:true], the url + will point to the parent page when applicable. - There is a pitfall with [from_identifier]: Using [~stop_before:false] with - a module that does not contain an expansion, such as a module alias. This - will return a [url] leading to a 404 page. + There is a pitfall with [from_identifier]: Using [~stop_before:false] with a + module that does not contain an expansion, such as a module alias. This will + return a [url] leading to a 404 page. - It would be nice to enforce no 404 by the type system. *) + It would be nice to enforce no 404 by the type system. *) val from_asset_identifier : Identifier.AssetFile.t -> t 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/voodoo.mli b/src/driver/voodoo.mli index 19f362cfe9..d527337811 100644 --- a/src/driver/voodoo.mli +++ b/src/driver/voodoo.mli @@ -9,15 +9,16 @@ type extra_paths = { } val empty_extra_paths : extra_paths -(** When [odoc_driver] is not running in voodoo mode, this value can be passed to - {!Odoc_units_of.packages} *) +(** When [odoc_driver] is not running in voodoo mode, this value can be passed + to {!Odoc_units_of.packages} *) val extra_paths : Fpath.t -> extra_paths -(** [extra_paths odoc_dir] returns the paths to packages and libraries that have previously - been compiled by odoc_driver running in voodoo mode. In order to find these, - the previous invocation of odoc_driver will need to have written marker files by - calling {!write_lib_markers} *) +(** [extra_paths odoc_dir] returns the paths to packages and libraries that have + previously been compiled by odoc_driver running in voodoo mode. In order to + find these, the previous invocation of odoc_driver will need to have written + marker files by calling {!write_lib_markers} *) val write_lib_markers : Fpath.t -> Packages.t Util.StringMap.t -> unit -(** [write_lib_markers odoc_dir pkgs] writes marker files to show the locations of the - compilation units associated with packages and libraries in [pkgs]. *) +(** [write_lib_markers odoc_dir pkgs] writes marker files to show the locations + of the compilation units associated with packages and libraries in [pkgs]. +*) diff --git a/src/driver/worker_pool.mli b/src/driver/worker_pool.mli index 08dec9b3b8..efdf066168 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 -> (Run.t, 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/index/page_hierarchy.mli b/src/index/page_hierarchy.mli index d24f8287bc..1e56060858 100644 --- a/src/index/page_hierarchy.mli +++ b/src/index/page_hierarchy.mli @@ -15,4 +15,4 @@ type t = index Tree.t val of_list : (Identifier.LeafPage.t * title * Frontmatter.children_order option) list -> t (** Uses the convention that the [index] children passes its payload to the - container directory to output a payload *) + container directory to output a payload *) diff --git a/src/latex/generator.ml b/src/latex/generator.ml index 58cd5c57d9..37c1b049ef 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 d4a9117689..0dcaeea6a0 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 * Frontmatter.t -(** 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/model/lang.ml b/src/model/lang.ml index 8dc917a407..d3ca5504ab 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 e19dcae21f..611ccecf02 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 ac0d0cfc18..7d8fee3541 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/root.mli b/src/model/root.mli index 5c4768e464..f35c4538b5 100644 --- a/src/model/root.mli +++ b/src/model/root.mli @@ -18,8 +18,7 @@ {{!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 15d89a673e..a4d74aad9b 100644 --- a/src/model/semantics.ml +++ b/src/model/semantics.ml @@ -513,7 +513,8 @@ let strip_internal_tags ast : internal_tags_removed with_location list * _ = in loop ~start:true [] [] 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_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..9f515e6fc8 100644 --- a/src/ocamlary/ocamlary.mli +++ b/src/ocamlary/ocamlary.mli @@ -17,68 +17,49 @@ (** 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 +67,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 +91,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 +103,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 +113,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 +154,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 +166,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 +180,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 +216,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 +334,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 +825,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 +869,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} *) @@ -1028,9 +1000,8 @@ end - [{{!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 a5ba9fa4bb..d3ed7d02e6 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 ~opt l = let l = List.map diff --git a/src/odoc/compile.ml b/src/odoc/compile.ml index ee61392078..1e29af4318 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.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/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/resolver.ml b/src/odoc/resolver.ml index 5895c3b2f6..78f312f036 100644 --- a/src/odoc/resolver.ml +++ b/src/odoc/resolver.ml @@ -306,8 +306,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 = @@ -343,8 +343,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 7e48a7e7c8..5e93b32868 100644 --- a/src/odoc/resolver.mli +++ b/src/odoc/resolver.mli @@ -43,8 +43,9 @@ val create : (** 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/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 29f7eba660..0639d385c7 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,11 +64,11 @@ 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 +(** 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 ] @@ -80,8 +81,8 @@ type internal_tag = | `Children_order of nestable_block_element with_location list | `Short_title of nestable_block_element with_location list ] -(** 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 @@ -96,7 +97,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/search/html.mli b/src/search/html.mli index 32862220b6..d4767edafe 100644 --- a/src/search/html.mli +++ b/src/search/html.mli @@ -23,17 +23,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/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 58b8ae1f2e..124a806425 100644 --- a/src/xref2/component.ml +++ b/src/xref2/component.ml @@ -1733,15 +1733,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..58f51978db 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, + + 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. + 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/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/tools.mli b/src/xref2/tools.mli index bc54c338ca..b5d17fe7bb 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,35 @@ 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 +49,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 +92,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 +103,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 +115,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 +156,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 +175,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 +234,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 +287,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 +336,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 *)