ocaml · jonludlam · Sep 24, 2021 · Sep 24, 2021 · Sep 24, 2021 · Sep 24, 2021
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -13,9 +13,9 @@ jobs:
           - macos-latest
           - ubuntu-latest
           # - windows-latest Windows doesn't work yet
-        ocaml-version:
+        ocaml-compiler:
           # Don't include every versions. OCaml-CI already covers that
-          - 4.11.1
+          - 4.12.x
         include:
           - os: ubuntu-latest # Enable coverage only on a single build
             send-coverage: true
@@ -33,7 +33,7 @@ jobs:
         with:
           # Do not pin odoc to not break Mdx installation
           opam-pin: false
-          ocaml-version: ${{ matrix.ocaml-version }}
+          ocaml-compiler: ${{ matrix.ocaml-compiler }}
           opam-local-packages: |
             odoc.opam
 

diff --git a/src/ocamlary/ocamlary.mli b/src/ocamlary/ocamlary.mli
@@ -65,7 +65,7 @@ A numbered list:
 *)
 
 (**
-    Here is a table of links to indexes: {!indexlist}
+    Odoc doesn't support [{!indexlist}].
 *)
 
 (**
@@ -179,9 +179,9 @@ end
     {!section:emptySig} is the section and {!module-type:EmptySig} is the
     module signature. *)
 
