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