diff --git a/doc/dune.mld b/doc/dune.mld index 42adf454bf..49be552cfd 100644 --- a/doc/dune.mld +++ b/doc/dune.mld @@ -32,20 +32,20 @@ Dune creates the docs for these with this command: $ dune build @doc ]} -and the results will be in [_build/default/_doc/_html/]. +The results will be in [_build/default/_doc/_html/]. {1:library_wrapping Dune's Library Wrapping} Dune has a feature whereby a library may be exposed under a single top-level -module. This makes use of an OCaml feature where the use of the compiler -flag [-no-alias-deps] is used to avoid introducing dependencies between +module. This employs an OCaml feature where using the compiler +flag [-no-alias-deps] will avoid introducing dependencies between compilation units. We aim to reduce the potential name clashes of modules by -only exposing one main module for library users to use, +only exposing one main module for library users, encapsulating all other modules as submodules, while still retaining the usual way of writing OCaml code with one module per -file. These individual files are still compiled, and installed, and +file. These individual files are still compiled, installed, and available in the global namespace, but their names are prefixed with the library's name in order to reduce the possibility of clashes. These prefixed modules are not intended to be used directly, so @@ -94,22 +94,22 @@ have double underscores meaning they are hidden. Only the non-hidden module [Lib] is linked, and during this process, the the modules [A] and [B] are expanded because they are aliases of hidden modules. All references to [Lib__A] and [Lib__B] are replaced with the canonical -paths [Lib.A] and [Lib.B], so in this way odoc presents the library as entirely +paths [Lib.A] and [Lib.B], so in this way, [odoc] presents the library as entirely contained within the module [Lib]. {2 Hand-Written Top-Level Module} In some cases it's desirable to hand-write the top-level library module. This -is usually done because some of the modules within the library are intended to -be internal only and not exposed. Dune will notice that a module exists with -the name of the library ([lib.ml] in this case), so instead it will create the -file [lib__.ml]. The contents of this are identical to the previous section, -with aliases for all modules. The canonical tags on the aliases are, as before, -to [Lib.A] and [Lib.B]. These are references to module aliases that should be -present in [lib.ml]. If these are {e not} there, [odoc] won't be able to -resolve the canonical references, and any items from these modules that are -exposed elsewhere will be hidden. If the items are type aliases they can be -replaced, but otherwise they'll be rendered as unresolved links. +is usually done because some modules in the library are intended to be internal +only and not exposed. Dune will notice that a module exists with the library's +name ([lib.ml] in this case), so instead it will create the file +[lib__.ml]. Its contents are identical to the previous section, with aliases +for all modules. Like before, the canonical tags on these aliases are +references to [Lib.A] and [Lib.B]. These module should be present in [lib.ml] +as module aliases. If these are {e not} there, [odoc] won't be able to resolve +the canonical references, and any items from these modules that are exposed +elsewhere will be hidden. If the items are type aliases, they can be replaced, +but otherwise they'll be rendered as unresolved links. For example, consider the following module structure. First, the module [Unexposed] in file [unexposed.mli]: @@ -130,10 +130,10 @@ type t = Unexposed.t val f : Unexposed.t ]} -and the library module that only exposes the module [Wrapping]: +The library module that only exposes the module [Wrapping]: {[ module Wrapping = Wrapping ]} -This structure is rendered {{!Odoc_examples.Wrapping}here}. \ No newline at end of file +This structure is rendered {{!Odoc_examples.Wrapping}here}.