-(** {!Buffer.t} *)
+(** References are resolved after everything, so [{!Buffer.t}] won't resolve. *)
 module Buffer : sig
-  val f : Buffer.t -> unit
+  val f : int -> unit
 end
 
 (** Some text before exception title.
@@ -836,6 +836,8 @@ module IncludeInclude1 : sig
   module type IncludeInclude2 = sig
     type include_include
   end
+
+  module IncludeInclude2_M : sig end
 end
 
 include module type of IncludeInclude1
@@ -850,11 +852,11 @@ include IncludeInclude2
     With odoc, everything should be resolved (and linked) but only toplevel
     units will be documented.
 
-    {!modules: Dep1.X DocOckTypes Ocamlary.IncludeInclude1 Ocamlary}
+    {!modules: Dep1.X Ocamlary.IncludeInclude1 Ocamlary}
 
     {3 Weirder usages involving module types}
 
-    {!modules: IncludeInclude1.IncludeInclude2 Dep4.T A.Q}
+    {!modules: IncludeInclude1.IncludeInclude2_M Dep4.X}
 *)
 
 (** {1 Playing with \@canonical paths} *)
@@ -875,7 +877,7 @@ module CanonicalTest : sig
     module List = Base__.List
   end
 
-  module Base__Tests : sig
+  module Base_Tests : sig
     module C : module type of Base__.List
 
     open Base__
@@ -887,16 +889,16 @@ module CanonicalTest : sig
     (** This is just {!List.id}, or rather {!L.id} *)
 
     val baz : 'a Base__.List.t -> unit
-    (** Just seeing if {!Base__.List.t} ([Base__.List.t]) gets rewriten to
-        {!Base.List.t} ([Base.List.t]) *)
+    (** 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
-(** 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} *)
 
@@ -1047,10 +1049,10 @@ module Only_a_module : sig
   type t
 end
 
-(** Some here should fail:
-    - [{!Only_a_module.t}] : {!Only_a_module.t}
+(** - [{!Only_a_module.t}] : {!Only_a_module.t}
     - [{!module-Only_a_module.t}] : {!module-Only_a_module.t}
-    - [{!module-type-Only_a_module.t}] : {!module-type-Only_a_module.t} : {{!module-type-Only_a_module.t}test}*)
+    - [{!module-Only_a_module.type-t}] : {!module-Only_a_module.type-t}
+    - [{!type:Only_a_module.t}] : {!type:Only_a_module.t} *)
 
 module type TypeExt = sig
   type t = ..

diff --git a/src/xref2/notes.md b/src/xref2/notes.md
@@ -19,7 +19,7 @@ so we have no access to type `u` in the result of applying
 `F` to `Y`.
 
 ```ocaml env=e1
-# module FY = F(Y)
+# module FY = F(Y) ;;
 module FY : sig type t = Y.t end
 ```
 

diff --git a/src/xref2/paths.md b/src/xref2/paths.md
@@ -258,7 +258,7 @@ type t = F(M).N.t
 ```
 
 ```ocaml env=e1
-# let sg = Common.compile_signature (Common.signature_of_mli_string example)
+# let sg = Common.compile_signature (Common.signature_of_mli_string example) ;;
 val sg : Odoc_model.Lang.Signature.t =
   {Odoc_model.Lang.Signature.items =
     [Odoc_model.Lang.Signature.ModuleType
@@ -386,7 +386,7 @@ of `t` during the resolution process we embed it into the returned resolved
 path as this `` `Subst `` constructor:
 
 ```ocaml env=e1
-# Common.LangUtils.Lens.(get (type_constr_path "t") sg)
+# Common.LangUtils.Lens.(get (type_constr_path "t") sg) ;;
 - : Odoc_model.Paths.Path.Type.t =
 `Resolved
   (`Type

diff --git a/src/xref2/test.md b/src/xref2/test.md
@@ -148,7 +148,7 @@ let s_manifest = type_manifest "s"
 and using this lens on our original signature we obtain:
 
 ```ocaml env=e1
-# Common.LangUtils.Lens.get u_manifest sg
+# Common.LangUtils.Lens.get u_manifest sg ;;
 - : Odoc_model.Lang.TypeExpr.t option =
 Some
  (Odoc_model.Lang.TypeExpr.Constr
@@ -227,7 +227,7 @@ The OCaml compiler find the module `M` exactly, but everything after that is lef
 to identify precisely. So the manifest of `u` is now:
 
 ```ocaml env=e1
-# Common.LangUtils.Lens.get u_manifest sg
+# Common.LangUtils.Lens.get u_manifest sg ;;
 - : Odoc_model.Lang.TypeExpr.t option =
 Some
  (Odoc_model.Lang.TypeExpr.Constr
@@ -444,7 +444,7 @@ which is `A.B.t`. The compiler has started us off by resolving the
 `A`:
 
 ```ocaml env=e1
-# Common.LangUtils.Lens.get u_manifest sg
+# Common.LangUtils.Lens.get u_manifest sg ;;
 - : Odoc_model.Lang.TypeExpr.t option =
 Some
  (Odoc_model.Lang.TypeExpr.Constr
@@ -574,7 +574,7 @@ let resolved = Common.compile_signature sg;;
 Let's look at `t`'s manifest:
 
 ```ocaml env=e1
-# Common.LangUtils.Lens.get t_manifest resolved
+# Common.LangUtils.Lens.get t_manifest resolved ;;
 - : Odoc_model.Lang.TypeExpr.t option =
 Some
  (Odoc_model.Lang.TypeExpr.Constr
@@ -612,7 +612,7 @@ let resolved = Common.compile_signature sg;;
 ```
 
 ```ocaml env=e1
-# Common.LangUtils.Lens.get t_manifest resolved
+# Common.LangUtils.Lens.get t_manifest resolved ;;
 - : Odoc_model.Lang.TypeExpr.t option =
 Some
  (Odoc_model.Lang.TypeExpr.Constr
@@ -1572,7 +1572,7 @@ let sg = Common.signature_of_mli_string test_data;;
 ```
 
 ```ocaml env=e1
-# Link.signature Env.empty id sg
+# Link.signature Env.empty id sg ;;
 - : Odoc_model.Lang.Signature.t =
 {Odoc_model.Lang.Signature.items =
   [Odoc_model.Lang.Signature.ModuleType
@@ -1651,7 +1651,7 @@ let module_M_expansion =
 ```
 
 ```ocaml env=e1
-# Common.LangUtils.Lens.get module_M_expansion expanded
+# Common.LangUtils.Lens.get module_M_expansion expanded ;;
 - : Odoc_model.Lang.ModuleType.expr =
 Odoc_model.Lang.ModuleType.Path
  {Odoc_model.Lang.ModuleType.p_expansion =

diff --git a/test/generators/cases/markup.mli b/test/generators/cases/markup.mli
@@ -154,9 +154,8 @@ v}
 
     {1 Modules}
 
-    {!modules: }
     {!modules: X}
-    {!modules: X Y Z}
+    {!modules: X Y}
 
 
     {1 Tags}
@@ -177,3 +176,8 @@ v}
 
 val foo : unit
 (** Comments in structure items {b support} {e markup}, t{^o}{_o}. *)
+
+(** Some modules to support references. *)
+
+module X : sig end
+module Y : sig end
diff --git a/test/generators/cases/type.mli b/test/generators/cases/type.mli
@@ -27,7 +27,7 @@ type nested_pair = (int * int) * int
 
 type instance = int constructor
 
-type long = labeled_higher_order -> [ `Bar | `Baz of triple] -> pair -> labeled -> higher_order -> (string -> int) -> (int,float,char,string,char,unit) CamlinternalFormatBasics.fmtty -> nested_pair -> arrow -> string -> nested_pair array
+type long = labeled_higher_order -> [ `Bar | `Baz of triple] -> pair -> labeled -> higher_order -> (string -> int) -> (int * float * char * string * char * unit) option -> nested_pair -> arrow -> string -> nested_pair array
 
 type variant_e = {a : int}
 type variant =

diff --git a/test/generators/html/Markup-X.html b/test/generators/html/Markup-X.html
@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head><title>X (Markup.X)</title><link rel="stylesheet" href="odoc.css"/>
+  <meta charset="utf-8"/><meta name="generator" content="odoc %%VERSION%%"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1.0"/>
+  <script src="highlight.pack.js"></script>
+  <script>hljs.initHighlightingOnLoad();</script>
+ </head>
+ <body class="odoc">
+  <nav class="odoc-nav"><a href="Markup.html">Up</a> – 
+   <a href="Markup.html">Markup</a> &#x00BB; X
+  </nav>
+  <header class="odoc-preamble">
+   <h1>Module <code><span>Markup.X</span></code></h1>
+  </header><div class="odoc-content"></div>
+ </body>
+</html>
diff --git a/test/generators/html/Markup-Y.html b/test/generators/html/Markup-Y.html
@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head><title>Y (Markup.Y)</title><link rel="stylesheet" href="odoc.css"/>
+  <meta charset="utf-8"/><meta name="generator" content="odoc %%VERSION%%"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1.0"/>
+  <script src="highlight.pack.js"></script>
+  <script>hljs.initHighlightingOnLoad();</script>
+ </head>
+ <body class="odoc">
+  <nav class="odoc-nav"><a href="Markup.html">Up</a> – 
+   <a href="Markup.html">Markup</a> &#x00BB; Y
+  </nav>
+  <header class="odoc-preamble">
+   <h1>Module <code><span>Markup.Y</span></code></h1>
+  </header><div class="odoc-content"></div>
+ </body>
+</html>
diff --git a/test/generators/html/Markup.html b/test/generators/html/Markup.html
@@ -179,9 +179,10 @@ <h2 id="lists"><a href="#lists" class="anchor"></a>Lists</h2>
     </blockquote>
 
    <h2 id="modules"><a href="#modules" class="anchor"></a>Modules</h2>
-   <ul class="modules"></ul><ul class="modules"><li><code>X</code> </li></ul>
-   <ul class="modules"><li><code>X</code> </li><li><code>Y</code> </li>
-    <li><code>Z</code> </li>
+   <ul class="modules"><li><a href="Markup-X.html"><code>X</code></a> </li>
+   </ul>
+   <ul class="modules"><li><a href="Markup-X.html"><code>X</code></a> </li>
+    <li><a href="Markup-Y.html"><code>Y</code></a> </li>
    </ul><h2 id="tags"><a href="#tags" class="anchor"></a>Tags</h2>
    <p>Each comment can end with zero or more tags. Here are some examples:
    </p>
@@ -243,6 +244,28 @@ <h2 id="modules"><a href="#modules" class="anchor"></a>Modules</h2>
       <sup>o</sup><sub>o</sub>.
      </p>
     </div>
+   </div><p>Some modules to support references.</p>
+   <div class="odoc-spec">
+    <div class="spec module" id="module-X" class="anchored">
+     <a href="#module-X" class="anchor"></a>
+     <code><span><span class="keyword">module</span> </span>
+      <span><a href="Markup-X.html">X</a></span>
+      <span> : <span class="keyword">sig</span> ... 
+       <span class="keyword">end</span>
+      </span>
+     </code>
+    </div>
+   </div>
+   <div class="odoc-spec">
+    <div class="spec module" id="module-Y" class="anchored">
+     <a href="#module-Y" class="anchor"></a>
+     <code><span><span class="keyword">module</span> </span>
+      <span><a href="Markup-Y.html">Y</a></span>
+      <span> : <span class="keyword">sig</span> ... 
+       <span class="keyword">end</span>
+      </span>
+     </code>
+    </div>
    </div>
   </div>
  </body>

diff --git a/test/generators/html/Ocamlary-Buffer.html b/test/generators/html/Ocamlary-Buffer.html
@@ -13,17 +13,17 @@
   </nav>
   <header class="odoc-preamble">
    <h1>Module <code><span>Ocamlary.Buffer</span></code></h1>
-   <p><code>Buffer</code>.t</p>
+   <p>References are resolved after everything, so <code>{!Buffer.t}</code>
+     won't resolve.
+   </p>
   </header>
   <div class="odoc-content">
    <div class="odoc-spec">
     <div class="spec value" id="val-f" class="anchored">
      <a href="#val-f" class="anchor"></a>
      <code>
       <span><span class="keyword">val</span> f : 
-       <span><span class="xref-unresolved">Stdlib</span>.Buffer.t 
-        <span class="arrow">&#45;&gt;</span>
-       </span> unit
+       <span>int <span class="arrow">&#45;&gt;</span></span> unit
       </span>
      </code>
     </div>

diff --git a/test/generators/html/Ocamlary-CanonicalTest-Base_Tests-C.html b/test/generators/html/Ocamlary-CanonicalTest-Base_Tests-C.html
@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head><title>C (Ocamlary.CanonicalTest.Base_Tests.C)</title>
+  <link rel="stylesheet" href="odoc.css"/><meta charset="utf-8"/>
+  <meta name="generator" content="odoc %%VERSION%%"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1.0"/>
+  <script src="highlight.pack.js"></script>
+  <script>hljs.initHighlightingOnLoad();</script>
+ </head>
+ <body class="odoc">
+  <nav class="odoc-nav">
+   <a href="Ocamlary-CanonicalTest-Base_Tests.html">Up</a> – 
+   <a href="Ocamlary.html">Ocamlary</a> &#x00BB; 
+   <a href="Ocamlary-CanonicalTest.html">CanonicalTest</a> &#x00BB; 
+   <a href="Ocamlary-CanonicalTest-Base_Tests.html">Base_Tests</a> &#x00BB;
+    C
+  </nav>
+  <header class="odoc-preamble">
+   <h1>Module <code><span>Base_Tests.C</span></code></h1>
+  </header>
+  <div class="odoc-content">
+   <div class="odoc-spec">
+    <div class="spec type" id="type-t" class="anchored">
+     <a href="#type-t" class="anchor"></a>
+     <code><span><span class="keyword">type</span> <span>'a t</span></span>
+     </code>
+    </div>
+   </div>
+   <div class="odoc-spec">
+    <div class="spec value" id="val-id" class="anchored">
+     <a href="#val-id" class="anchor"></a>
+     <code>
+      <span><span class="keyword">val</span> id : 
+       <span>
+        <span><span class="type-var">'a</span> <a href="#type-t">t</a></span>
+         <span class="arrow">&#45;&gt;</span>
+       </span> 
+       <span><span class="type-var">'a</span> <a href="#type-t">t</a></span>
+      </span>
+     </code>
+    </div>
+   </div>
+  </div>
+ </body>
+</html>