jon.recoil.org
Odoc docs
1(** Resolve an odoc reference against every package installed in the switch, and
2 locate the item it names — the substrate shared by {!Show} and {!Complete}.
3
4 This is the reference-resolution half of [odoc link], run standalone over
5 the whole switch (with [Stdlib] open and the package roots in scope), with
6 no "current unit" — so relative ([./…]) and current-package ([//…]) path
7 references don't apply, but absolute ([/pkg/…]) ones do. *)
8
9module Id = Odoc_model.Paths.Identifier
10module Lang = Odoc_model.Lang
11module Url = Odoc_document.Url
12
13type scan = {
14 odoc : Fpath.t; (** the switch's [odoc/] root *)
15 directories : Fpath.t list; (** every dir holding a [.odoc] (the [-I] set) *)
16 odocl : (string, Fpath.t) Hashtbl.t; (** capitalised unit name -> [.odocl] *)
17 page_roots : (string * Fpath.t) list;
18 (** package name -> [odoc/<pkg>] ([-P]) *)
19 lib_roots : (string * Fpath.t) list;
20 (** library name -> [odoc/<pkg>/<lib>] ([-L]) *)
21}
22
23val scan : Switch.t -> scan
24(** Scan the switch's [odoc/] tree: the include directories, the package/library
25 roots, and the linked-unit index. *)
26
27val default_open : string list
28(** Modules resolution treats as open (currently [Stdlib]), mirroring the
29 compiler's default environment. *)
30
31val resolve_to_id : scan -> string -> (Id.t, [> `Msg of string ]) result
32(** Parse and resolve a (complete) reference to its canonical identifier, using
33 the same machinery as [odoc link]. Resolver ambiguity chatter on stderr is
34 suppressed; genuine failures are returned as [`Msg]. *)
35
36type located =
37 | Lmodule of Odoc_model.Comment.docs * Lang.Signature.t option
38 (** module / module type / unit: doc comment, and the expansion's
39 signature when present *)
40 | Lclass of Odoc_model.Comment.docs * Lang.ClassSignature.t option
41 | Ltype of Odoc_model.Comment.docs * Lang.TypeDecl.t
42 | Lleaf of Odoc_model.Comment.docs
43 (** value, exception, constructor, field, method, … — no children *)
44
45val find : Id.t -> Lang.Compilation_unit.t -> located option
46(** Locate the item named by [id] within a loaded compilation unit, descending
47 through module/class expansions and includes. *)
48
49val root_candidates : scan -> Id.t -> Fpath.t list
50(** The linked [.odocl] files whose name matches the root of [id]. More than one
51 means the reference is ambiguous across packages/libraries (the resolver
52 would otherwise silently pick the first). *)
53
54val owning_content :
55 scan ->
56 ref_str:string ->
57 Id.t ->
58 (Odoc_odoc.Odoc_file.content, [> `Msg of string ]) result
59(** Load the linked [.odocl] file that defines [id], disambiguating same-named
60 files by matching the identifier key. [ref_str] is used only for error
61 messages. *)