jon.recoil.org
this repo has no description
line edit features.mld (#1172)
* line edit features.mld
* remove extra space
* Removed "then" to make sentence accurate
* reverted to "given the following:
* changed "to" to "of"
* changed "to" to "of"
* change module-type to [module type} when adj.
* apply agreed changes
authored by
Christine Rose
and committed by
GitHub
468ab028
dd5cbd35
+30
-30
doc/features.mld
+30
-30
doc/features.mld
···
2
3
[odoc] works by taking module interfaces, processing them to make them more
4
useful, and turning them into documentation. This processing is largely {{!hiding}hiding}, handling of {{!canonical}
5
-
canonical references}, {{!expansion}expansion} and {{!resolution}resolution}.
6
This document explains the features of these processes in detail.
7
8
{1:hiding Hiding}
9
10
Some items are not intended to be used directly but are present as
11
-
implementation detail, e.g., for testing, for implementing Dune's namespacing, or other reasons.
12
13
There are two mechanisms for explicitly hiding elements from the final
14
output. The first is to use {{:https://ocaml.org/manual/ocamldoc.html#ss:ocamldoc-stop}documentation stop comments},
···
20
Occasionally it’s useful to declare an item in one place and expose
21
it in the public interface in another. In order to prevent unwanted occurrences
22
of the actual definition site, [odoc] has a feature whereby the 'canonical'
23
-
location of a module, module type or type can be specified.
24
25
-
The biggest user of module aliases is Dune's {{:https://dune.readthedocs.io/en/stable/dune-files.html#library}wrapped libraries}.
26
This feature allows Dune to produce a library whose interface is exposed entirely
27
though a single top-level module. It does this by mangling the names of the
28
real implementation modules and generating the single top-level module that
29
simply contains aliases to the these implementation modules. With [odoc]'s
30
-
canonical modules feature all references to the implementation modules are
31
-
rewritten to point at the aliases in the top-level module instead. Please
32
see the section on Dune's
33
{{!page-dune.library_wrapping}library wrapping} for more detail.
34
···
64
65
{2:expansion_aliases Aliases}
66
67
-
In general [odoc] doesn’t expand module aliases unless they are an
68
alias to a hidden module. If this is the case, the right-hand side of
69
the declaration is dropped and replaced with [sig ... end], and
70
the expansion is created.
···
82
83
]}
84
85
-
the [Hidden__module] module won’t be present in the output, and
86
the [Alias] module will be rendered as if it were a simple
87
signature. This can be seen in the example rendering {{!Odoc_examples.Expansion.Aliases}here}.
88
···
106
module type B = A
107
]}
108
109
-
For these simple module type declarations, where the right-hand side is just a
110
path, [odoc] treats them as module aliases and doesn’t produce an expansion.
111
This example is rendered {{!Odoc_examples.Expansion.ModuleTypeAliases}here}.
112
113
-
When strengthening, OCaml turns modules into aliases to the original
114
module, but nothing is done to module types. In contrast, [odoc] replaces
115
-
module types with 'aliases' to the originals, too. These are not expanded, hence this is important for reducing the size of the output.
116
117
The following examples use [module type of struct include ... end] to
118
obtain the strengthened signature of [A] (see the {{!module_type_of}[Module Type Of]}
···
298
module M : MODTYPE with type X.t = foo
299
]}
300
301
-
the {{!Odoc_examples.Expansion.DeepEquality2.M}expansion of M} does not contain any [with type] equations.
302
303
{2 Substitution}
304
···
307
type or module is entirely removed from the resulting signature.
308
309
As with the addition of equations above, these substitutions may be on
310
-
deeply nested modules, and care needs to be taken to ensure that there are
311
no references to the removed module or type left. For example:
312
313
{[
···
329
type t = M.t
330
]}
331
332
-
From this expansion it is still clear how to resolve the right-hand side
333
-
of [type t = M.t], and the next phase of [odoc]'s transformation turns the
334
right-hand side of [M.t] into [int].
335
336
In the output documentation, the declaration of [module M] is rendered
···
340
module M : sig ... end
341
]}
342
343
-
with the type substitution dropped. This is because the type substitition on
344
-
the simple signature isn't useful for the reader; the link [t] would
345
have no destination. This example is rendered {{!Odoc_examples.Expansion.TypeSubstitution}here}.
346
347
···
350
The OCaml construct [module type of] allows the type of a module to be
351
recovered. As usual, when OCaml performs this operation, it only retains
352
the simplified signature, stripped of comments, includes, and more
353
-
complex module type expressions. As with the previous sections, [odoc]
354
tries a little harder to keep track of these things and also of the
355
fact that the signature came from a [module type of] expression.
356
···
367
module M : module type of A
368
]}
369
370
-
the [type t] in module [M] has the comment from the original module.
371
There is also logic in [odoc] to manage the similar construct
372
[module type of struct include ... end], which is used where the types
373
and modules are required to be strengthened. That is, the types in
···
411
end
412
]}
413
414
-
whereas [odoc] preserves the fact that [Y] and [Z] are calculated from [X]. If the
415
module [X] is subsequently replaced using a destructive substitution on [S], the
416
-
results would be different. Given the following,
417
418
{[
419
module X1 : sig
···
424
module type T = S with module X := X1
425
]}
426
427
-
then the signature of [T] as calculated by OCaml will be
428
429
{[
430
sig
···
440
syntax for representing transparent ascription, the consequence is that we lose
441
the fact that [Y] and [Z] originally came from [module type of] expressions.
442
443
-
This example is rendered {{!Odoc_examples.Expansion.ModuleTypeOfComplications}here},
444
-
and in the {{!Odoc_examples.Expansion.ModuleTypeOfComplications.T}expansion of T}, it
445
can be seen that [Y] and [Z] are simple signatures only containing [type t].
446
447
···
462
identifiers; however, unlike paths, they are not checked by the compiler and are entirely
463
resolved by [odoc].
464
465
-
In most of the output formats, [odoc] supports paths; references and fragments will be
466
turned into links that take the reader to the referred identifier. These
467
links need to consider some of the expansions’ features,
468
as outlined above. In order to decide where the links should point to and how to
···
512
When encountering a module, module type, or a type that has been marked with a
513
[@canonical] tag, [odoc] first has to check that the specified canonical path
514
actually resolves. If this is the case, in a similar way to the alias above, the
515
-
target of the path will be rewritten to point to the canonical path.
516
-
However, in contrast to the alias behaviour, the {e text} of the path will
517
also be rewritten, so it will be as if the canonical path had been written instead
518
of whatever path was actually there.
519
···
544
545
{2 Fragment Resolution}
546
547
-
Fragments are relative paths that appear in module type expressions when
548
adding equations or substituting types or modules. For example:
549
550
{[
···
588
]}
589
590
[type v] will have a right-hand side of [T of int], as the hidden [type t] is
591
-
equal to [int]; whereas, there is no non-hidden type equivalent to [u], so the
592
right-hand side of [type w] is omitted from the output.
593
594
{2:reference_resolution Reference Resolution}
595
596
-
References are hand-written in comments and not evaluated in any way by the
597
compiler.
598
599
{[
···
2
3
[odoc] works by taking module interfaces, processing them to make them more
4
useful, and turning them into documentation. This processing is largely {{!hiding}hiding}, handling of {{!canonical}
5
+
canonical references}, {{!expansion}expansion}, and {{!resolution}resolution}.
6
This document explains the features of these processes in detail.
7
8
{1:hiding Hiding}
9
10
Some items are not intended to be used directly but are present as
11
+
implementation detail, e.g., for testing, implementing Dune's namespacing, or other reasons.
12
13
There are two mechanisms for explicitly hiding elements from the final
14
output. The first is to use {{:https://ocaml.org/manual/ocamldoc.html#ss:ocamldoc-stop}documentation stop comments},
···
20
Occasionally it’s useful to declare an item in one place and expose
21
it in the public interface in another. In order to prevent unwanted occurrences
22
of the actual definition site, [odoc] has a feature whereby the 'canonical'
23
+
location of a module, module type, or type can be specified.
24
25
+
The biggest user of module aliases is Dune's {{:https://dune.readthedocs.io/en/stable/reference/dune/library.html#library}wrapped libraries}.
26
This feature allows Dune to produce a library whose interface is exposed entirely
27
though a single top-level module. It does this by mangling the names of the
28
real implementation modules and generating the single top-level module that
29
simply contains aliases to the these implementation modules. With [odoc]'s
30
+
canonical modules feature, all references to the implementation modules are
31
+
rewritten to point at the top-level module aliases instead. Please
32
see the section on Dune's
33
{{!page-dune.library_wrapping}library wrapping} for more detail.
34
···
64
65
{2:expansion_aliases Aliases}
66
67
+
In general, [odoc] doesn’t expand module aliases unless they are an
68
alias to a hidden module. If this is the case, the right-hand side of
69
the declaration is dropped and replaced with [sig ... end], and
70
the expansion is created.
···
82
83
]}
84
85
+
The [Hidden__module] module won’t be present in the output, and
86
the [Alias] module will be rendered as if it were a simple
87
signature. This can be seen in the example rendering {{!Odoc_examples.Expansion.Aliases}here}.
88
···
106
module type B = A
107
]}
108
109
+
For these simple [module type] declarations, where the right-hand side is just a
110
path, [odoc] treats them as module aliases and doesn’t produce an expansion.
111
This example is rendered {{!Odoc_examples.Expansion.ModuleTypeAliases}here}.
112
113
+
When strengthening, OCaml turns modules into aliases of the original
114
module, but nothing is done to module types. In contrast, [odoc] replaces
115
+
module types with 'aliases' of the originals, too. These are not expanded, hence this is important for reducing the size of the output.
116
117
The following examples use [module type of struct include ... end] to
118
obtain the strengthened signature of [A] (see the {{!module_type_of}[Module Type Of]}
···
298
module M : MODTYPE with type X.t = foo
299
]}
300
301
+
The {{!Odoc_examples.Expansion.DeepEquality2.M}expansion of M} does not contain any [with type] equations.
302
303
{2 Substitution}
304
···
307
type or module is entirely removed from the resulting signature.
308
309
As with the addition of equations above, these substitutions may be on
310
+
deeply nested modules. Care must be taken to ensure that there are
311
no references to the removed module or type left. For example:
312
313
{[
···
329
type t = M.t
330
]}
331
332
+
From this expansion, it is still clear how to resolve the right-hand side
333
+
of [type t = M.t]. The next phase of [odoc]'s transformation turns the
334
right-hand side of [M.t] into [int].
335
336
In the output documentation, the declaration of [module M] is rendered
···
340
module M : sig ... end
341
]}
342
343
+
with the type substitution dropped. This is because the simple signature's type substitition
344
+
isn't useful for the reader. The link [t] would
345
have no destination. This example is rendered {{!Odoc_examples.Expansion.TypeSubstitution}here}.
346
347
···
350
The OCaml construct [module type of] allows the type of a module to be
351
recovered. As usual, when OCaml performs this operation, it only retains
352
the simplified signature, stripped of comments, includes, and more
353
+
complex [module type] expressions. As with the previous sections, [odoc]
354
tries a little harder to keep track of these things and also of the
355
fact that the signature came from a [module type of] expression.
356
···
367
module M : module type of A
368
]}
369
370
+
The [type t] in module [M] has the comment from the original module.
371
There is also logic in [odoc] to manage the similar construct
372
[module type of struct include ... end], which is used where the types
373
and modules are required to be strengthened. That is, the types in
···
411
end
412
]}
413
414
+
On the other hand, [odoc] preserves the fact that [Y] and [Z] are calculated from [X]. If the
415
module [X] is subsequently replaced using a destructive substitution on [S], the
416
+
results would be different. For example:
417
418
{[
419
module X1 : sig
···
424
module type T = S with module X := X1
425
]}
426
427
+
The signature of [T], as calculated by OCaml, will be
428
429
{[
430
sig
···
440
syntax for representing transparent ascription, the consequence is that we lose
441
the fact that [Y] and [Z] originally came from [module type of] expressions.
442
443
+
This example is rendered {{!Odoc_examples.Expansion.ModuleTypeOfComplications}here}.
444
+
In the {{!Odoc_examples.Expansion.ModuleTypeOfComplications.T}expansion of T}, it
445
can be seen that [Y] and [Z] are simple signatures only containing [type t].
446
447
···
462
identifiers; however, unlike paths, they are not checked by the compiler and are entirely
463
resolved by [odoc].
464
465
+
In most of the output formats, [odoc] supports paths. References and fragments will be
466
turned into links that take the reader to the referred identifier. These
467
links need to consider some of the expansions’ features,
468
as outlined above. In order to decide where the links should point to and how to
···
512
When encountering a module, module type, or a type that has been marked with a
513
[@canonical] tag, [odoc] first has to check that the specified canonical path
514
actually resolves. If this is the case, in a similar way to the alias above, the
515
+
path's target will be rewritten to point to the canonical path.
516
+
However, in contrast to the alias behaviour, the path's {e text} will
517
also be rewritten, so it will be as if the canonical path had been written instead
518
of whatever path was actually there.
519
···
544
545
{2 Fragment Resolution}
546
547
+
Fragments are relative paths that appear in [module type] expressions when
548
adding equations or substituting types or modules. For example:
549
550
{[
···
588
]}
589
590
[type v] will have a right-hand side of [T of int], as the hidden [type t] is
591
+
equal to [int]. Conversely, there is no non-hidden type equivalent to [u], so the
592
right-hand side of [type w] is omitted from the output.
593
594
{2:reference_resolution Reference Resolution}
595
596
+
References are handwritten in comments and not evaluated in any way by the
597
compiler.
598
599
{[