jon.recoil.org
this repo has no description
Line editing for dune.mld (#1180)
authored by
Christine Rose
and committed by
GitHub
5d31ff2d
a28b179e
+18
-18
doc/dune.mld
+18
-18
doc/dune.mld
···
32
32
$ dune build @doc
33
33
]}
34
34
35
-
and the results will be in [_build/default/_doc/_html/].
35
+
The results will be in [_build/default/_doc/_html/].
36
36
37
37
{1:library_wrapping Dune's Library Wrapping}
38
38
39
39
Dune has a feature whereby a library may be exposed under a single top-level
40
-
module. This makes use of an OCaml feature where the use of the compiler
41
-
flag [-no-alias-deps] is used to avoid introducing dependencies between
40
+
module. This employs an OCaml feature where using the compiler
41
+
flag [-no-alias-deps] will avoid introducing dependencies between
42
42
compilation units.
43
43
44
44
We aim to reduce the potential name clashes of modules by
45
-
only exposing one main module for library users to use,
45
+
only exposing one main module for library users,
46
46
encapsulating all other modules as submodules, while
47
47
still retaining the usual way of writing OCaml code with one module per
48
-
file. These individual files are still compiled, and installed, and
48
+
file. These individual files are still compiled, installed, and
49
49
available in the global namespace, but their names are prefixed with
50
50
the library's name in order to reduce the possibility of clashes. These
51
51
prefixed modules are not intended to be used directly, so
···
94
94
[Lib] is linked, and during this process, the
95
95
the modules [A] and [B] are expanded because they are aliases of hidden
96
96
modules. All references to [Lib__A] and [Lib__B] are replaced with the canonical
97
-
paths [Lib.A] and [Lib.B], so in this way odoc presents the library as entirely
97
+
paths [Lib.A] and [Lib.B], so in this way, [odoc] presents the library as entirely
98
98
contained within the module [Lib].
99
99
100
100
{2 Hand-Written Top-Level Module}
101
101
102
102
In some cases it's desirable to hand-write the top-level library module. This
103
-
is usually done because some of the modules within the library are intended to
104
-
be internal only and not exposed. Dune will notice that a module exists with
105
-
the name of the library ([lib.ml] in this case), so instead it will create the
106
-
file [lib__.ml]. The contents of this are identical to the previous section,
107
-
with aliases for all modules. The canonical tags on the aliases are, as before,
108
-
to [Lib.A] and [Lib.B]. These are references to module aliases that should be
109
-
present in [lib.ml]. If these are {e not} there, [odoc] won't be able to
110
-
resolve the canonical references, and any items from these modules that are
111
-
exposed elsewhere will be hidden. If the items are type aliases they can be
112
-
replaced, but otherwise they'll be rendered as unresolved links.
103
+
is usually done because some modules in the library are intended to be internal
104
+
only and not exposed. Dune will notice that a module exists with the library's
105
+
name ([lib.ml] in this case), so instead it will create the file
106
+
[lib__.ml]. Its contents are identical to the previous section, with aliases
107
+
for all modules. Like before, the canonical tags on these aliases are
108
+
references to [Lib.A] and [Lib.B]. These module should be present in [lib.ml]
109
+
as module aliases. If these are {e not} there, [odoc] won't be able to resolve
110
+
the canonical references, and any items from these modules that are exposed
111
+
elsewhere will be hidden. If the items are type aliases, they can be replaced,
112
+
but otherwise they'll be rendered as unresolved links.
113
113
114
114
For example, consider the following module structure. First, the module [Unexposed]
115
115
in file [unexposed.mli]:
···
130
130
val f : Unexposed.t
131
131
]}
132
132
133
-
and the library module that only exposes the module [Wrapping]:
133
+
The library module that only exposes the module [Wrapping]:
134
134
135
135
{[
136
136
module Wrapping = Wrapping
137
137
]}
138
138
139
-
This structure is rendered {{!Odoc_examples.Wrapping}here}.
139
+
This structure is rendered {{!Odoc_examples.Wrapping}here}.