Fix a few error reports

CHANGES.md

@@ -4,9 +4,12 @@ Unreleased
 Bugs fixed
 - Man page renderer fails to output pages that have children (@jonludlam, @Julow, #766)
 - Fix resolution of unprefixed references to pages (@Julow, #755)
+- Fix reporting of ambiguous labels (@Julow, @jonludlam, #773, #781)
+- Allow referencing of labels in the top comment (@jonludlam, #771)
 
 Additions
 - Strip unquoted spaces in identifiers for a more flexible reference syntax (@lubega-simon, @panglesd, #783)
+- Add context to messages raised in expansions of includes (@Julow, #780)
 
 2.0.0
 -----

doc/driver.mld

@@ -14,6 +14,8 @@ First we need to initialise MDX with some libraries and helpful values.
 (* Prelude *)
 #require "bos";;
 #install_printer Fpath.pp;;
+#print_length 100;;
+#print_depth 10;;
 open Bos;;
 let (>>=) = Result.bind;;
 let (>>|=) m f = m >>= fun x -> Ok (f x);;
@@ -28,7 +30,6 @@ let get_ok = function | Ok x -> x | Error (`Msg m) -> failwith m
 }{- [odoc/odoc_model/index.html] : [odoc] model library subpage
 }{- [odoc/odoc_model/Odoc_model/index.html] : Module page for the module [Odoc_model]
 }{- [odoc/odoc_model/Odoc_model/...] : Further pages for the submodules of [Odoc_model]
-}{- [odoc/odoc_parser/index.html] : [odoc] parser library subpage
 }{- [odoc/odoc_.../index.html] : other [odoc] library pages
 }{- [odoc/deps/stdlib/index.html] : stdlib main page
 }{- [odoc/deps/stdlib/Stdlib/index.html] : Module page for the module [Stdlib]
@@ -41,7 +42,7 @@ The [odoc] model for achieving this is that we have {e pages} ([.mld] files) tha
 In the example below, there will be a file [odoc.mld] that corresponds with the top-level directory [odoc/]. It will be compiled as follows:
 
 {[
-odoc compile odoc.mld --child page-odoc_model --child page-odoc_parser --child deps ...
+odoc compile odoc.mld --child page-odoc_model --child deps ...
 ]}
 
 The file [deps.mld] which corresponds with the sub-directory [odoc/deps/], will be compiled as follows:
@@ -157,7 +158,8 @@ let compile file ?parent ?(ignore_output = false) children =
 let link ?(ignore_output = false) file =
   let open Cmd in
   let cmd = odoc % "link" % p file % "-I" % "." in
-  let lines = OS.Cmd.(run_out ~err:err_run_out cmd |> to_lines) |> get_ok in
+  let cmd = if Fpath.to_string file = "stdlib.odoc" then cmd % "--open=\"\"" else cmd in
+  Format.printf "%a" pp cmd;let lines = OS.Cmd.(run_out ~err:err_run_out cmd |> to_lines) |> get_ok in
   if not ignore_output then
     add_prefixed_output cmd link_output (Fpath.to_string file) lines
 
@@ -348,16 +350,16 @@ let odoc_units =
 ]}
 
 {[
-let lib_units =
-  List.map
-    (fun (lib, p) ->
-      Fpath.Set.fold
-        (fun p acc -> ("deps", lib, p) :: acc)
-        (find_units p |> get_ok)
-        [])
-    lib_paths
-
-let all_units = odoc_units @ lib_units |> List.flatten
+let all_units =
+  let lib_units =
+    List.map
+      (fun (lib, p) ->
+        Fpath.Set.fold
+          (fun p acc -> ("deps", lib, p) :: acc)
+          (find_units p |> get_ok)
+          [])
+      lib_paths in
+  odoc_units @ lib_units |> List.flatten
 ]}
 
 Now we'll compile all of the parent [.mld] files. To ensure that the parents are compiled before the children, we start with [odoc.mld], then [deps.mld], and so on. The result of this file is a list of the resulting [odoc] files.
@@ -464,6 +466,7 @@ generate_all linked
 Let's see if there was any output from the [odoc] invocations:
 
 {[
+# #print_length 655360;;
 # !compile_output;;
 - : string list = [""]
 # !link_output;;

doc/dune

@@ -1,6 +1,6 @@
 (documentation
  (package odoc)
- (mld_files contributing deps driver dune features index interface
+ (mld_files contributing driver dune features index interface
    ocamldoc_differences odoc_for_authors parent_child_spec))
 
 (rule
@@ -9,6 +9,7 @@
   (:x driver.md)
   (glob_files *.ml*)
   (glob_files *.png)
+  (glob_files library_mlds/*.mld)
   (package odoc))
  (enabled_if
   (> %{ocaml_version} 4.11))

doc/features.mld

@@ -62,7 +62,7 @@ and the full expansion can be found by clicking on the name of the module
 These expansions have to be done carefully. A number of cases follow
 in which [odoc] has to treat specially.
 
-{2 Aliases}
+{2:expansion_aliases Aliases}
 
 In general [odoc] doesn’t expand module aliases unless they are an
 alias to a hidden module. If this is the case, the right-hand side of
@@ -468,7 +468,7 @@ links need to consider some of the expansions’ features,
 as outlined above. In order to decide where the links should point to and how to
 turn them into text, a process called 'Resolution' is required.
 
-{2 Aliases}
+{2:resolution_aliases Aliases}
 
 Since aliases are not usually expanded, a path or reference to an item contained in
 an aliased module must link directly to the item inside the aliased module. For

doc/library_mlds/dune

@@ -0,0 +1,5 @@
+(documentation
+ (package odoc)
+ (mld_files odoc_document odoc_examples odoc_html odoc_latex odoc_loader
+   odoc_manpage odoc_model odoc_model_desc odoc_odoc odoc_xref2
+   odoc_xref_test))

doc/library_mlds/odoc-parser.mld

@@ -1,3 +1,3 @@
-{0 Odoc_parser}
+{0 Odoc-parser}
 
 The parser library used by Odoc. See {!module-Odoc_parser}.

doc/odoc_for_authors.mld

@@ -36,7 +36,7 @@ v}
 
 Odoc is built to produce documentation for your {e libraries}, and the unit of
 organisation is the {e module}. Documentation is written by putting
-{{!comments}special comments} into the source of the {e module interface} or
+{{!special_comments}special comments} into the source of the {e module interface} or
 less commonly your {e module implementation}. 
 
 For the HTML output, [odoc] will produce one page for each module, module type,
@@ -67,15 +67,15 @@ it is intended that all features of the OCaml language are supported by [odoc].
 For examples of how the language features are handled, see the
 {{!page-features}Features} page.
 
-{2:comment-placement Comment placement}
+{2:special_comments Special Comments}
 
 Comments containing documentation are known as {e special comments}. 
 They are like normal comments except they have precisely
 two asterisks at the start:
 
 {[
 (* Normal comment *)
-(** Documentation comment *)
+(** Special comment containing documentation *)
 (*** Normal comment *)
 ]}
 
@@ -425,7 +425,7 @@ end
 type u
 ]}
 
-The above example can be seen rendered in the module {!Odoc_examples.Scope}.
+The above example can be seen rendered in the module {!Odoc_examples.Markup.Scope}.
 
 [odoc] allows modules to be 'opened' for the purposes of resolving references.
 By default, the module [Stdlib] is 'opened', allowing references like [{!List.t}]
@@ -543,7 +543,7 @@ The OCaml manual provides an instructive example:
 The output of this as rendered by [odoc] is {{!Odoc_examples.Markup.Stop}here}.
 
 
-{1 Page Structure}
+{1:page_structure Page Structure}
 
 Producing good documentation for your library is more than simply annotating
 the various modules, type and functions that are contained however. 
@@ -645,7 +645,7 @@ Note: A comment attached to a declaration shouldn't contain any heading.
 The synopsis of a module (a module type, a class, etc..) is the first
 paragraph of the {!preamble}, {e if} the preamble starts with a paragraph.
 
-It is rendered in [{!modules:...}] lists and after {{!page-features.aliases}expanded aliases}.
+It is rendered in [{!modules:...}] lists and after {{!page-features.expansion_aliases}expanded aliases}.
 
 Note that the synopsis is computed on top of the {e preamble}, in these two
 examples, the synopsis is the same:

src/ocamlary/ocamlary.mli

@@ -886,17 +886,17 @@ module CanonicalTest : sig
     val foo : int L.t -> float L.t
 
     val bar : 'a List.t -> 'a List.t
-    (** This is just {!List.id}, or rather {!L.id} *)
+    (* This is just {!List.id}, or rather {!L.id} *)
 
     val baz : 'a Base__.List.t -> unit
-    (** We can't reference [Base__] because it's hidden.
+    (* We can't reference [Base__] because it's hidden.
         {!List.t} ([List.t]) should resolve. *)
   end
 
   module List_modif : module type of Base.List with type 'c t = 'c Base__.List.t
 end
 
-val test : 'a CanonicalTest.Base__.List.t -> unit
+(* 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} *)
 

src/xref2/env.ml

@@ -218,7 +218,14 @@ let add_to_elts kind identifier component env =
     assert (
       List.mem kind
         [ Kind_Module; Kind_ModuleType; Kind_Type; Kind_Class; Kind_ClassType ]);
-  assert (ElementsById.find_by_id identifier env.ids = None);
+  let _ =
+    let other = ElementsById.find_by_id identifier env.ids in
+    match other with
+    | Some _ ->
+        (* Format.eprintf "Overriding duplicate env entry\n%!" *)
+        ()
+    | None -> ()
+  in
   let name = Identifier.name identifier in
   {
     env with

src/xref2/errors.ml

@@ -215,6 +215,8 @@ let is_unexpanded_module_type_of =
   in
   inner
 
+type kind = [ `OpaqueModule | `Root of string ]
+
 let rec kind_of_module_cpath = function
   | `Root name -> Some (`Root name)
   | `Substituted p' | `Dot (p', _) -> kind_of_module_cpath p'
@@ -231,11 +233,18 @@ let rec kind_of_module_type_cpath = function
 
 (** [Some (`Root _)] for errors during lookup of root modules or [None] for
     other errors. *)
-let rec kind_of_error = function
-  | `UnresolvedPath (`Module (cp, _)) -> kind_of_module_cpath cp
-  | `UnresolvedPath (`ModuleType (cp, _)) -> kind_of_module_type_cpath cp
+let rec kind_of_error : Tools_error.any -> kind option = function
+  | `UnresolvedPath (`Module (cp, e)) -> (
+      match kind_of_module_cpath cp with
+      | None -> kind_of_error (e :> Tools_error.any)
+      | x -> x)
+  | `UnresolvedPath (`ModuleType (cp, e)) -> (
+      match kind_of_module_type_cpath cp with
+      | None -> kind_of_error (e :> Tools_error.any)
+      | x -> x)
   | `Lookup_failure (`Root (_, name)) ->
       Some (`Root (Names.ModuleName.to_string name))
+  | `UnexpandedTypeOf type_of_desc -> kind_of_type_of_desc type_of_desc
   | `Lookup_failure_root name -> Some (`Root name)
   | `Parent (`Parent_sig e) -> kind_of_error (e :> Tools_error.any)
   | `Parent (`Parent_module_type e) -> kind_of_error (e :> Tools_error.any)
@@ -247,6 +256,11 @@ let rec kind_of_error = function
       Some `OpaqueModule
   | _ -> None
 
+and kind_of_type_of_desc : Component.ModuleType.type_of_desc -> kind option =
+  function
+  | ModPath cp -> kind_of_module_cpath cp
+  | StructInclude cp -> kind_of_module_cpath cp
+
 let kind_of_error ~what = function
   | Some e -> kind_of_error (e :> Tools_error.any)
   | None -> (

test/generators/cases/labels.mli

@@ -18,28 +18,28 @@ module type S = sig end
 (** {1:L6 Attached to module type} *)
 
 class c : object end
-(** {1:L6 Attached to class} *)
+(** {1:L7 Attached to class} *)
 
 class type cs = object end
-(** {1:L7 Attached to class type} *)
+(** {1:L8 Attached to class type} *)
 
 exception E
-(** {1:L8 Attached to exception} *)
+(** {1:L9 Attached to exception} *)
 
 type x = ..
 
-(** {1:L9 Attached to extension} *)
+(** {1:L10 Attached to extension} *)
 type x += X
 
 module S := A
-(** {1:L10 Attached to module subst} *)
+(** {1:L11 Attached to module subst} *)
 
 type s := t
-(** {1:L11 Attached to type subst} *)
+(** {1:L12 Attached to type subst} *)
 
-type u = A'  (** {1:L12 Attached to constructor} *)
+type u = A'  (** {1:L13 Attached to constructor} *)
 
-type v = { f : t  (** {1:L13 Attached to field} *) }
+type v = { f : t  (** {1:L14 Attached to field} *) }
 
 (** Testing that labels can be referenced
     - {!L1}
@@ -55,4 +55,5 @@ type v = { f : t  (** {1:L13 Attached to field} *) }
     - {!L11}
     - {!L12}
     - {!L13}
+    - {!L14}
   *)

test/generators/html/Labels-class-c.html

@@ -13,10 +13,10 @@
   <header class="odoc-preamble">
    <h1>Class <code><span>Labels.c</span></code></h1>
   </header>
-  <nav class="odoc-toc"><ul><li><a href="#L6">Attached to class</a></li></ul>
+  <nav class="odoc-toc"><ul><li><a href="#L7">Attached to class</a></li></ul>
   </nav>
   <div class="odoc-content">
-   <h2 id="L6"><a href="#L6" class="anchor"></a>Attached to class</h2>
+   <h2 id="L7"><a href="#L7" class="anchor"></a>Attached to class</h2>
   </div>
  </body>
 </html>

test/generators/html/Labels-class-type-cs.html

@@ -14,10 +14,10 @@
    <h1>Class type <code><span>Labels.cs</span></code></h1>
   </header>
   <nav class="odoc-toc">
-   <ul><li><a href="#L7">Attached to class type</a></li></ul>
+   <ul><li><a href="#L8">Attached to class type</a></li></ul>
   </nav>
   <div class="odoc-content">
-   <h2 id="L7"><a href="#L7" class="anchor"></a>Attached to class type</h2>
+   <h2 id="L8"><a href="#L8" class="anchor"></a>Attached to class type</h2>
   </div>
  </body>
 </html>

test/generators/html/Labels.html

@@ -185,14 +185,15 @@ <h2 id="L2"><a href="#L2" class="anchor"></a>Attached to nothing</h2>
     <li><a href="#L3">Attached to module</a></li>
     <li><a href="#L4">Attached to type</a></li>
     <li><a href="#L5">Attached to value</a></li>
-    <li><a href="#L6">Attached to class</a></li>
-    <li><a href="#L7">Attached to class type</a></li>
-    <li><a href="#L8">Attached to exception</a></li>
-    <li><a href="#L9">Attached to extension</a></li>
-    <li><a href="#L10">Attached to module subst</a></li>
-    <li><a href="#L11">Attached to type subst</a></li>
-    <li><a href="#L12">Attached to constructor</a></li>
-    <li><a href="#L13">Attached to field</a></li>
+    <li><a href="#L6">Attached to module type</a></li>
+    <li><a href="#L7">Attached to class</a></li>
+    <li><a href="#L8">Attached to class type</a></li>
+    <li><a href="#L9">Attached to exception</a></li>
+    <li><a href="#L10">Attached to extension</a></li>
+    <li><a href="#L11">Attached to module subst</a></li>
+    <li><a href="#L12">Attached to type subst</a></li>
+    <li><a href="#L13">Attached to constructor</a></li>
+    <li><a href="#L14">Attached to field</a></li>
    </ul>
   </div>
  </body>

test/generators/html/Ocamlary-CanonicalTest-Base_Tests.html

@@ -73,13 +73,6 @@ <h1>Module <code><span>CanonicalTest.Base_Tests</span></code></h1>
       </span>
      </code>
     </div>
-    <div class="spec-doc">
-     <p>This is just <code>List</code>.id, or rather 
-      <a href="Ocamlary-CanonicalTest-Base-List.html#val-id">
-       <code>L.id</code>
-      </a>
-     </p>
-    </div>
    </div>
    <div class="odoc-spec">
     <div class="spec value" id="val-baz" class="anchored">
@@ -95,11 +88,6 @@ <h1>Module <code><span>CanonicalTest.Base_Tests</span></code></h1>
       </span>
      </code>
     </div>
-    <div class="spec-doc">
-     <p>We can't reference <code>Base__</code> because it's hidden. 
-      <code>List</code>.t (<code>List.t</code>) should resolve.
-     </p>
-    </div>
    </div>
   </div>
  </body>