1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
|
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="hevea 2.32">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1">
<link rel="stylesheet" type="text/css" href="manual.css">
<title>Chapter 16 The documentation generator (ocamldoc)</title>
</head>
<body>
<a href="browser.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="index.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="debugger.html"><img src="next_motif.svg" alt="Next"></a>
<hr>
<h1 class="chapter" id="sec345">Chapter 16 The documentation generator (ocamldoc)</h1>
<ul>
<li><a href="ocamldoc.html#s%3Aocamldoc-usage">16.1 Usage</a>
</li><li><a href="ocamldoc.html#s%3Aocamldoc-comments">16.2 Syntax of documentation comments</a>
</li><li><a href="ocamldoc.html#s%3Aocamldoc-custom-generators">16.3 Custom generators</a>
</li><li><a href="ocamldoc.html#s%3Aocamldoc-adding-flags">16.4 Adding command line options</a>
</li></ul>
<p> <a id="c:ocamldoc"></a>
</p><p>This chapter describes OCamldoc, a tool that generates documentation from
special comments embedded in source files. The comments used by OCamldoc
are of the form <span class="c003">(**</span>…<span class="c003">*)</span> and follow the format described
in section <a href="#s%3Aocamldoc-comments">16.2</a>.</p><p>OCamldoc can produce documentation in various formats: HTML, L<sup>A</sup>T<sub>E</sub>X,
TeXinfo, Unix man pages, and <span class="c003">dot</span> dependency graphs. Moreover,
users can add their own custom generators, as explained in
section <a href="#s%3Aocamldoc-custom-generators">16.3</a>.</p><p>In this chapter, we use the word <em>element</em> to refer to any of the
following parts of an OCaml source file: a type declaration, a value,
a module, an exception, a module type, a type constructor, a record
field, a class, a class type, a class method, a class value or a class
inheritance clause.</p>
<h2 class="section" id="s:ocamldoc-usage"><a class="section-anchor" href="#s:ocamldoc-usage" aria-hidden="true"></a>16.1 Usage</h2>
<h3 class="subsection" id="ss:ocamldoc-invocation"><a class="section-anchor" href="#ss:ocamldoc-invocation" aria-hidden="true"></a>16.1.1 Invocation</h3>
<p>OCamldoc is invoked via the command <span class="c003">ocamldoc</span>, as follows:
</p><pre>
ocamldoc <span class="c009">options sourcefiles</span>
</pre><h4 class="subsubsection" id="sss:ocamldoc-output"><a class="section-anchor" href="#sss:ocamldoc-output" aria-hidden="true"></a>Options for choosing the output format</h4>
<p>The following options determine the format for the generated
documentation.</p><dl class="description"><dt class="dt-description">
<span class="c006">-html</span></dt><dd class="dd-description">
Generate documentation in HTML default format. The generated HTML pages
are stored in the current directory, or in the directory specified
with the <span class="c006">-d</span> option. You can customize the style of the
generated pages by editing the generated <span class="c003">style.css</span> file, or by providing
your own style sheet using option <span class="c003">-css-style</span>.
The file <span class="c003">style.css</span> is not generated if it already exists or if -css-style is used.</dd><dt class="dt-description"><span class="c006">-latex</span></dt><dd class="dd-description">
Generate documentation in L<sup>A</sup>T<sub>E</sub>X default format. The generated
L<sup>A</sup>T<sub>E</sub>X document is saved in file <span class="c003">ocamldoc.out</span>, or in the file
specified with the <span class="c006">-o</span> option. The document uses the style file
<span class="c003">ocamldoc.sty</span>. This file is generated when using the <span class="c003">-latex</span> option,
if it does not already exist.
You can change this file to customize the style of your L<sup>A</sup>T<sub>E</sub>X documentation.</dd><dt class="dt-description"><span class="c006">-texi</span></dt><dd class="dd-description">
Generate documentation in TeXinfo default format. The generated
L<sup>A</sup>T<sub>E</sub>X document is saved in file <span class="c003">ocamldoc.out</span>, or in the file
specified with the <span class="c006">-o</span> option.</dd><dt class="dt-description"><span class="c006">-man</span></dt><dd class="dd-description">
Generate documentation as a set of Unix <span class="c003">man</span> pages. The generated pages
are stored in the current directory, or in the directory specified
with the <span class="c006">-d</span> option.</dd><dt class="dt-description"><span class="c006">-dot</span></dt><dd class="dd-description">
Generate a dependency graph for the toplevel modules, in a format suitable
for displaying and processing by <span class="c003">dot</span>. The <span class="c003">dot</span> tool is available from
<a href="https://graphviz.org/"><span class="c003">https://graphviz.org/</span></a>.
The textual representation of the graph is written to the file
<span class="c003">ocamldoc.out</span>, or to the file specified with the <span class="c006">-o</span> option.
Use <span class="c003">dot ocamldoc.out</span> to display it.</dd><dt class="dt-description"><span class="c013"><span class="c003">-g</span> <span class="c009">file.cm[o,a,xs]</span></span></dt><dd class="dd-description">
Dynamically load the given file, which defines a custom documentation
generator. See section <a href="#ss%3Aocamldoc-compilation-and-usage">16.4.1</a>. This
option is supported by the <span class="c003">ocamldoc</span> command (to load <span class="c003">.cmo</span> and <span class="c003">.cma</span> files)
and by its native-code version <span class="c003">ocamldoc.opt</span> (to load <span class="c003">.cmxs</span> files).
If the given file is a simple one and does not exist in
the current directory, then ocamldoc looks for it in the custom
generators default directory, and in the directories specified with
optional <span class="c003">-i</span> options.</dd><dt class="dt-description"><span class="c006">-customdir</span></dt><dd class="dd-description">
Display the custom generators default directory.</dd><dt class="dt-description"><span class="c013"><span class="c003">-i</span> <span class="c009">directory</span></span></dt><dd class="dd-description">
Add the given directory to the path where to look for custom generators.</dd></dl><h4 class="subsubsection" id="sss:ocamldoc-options"><a class="section-anchor" href="#sss:ocamldoc-options" aria-hidden="true"></a>General options</h4>
<dl class="description"><dt class="dt-description"><span class="c013"><span class="c003">-d</span> <span class="c009">dir</span></span></dt><dd class="dd-description">
Generate files in directory <span class="c009">dir</span>, rather than the current directory.</dd><dt class="dt-description"><span class="c013"><span class="c003">-dump</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Dump collected information into <span class="c009">file</span>. This information can be
read with the <span class="c003">-load</span> option in a subsequent invocation of <span class="c003">ocamldoc</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-hide</span> <span class="c009">modules</span></span></dt><dd class="dd-description">
Hide the given complete module names in the generated documentation.
<span class="c009">modules</span> is a list of complete module names separated
by ’<span class="c003">,</span>’, without blanks. For instance: <span class="c003">Stdlib,M2.M3</span>.</dd><dt class="dt-description"><span class="c006">-inv-merge-ml-mli</span></dt><dd class="dd-description">
Reverse the precedence of implementations and interfaces when merging.
All elements
in implementation files are kept, and the <span class="c006">-m</span> option
indicates which parts of the comments in interface files are merged
with the comments in implementation files.</dd><dt class="dt-description"><span class="c006">-keep-code</span></dt><dd class="dd-description">
Always keep the source code for values, methods and instance variables,
when available.</dd><dt class="dt-description"><span class="c013"><span class="c003">-load</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Load information from <span class="c009">file</span>, which has been produced by
<span class="c003">ocamldoc -dump</span>. Several <span class="c003">-load</span> options can be given.</dd><dt class="dt-description"><span class="c013"><span class="c003">-m</span> <span class="c009">flags</span></span></dt><dd class="dd-description">
Specify merge options between interfaces and implementations.
(see section <a href="#ss%3Aocamldoc-merge">16.1.2</a> for details).
<span class="c009">flags</span> can be one or several of the following characters:
<dl class="description"><dt class="dt-description">
<span class="c006">d</span></dt><dd class="dd-description"> merge description
</dd><dt class="dt-description"><span class="c006">a</span></dt><dd class="dd-description"> merge <span class="c003">@author</span>
</dd><dt class="dt-description"><span class="c006">v</span></dt><dd class="dd-description"> merge <span class="c003">@version</span>
</dd><dt class="dt-description"><span class="c006">l</span></dt><dd class="dd-description"> merge <span class="c003">@see</span>
</dd><dt class="dt-description"><span class="c006">s</span></dt><dd class="dd-description"> merge <span class="c003">@since</span>
</dd><dt class="dt-description"><span class="c006">b</span></dt><dd class="dd-description"> merge <span class="c003">@before</span>
</dd><dt class="dt-description"><span class="c006">o</span></dt><dd class="dd-description"> merge <span class="c003">@deprecated</span>
</dd><dt class="dt-description"><span class="c006">p</span></dt><dd class="dd-description"> merge <span class="c003">@param</span>
</dd><dt class="dt-description"><span class="c006">e</span></dt><dd class="dd-description"> merge <span class="c003">@raise</span>
</dd><dt class="dt-description"><span class="c006">r</span></dt><dd class="dd-description"> merge <span class="c003">@return</span>
</dd><dt class="dt-description"><span class="c006">A</span></dt><dd class="dd-description"> merge everything
</dd></dl></dd><dt class="dt-description"><span class="c006">-no-custom-tags</span></dt><dd class="dd-description">
Do not allow custom @-tags (see section <a href="#ss%3Aocamldoc-tags">16.2.5</a>).</dd><dt class="dt-description"><span class="c006">-no-stop</span></dt><dd class="dd-description">
Keep elements placed after/between the <span class="c003">(**/**)</span> special comment(s)
(see section <a href="#s%3Aocamldoc-comments">16.2</a>).</dd><dt class="dt-description"><span class="c013"><span class="c003">-o</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Output the generated documentation to <span class="c009">file</span> instead of <span class="c003">ocamldoc.out</span>.
This option is meaningful only in conjunction with the
<span class="c006">-latex</span>, <span class="c006">-texi</span>, or <span class="c006">-dot</span> options.</dd><dt class="dt-description"><span class="c013"><span class="c003">-pp</span> <span class="c009">command</span></span></dt><dd class="dd-description">
Pipe sources through preprocessor <span class="c009">command</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-impl</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Process the file <span class="c009">filename</span> as an implementation file, even if its
extension is not <span class="c003">.ml</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-intf</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Process the file <span class="c009">filename</span> as an interface file, even if its
extension is not <span class="c003">.mli</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-text</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Process the file <span class="c009">filename</span> as a text file, even if its
extension is not <span class="c003">.txt</span>.</dd><dt class="dt-description"><span class="c006">-sort</span></dt><dd class="dd-description">
Sort the list of top-level modules before generating the documentation.</dd><dt class="dt-description"><span class="c006">-stars</span></dt><dd class="dd-description">
Remove blank characters until the first asterisk (’<span class="c003">*</span>’) in each
line of comments.</dd><dt class="dt-description"><span class="c013"><span class="c003">-t</span> <span class="c009">title</span></span></dt><dd class="dd-description">
Use <span class="c009">title</span> as the title for the generated documentation.</dd><dt class="dt-description"><span class="c013"><span class="c003">-intro</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Use content of <span class="c009">file</span> as ocamldoc text to use as introduction (HTML,
L<sup>A</sup>T<sub>E</sub>X and TeXinfo only).
For HTML, the file is used to create the whole <span class="c003">index.html</span> file.</dd><dt class="dt-description"><span class="c006">-v</span></dt><dd class="dd-description">
Verbose mode. Display progress information.</dd><dt class="dt-description"><span class="c006">-version</span></dt><dd class="dd-description">
Print version string and exit.</dd><dt class="dt-description"><span class="c006">-vnum</span></dt><dd class="dd-description">
Print short version number and exit.</dd><dt class="dt-description"><span class="c006">-warn-error</span></dt><dd class="dd-description">
Treat Ocamldoc warnings as errors.</dd><dt class="dt-description"><span class="c006">-hide-warnings</span></dt><dd class="dd-description">
Do not print OCamldoc warnings.</dd><dt class="dt-description"><span class="c013"><span class="c003">-help</span> or <span class="c003">--help</span></span></dt><dd class="dd-description">
Display a short usage summary and exit.
</dd></dl><h4 class="subsubsection" id="sss:ocamldoc-type-checking"><a class="section-anchor" href="#sss:ocamldoc-type-checking" aria-hidden="true"></a>Type-checking options</h4>
<p>OCamldoc calls the OCaml type-checker to obtain type
information. The following options impact the type-checking phase.
They have the same meaning as for the <span class="c003">ocamlc</span> and <span class="c003">ocamlopt</span> commands.</p><dl class="description"><dt class="dt-description"><span class="c013"><span class="c003">-I</span> <span class="c009">directory</span></span></dt><dd class="dd-description">
Add <span class="c009">directory</span> to the list of directories search for compiled
interface files (<span class="c003">.cmi</span> files).</dd><dt class="dt-description"><span class="c006">-nolabels</span></dt><dd class="dd-description">
Ignore non-optional labels in types.</dd><dt class="dt-description"><span class="c006">-rectypes</span></dt><dd class="dd-description">
Allow arbitrary recursive types. (See the <span class="c003">-rectypes</span> option to <span class="c003">ocamlc</span>.)</dd></dl><h4 class="subsubsection" id="sss:ocamldoc-html"><a class="section-anchor" href="#sss:ocamldoc-html" aria-hidden="true"></a>Options for generating HTML pages</h4>
<p>The following options apply in conjunction with the <span class="c003">-html</span> option:</p><dl class="description"><dt class="dt-description">
<span class="c006">-all-params</span></dt><dd class="dd-description">
Display the complete list of parameters for functions and methods.</dd><dt class="dt-description"><span class="c013"><span class="c003">-charset</span> <span class="c009">charset</span></span></dt><dd class="dd-description">
Add information about character encoding being <span class="c009">charset</span>
(default is iso-8859-1).</dd><dt class="dt-description"><span class="c006">-colorize-code</span></dt><dd class="dd-description">
Colorize the OCaml code enclosed in <span class="c003">[ ]</span> and <span class="c003">{[ ]}</span>, using colors
to emphasize keywords, etc. If the code fragments are not
syntactically correct, no color is added.</dd><dt class="dt-description"><span class="c013"><span class="c003">-css-style</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Use <span class="c009">filename</span> as the Cascading Style Sheet file.</dd><dt class="dt-description"><span class="c006">-index-only</span></dt><dd class="dd-description">
Generate only index files.</dd><dt class="dt-description"><span class="c006">-short-functors</span></dt><dd class="dd-description">
Use a short form to display functors:
<pre>
module M : functor (A:Module) -> functor (B:Module2) -> sig .. end
</pre>
is displayed as:
<pre>
module M (A:Module) (B:Module2) : sig .. end
</pre></dd></dl><h4 class="subsubsection" id="sss:ocamldoc-latex"><a class="section-anchor" href="#sss:ocamldoc-latex" aria-hidden="true"></a>Options for generating L<sup>A</sup>T<sub>E</sub>X files</h4>
<p>The following options apply in conjunction with the <span class="c003">-latex</span> option:</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">-latex-value-prefix</span> <span class="c009">prefix</span></span></dt><dd class="dd-description">
Give a prefix to use for the labels of the values in the generated
L<sup>A</sup>T<sub>E</sub>X document.
The default prefix is the empty string. You can also use the options
<span class="c003">-latex-type-prefix</span>, <span class="c003">-latex-exception-prefix</span>,
<span class="c003">-latex-module-prefix</span>,
<span class="c003">-latex-module-type-prefix</span>, <span class="c003">-latex-class-prefix</span>,
<span class="c003">-latex-class-type-prefix</span>,
<span class="c003">-latex-attribute-prefix</span> and <span class="c003">-latex-method-prefix</span>.<p>These options are useful when you have, for example, a type and a value with
the same name. If you do not specify prefixes, L<sup>A</sup>T<sub>E</sub>X will complain about
multiply defined labels.</p></dd><dt class="dt-description"><span class="c013"><span class="c003">-latextitle</span> <span class="c009">n,style</span></span></dt><dd class="dd-description">
Associate style number <span class="c009">n</span> to the given L<sup>A</sup>T<sub>E</sub>X sectioning command
<span class="c009">style</span>, e.g. <span class="c003">section</span> or <span class="c003">subsection</span>. (L<sup>A</sup>T<sub>E</sub>X only.) This is
useful when including the generated document in another L<sup>A</sup>T<sub>E</sub>X document,
at a given sectioning level. The default association is 1 for <span class="c003">section</span>,
2 for <span class="c003">subsection</span>, 3 for <span class="c003">subsubsection</span>, 4 for <span class="c003">paragraph</span> and 5 for
<span class="c003">subparagraph</span>.</dd><dt class="dt-description"><span class="c006">-noheader</span></dt><dd class="dd-description">
Suppress header in generated documentation.</dd><dt class="dt-description"><span class="c006">-notoc</span></dt><dd class="dd-description">
Do not generate a table of contents.</dd><dt class="dt-description"><span class="c006">-notrailer</span></dt><dd class="dd-description">
Suppress trailer in generated documentation.</dd><dt class="dt-description"><span class="c006">-sepfiles</span></dt><dd class="dd-description">
Generate one <span class="c003">.tex</span> file per toplevel module, instead of the global
<span class="c003">ocamldoc.out</span> file.
</dd></dl><h4 class="subsubsection" id="sss:ocamldoc-info"><a class="section-anchor" href="#sss:ocamldoc-info" aria-hidden="true"></a>Options for generating TeXinfo files</h4>
<p>The following options apply in conjunction with the <span class="c003">-texi</span> option:</p><dl class="description"><dt class="dt-description">
<span class="c006">-esc8</span></dt><dd class="dd-description">
Escape accented characters in Info files.</dd><dt class="dt-description"><span class="c006">-info-entry</span></dt><dd class="dd-description">
Specify Info directory entry.</dd><dt class="dt-description"><span class="c006">-info-section</span></dt><dd class="dd-description">
Specify section of Info directory.</dd><dt class="dt-description"><span class="c006">-noheader</span></dt><dd class="dd-description">
Suppress header in generated documentation.</dd><dt class="dt-description"><span class="c006">-noindex</span></dt><dd class="dd-description">
Do not build index for Info files.</dd><dt class="dt-description"><span class="c006">-notrailer</span></dt><dd class="dd-description">
Suppress trailer in generated documentation.
</dd></dl><h4 class="subsubsection" id="sss:ocamldoc-dot"><a class="section-anchor" href="#sss:ocamldoc-dot" aria-hidden="true"></a>Options for generating <span class="c003">dot</span> graphs</h4>
<p>The following options apply in conjunction with the <span class="c003">-dot</span> option:</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">-dot-colors</span> <span class="c009">colors</span></span></dt><dd class="dd-description">
Specify the colors to use in the generated <span class="c003">dot</span> code.
When generating module dependencies, <span class="c003">ocamldoc</span> uses different colors
for modules, depending on the directories in which they reside.
When generating types dependencies, <span class="c003">ocamldoc</span> uses different colors
for types, depending on the modules in which they are defined.
<span class="c009">colors</span> is a list of color names separated by ’<span class="c003">,</span>’, as
in <span class="c003">Red,Blue,Green</span>. The available colors are the ones supported by
the <span class="c003">dot</span> tool.</dd><dt class="dt-description"><span class="c006">-dot-include-all</span></dt><dd class="dd-description">
Include all modules in the <span class="c003">dot</span> output, not only modules given
on the command line or loaded with the <span class="c006">-load</span> option.</dd><dt class="dt-description"><span class="c006">-dot-reduce</span></dt><dd class="dd-description">
Perform a transitive reduction of the dependency graph before
outputting the <span class="c003">dot</span> code. This can be useful if there are
a lot of transitive dependencies that clutter the graph.</dd><dt class="dt-description"><span class="c006">-dot-types</span></dt><dd class="dd-description">
Output <span class="c003">dot</span> code describing the type dependency graph instead of
the module dependency graph.
</dd></dl><h4 class="subsubsection" id="sss:ocamldoc-man"><a class="section-anchor" href="#sss:ocamldoc-man" aria-hidden="true"></a>Options for generating man files</h4>
<p>The following options apply in conjunction with the <span class="c003">-man</span> option:</p><dl class="description"><dt class="dt-description">
<span class="c006">-man-mini</span></dt><dd class="dd-description">
Generate man pages only for modules, module types, classes and class
types, instead of pages for all elements.</dd><dt class="dt-description"><span class="c013"><span class="c003">-man-suffix</span> <span class="c009">suffix</span></span></dt><dd class="dd-description">
Set the suffix used for generated man filenames. Default is ’<span class="c003">3o</span>’,
as in <span class="c003">List.3o</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-man-section</span> <span class="c009">section</span></span></dt><dd class="dd-description">
Set the section number used for generated man filenames. Default is ’<span class="c003">3</span>’.</dd></dl>
<h3 class="subsection" id="ss:ocamldoc-merge"><a class="section-anchor" href="#ss:ocamldoc-merge" aria-hidden="true"></a>16.1.2 Merging of module information</h3>
<p>Information on a module can be extracted either from the <span class="c003">.mli</span> or <span class="c003">.ml</span>
file, or both, depending on the files given on the command line.
When both <span class="c003">.mli</span> and <span class="c003">.ml</span> files are given for the same module,
information extracted from these files is merged according to the
following rules:
</p><ul class="itemize"><li class="li-itemize">
Only elements (values, types, classes, ...) declared in the <span class="c003">.mli</span>
file are kept. In other terms, definitions from the <span class="c003">.ml</span> file that are
not exported in the <span class="c003">.mli</span> file are not documented.
</li><li class="li-itemize">Descriptions of elements and descriptions in @-tags are handled
as follows. If a description for the same element or in the same
@-tag of the same element is present in both files, then the
description of the <span class="c003">.ml</span> file is concatenated to the one in the <span class="c003">.mli</span> file,
if the corresponding <span class="c003">-m</span> flag is given on the command line.
If a description is present in the <span class="c003">.ml</span> file and not in the
<span class="c003">.mli</span> file, the <span class="c003">.ml</span> description is kept.
In either case, all the information given in the <span class="c003">.mli</span> file is kept.
</li></ul>
<h3 class="subsection" id="ss:ocamldoc-rules"><a class="section-anchor" href="#ss:ocamldoc-rules" aria-hidden="true"></a>16.1.3 Coding rules</h3>
<p>
The following rules must be respected in order to avoid name clashes
resulting in cross-reference errors:
</p><ul class="itemize"><li class="li-itemize">
In a module, there must not be two modules, two module types or
a module and a module type with the same name.
In the default HTML generator, modules <span class="c003">ab</span> and <span class="c003">AB</span> will be printed
to the same file on case insensitive file systems.
</li><li class="li-itemize">In a module, there must not be two classes, two class types or
a class and a class type with the same name.
</li><li class="li-itemize">In a module, there must not be two values, two types, or two
exceptions with the same name.
</li><li class="li-itemize">Values defined in tuple, as in <span class="c003">let (x,y,z) = (1,2,3)</span>
are not kept by OCamldoc.
</li><li class="li-itemize">Avoid the following construction:
<div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">open</span> Foo <span class="ocamlcomment">(* which has a module Bar with a value x *)</span>
<span class="ocamlkeyword">module</span> Foo =
<span class="ocamlkeyword">struct</span>
<span class="ocamlkeyword">module</span> Bar =
<span class="ocamlkeyword">struct</span>
<span class="ocamlkeyword">let</span> x = 1
<span class="ocamlkeyword">end</span>
<span class="ocamlkeyword">end</span>
<span class="ocamlkeyword">let</span> dummy = Bar.x</div></div>
</div>
In this case, OCamldoc will associate <span class="c003">Bar.x</span> to the <span class="c003">x</span> of module
<span class="c003">Foo</span> defined just above, instead of to the <span class="c003">Bar.x</span> defined in the
opened module <span class="c003">Foo</span>.
</li></ul>
<h2 class="section" id="s:ocamldoc-comments"><a class="section-anchor" href="#s:ocamldoc-comments" aria-hidden="true"></a>16.2 Syntax of documentation comments</h2>
<p>Comments containing documentation material are called <em>special
comments</em> and are written between <span class="c003">(**</span> and <span class="c003">*)</span>. Special comments
must start exactly with <span class="c003">(**</span>. Comments beginning with <span class="c003">(</span> and more
than two <span class="c003">*</span> are ignored.</p>
<h3 class="subsection" id="ss:ocamldoc-placement"><a class="section-anchor" href="#ss:ocamldoc-placement" aria-hidden="true"></a>16.2.1 Placement of documentation comments</h3>
<p>
OCamldoc can associate comments to some elements of the language
encountered in the source files. The association is made according to
the locations of comments with respect to the language elements. The
locations of comments in <span class="c003">.mli</span> and <span class="c003">.ml</span> files are different.</p>
<h4 class="subsubsection" id="sss:ocamldoc-mli"><a class="section-anchor" href="#sss:ocamldoc-mli" aria-hidden="true"></a>Comments in <span class="c003">.mli</span> files</h4>
<p>
A special comment is associated to an element if it is placed before or
after the element.<br>
A special comment before an element is associated to this element if :
</p><ul class="itemize"><li class="li-itemize">
There is no blank line or another special comment between the special
comment and the element. However, a regular comment can occur between
the special comment and the element.
</li><li class="li-itemize">The special comment is not already associated to the previous element.
</li><li class="li-itemize">The special comment is not the first one of a toplevel module.
</li></ul><p>A special comment after an element is associated to this element if
there is no blank line or comment between the special comment and the
element.</p><p>There are two exceptions: for constructors and record fields in
type definitions, the associated comment can only be placed after the
constructor or field definition, without blank lines or other comments
between them. The special comment for a constructor
with another constructor following must be placed before the ’<span class="c003">|</span>’
character separating the two constructors.</p><p>The following sample interface file <span class="c003">foo.mli</span> illustrates the
placement rules for comments in <span class="c003">.mli</span> files.</p><div class="caml-example signature">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlcomment">(** The first special comment of the file is the comment associated
with the whole module.*)</span>
<span class="ocamlcomment">(** Special comments can be placed between elements and are kept
by the OCamldoc tool, but are not associated to any element.
@-tags in these comments are ignored.*)</span>
<span class="ocamlcomment">(*******************************************************************)</span>
<span class="ocamlcomment">(** Comments like the one above, with more than two asterisks,
are ignored. *)</span>
<span class="ocamlcomment">(** The comment for function f. *)</span>
<span class="ocamlkeyword">val</span> f : int -> int -> int
<span class="ocamlcomment">(** The continuation of the comment for function f. *)</span>
<span class="ocamlcomment">(** Comment for exception My_exception, even with a simple comment
between the special comment and the exception.*)</span>
<span class="ocamlcomment">(* Hello, I'm a simple comment :-) *)</span>
<span class="ocamlkeyword">exception</span> My_exception <span class="ocamlkeyword">of</span> (int -> int) * int
<span class="ocamlcomment">(** Comment for type weather *)</span>
<span class="ocamlkeyword">type</span> weather =
| Rain <span class="ocamlkeyword">of</span> int <span class="ocamlcomment">(** The comment for constructor Rain *)</span>
| Sun <span class="ocamlcomment">(** The comment for constructor Sun *)</span>
<span class="ocamlcomment">(** Comment for type weather2 *)</span>
<span class="ocamlkeyword">type</span> weather2 =
| Rain <span class="ocamlkeyword">of</span> int <span class="ocamlcomment">(** The comment for constructor Rain *)</span>
| Sun <span class="ocamlcomment">(** The comment for constructor Sun *)</span>
<span class="ocamlcomment">(** I can continue the comment for type weather2 here
because there is already a comment associated to the last constructor.*)</span>
<span class="ocamlcomment">(** The comment for type my_record *)</span>
<span class="ocamlkeyword">type</span> my_record = {
foo : int ; <span class="ocamlcomment">(** Comment for field foo *)</span>
bar : string ; <span class="ocamlcomment">(** Comment for field bar *)</span>
}
<span class="ocamlcomment">(** Continuation of comment for type my_record *)</span>
<span class="ocamlcomment">(** Comment for foo *)</span>
<span class="ocamlkeyword">val</span> foo : string
<span class="ocamlcomment">(** This comment is associated to foo and not to bar. *)</span>
<span class="ocamlkeyword">val</span> bar : string
<span class="ocamlcomment">(** This comment is associated to bar. *)</span>
<span class="ocamlcomment">(** The comment for class my_class *)</span>
<span class="ocamlkeyword">class</span> my_class :
<span class="ocamlkeyword">object</span>
<span class="ocamlcomment">(** A comment to describe inheritance from cl *)</span>
<span class="ocamlkeyword">inherit</span> cl
<span class="ocamlcomment">(** The comment for attribute tutu *)</span>
<span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> tutu : string
<span class="ocamlcomment">(** The comment for attribute toto. *)</span>
<span class="ocamlkeyword">val</span> toto : int
<span class="ocamlcomment">(** This comment is not attached to titi since
there is a blank line before titi, but is kept
as a comment in the class. *)</span>
<span class="ocamlkeyword">val</span> titi : string
<span class="ocamlcomment">(** Comment for method toto *)</span>
<span class="ocamlkeyword">method</span> toto : string
<span class="ocamlcomment">(** Comment for method m *)</span>
<span class="ocamlkeyword">method</span> m : float -> int
<span class="ocamlkeyword">end</span>
<span class="ocamlcomment">(** The comment for the class type my_class_type *)</span>
<span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> my_class_type =
<span class="ocamlkeyword">object</span>
<span class="ocamlcomment">(** The comment for variable x. *)</span>
<span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
<span class="ocamlcomment">(** The comment for method m. *)</span>
<span class="ocamlkeyword">method</span> m : int -> int
<span class="ocamlkeyword">end</span>
<span class="ocamlcomment">(** The comment for module Foo *)</span>
<span class="ocamlkeyword">module</span> Foo :
<span class="ocamlkeyword">sig</span>
<span class="ocamlcomment">(** The comment for x *)</span>
<span class="ocamlkeyword">val</span> x : int
<span class="ocamlcomment">(** A special comment that is kept but not associated to any element *)</span>
<span class="ocamlkeyword">end</span>
<span class="ocamlcomment">(** The comment for module type my_module_type. *)</span>
<span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> my_module_type =
<span class="ocamlkeyword">sig</span>
<span class="ocamlcomment">(** The comment for value x. *)</span>
<span class="ocamlkeyword">val</span> x : int
<span class="ocamlcomment">(** The comment for module M. *)</span>
<span class="ocamlkeyword">module</span> M :
<span class="ocamlkeyword">sig</span>
<span class="ocamlcomment">(** The comment for value y. *)</span>
<span class="ocamlkeyword">val</span> y : int
<span class="ocamlcomment">(* ... *)</span>
<span class="ocamlkeyword">end</span>
<span class="ocamlkeyword">end</span></div></div>
</div>
<h4 class="subsubsection" id="sss:ocamldoc-comments-ml"><a class="section-anchor" href="#sss:ocamldoc-comments-ml" aria-hidden="true"></a>Comments in <span class="c003">.ml</span> files</h4>
<p>A special comment is associated to an element if it is placed before
the element and there is no blank line between the comment and the
element. Meanwhile, there can be a simple comment between the special
comment and the element. There are two exceptions, for
constructors and record fields in type definitions, whose associated
comment must be placed after the constructor or field definition,
without blank line between them. The special comment for a constructor
with another constructor following must be placed before the ’<span class="c003">|</span>’
character separating the two constructors.</p><p>The following example of file <span class="c003">toto.ml</span> shows where to place comments
in a <span class="c003">.ml</span> file.</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlcomment">(** The first special comment of the file is the comment associated
to the whole module. *)</span>
<span class="ocamlcomment">(** The comment for function f *)</span>
<span class="ocamlkeyword">let</span> f x y = x + y
<span class="ocamlcomment">(** This comment is not attached to any element since there is another
special comment just before the next element. *)</span>
<span class="ocamlcomment">(** Comment for exception My_exception, even with a simple comment
between the special comment and the exception.*)</span>
<span class="ocamlcomment">(* A simple comment. *)</span>
<span class="ocamlkeyword">exception</span> My_exception <span class="ocamlkeyword">of</span> (int -> int) * int
<span class="ocamlcomment">(** Comment for type weather *)</span>
<span class="ocamlkeyword">type</span> weather =
| Rain <span class="ocamlkeyword">of</span> int <span class="ocamlcomment">(** The comment for constructor Rain *)</span>
| Sun <span class="ocamlcomment">(** The comment for constructor Sun *)</span>
<span class="ocamlcomment">(** The comment for type my_record *)</span>
<span class="ocamlkeyword">type</span> my_record = {
foo : int ; <span class="ocamlcomment">(** Comment for field foo *)</span>
bar : string ; <span class="ocamlcomment">(** Comment for field bar *)</span>
}
<span class="ocamlcomment">(** The comment for class my_class *)</span>
<span class="ocamlkeyword">class</span> my_class =
<span class="ocamlkeyword">object</span>
<span class="ocamlcomment">(** A comment to describe inheritance from cl *)</span>
<span class="ocamlkeyword">inherit</span> cl
<span class="ocamlcomment">(** The comment for the instance variable tutu *)</span>
<span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> tutu = <span class="ocamlstring">"tutu"</span>
<span class="ocamlcomment">(** The comment for toto *)</span>
<span class="ocamlkeyword">val</span> toto = 1
<span class="ocamlkeyword">val</span> titi = <span class="ocamlstring">"titi"</span>
<span class="ocamlcomment">(** Comment for method toto *)</span>
<span class="ocamlkeyword">method</span> toto = tutu ^ <span class="ocamlstring">"!"</span>
<span class="ocamlcomment">(** Comment for method m *)</span>
<span class="ocamlkeyword">method</span> m (f : float) = 1
<span class="ocamlkeyword">end</span>
<span class="ocamlcomment">(** The comment for class type my_class_type *)</span>
<span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> my_class_type =
<span class="ocamlkeyword">object</span>
<span class="ocamlcomment">(** The comment for the instance variable x. *)</span>
<span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
<span class="ocamlcomment">(** The comment for method m. *)</span>
<span class="ocamlkeyword">method</span> m : int -> int
<span class="ocamlkeyword">end</span>
<span class="ocamlcomment">(** The comment for module Foo *)</span>
<span class="ocamlkeyword">module</span> Foo =
<span class="ocamlkeyword">struct</span>
<span class="ocamlcomment">(** The comment for x *)</span>
<span class="ocamlkeyword">let</span> x = 0
<span class="ocamlcomment">(** A special comment in the class, but not associated to any element. *)</span>
<span class="ocamlkeyword">end</span>
<span class="ocamlcomment">(** The comment for module type my_module_type. *)</span>
<span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> my_module_type =
<span class="ocamlkeyword">sig</span>
<span class="ocamlcomment">(* Comment for value x. *)</span>
<span class="ocamlkeyword">val</span> x : int
<span class="ocamlcomment">(* ... *)</span>
<span class="ocamlkeyword">end</span></div></div>
</div>
<h3 class="subsection" id="ss:ocamldoc-stop"><a class="section-anchor" href="#ss:ocamldoc-stop" aria-hidden="true"></a>16.2.2 The Stop special comment</h3>
<p>
The special comment <span class="c003">(**/**)</span> tells OCamldoc to discard
elements placed after this comment, up to the end of the current
class, class type, module or module type, or up to the next stop comment.
For instance:
</p><div class="caml-example signature">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> foo =
<span class="ocamlkeyword">object</span>
<span class="ocamlcomment">(** comment for method m *)</span>
<span class="ocamlkeyword">method</span> m : string
<span class="ocamlcomment">(**/**)</span>
<span class="ocamlcomment">(** This method won't appear in the documentation *)</span>
<span class="ocamlkeyword">method</span> bar : int
<span class="ocamlkeyword">end</span>
<span class="ocamlcomment">(** This value appears in the documentation, since the Stop special comment
in the class does not affect the parent module of the class.*)</span>
<span class="ocamlkeyword">val</span> foo : string
<span class="ocamlcomment">(**/**)</span>
<span class="ocamlcomment">(** The value bar does not appear in the documentation.*)</span>
<span class="ocamlkeyword">val</span> bar : string
<span class="ocamlcomment">(**/**)</span>
<span class="ocamlcomment">(** The type t appears since in the documentation since the previous stop comment
toggled off the "no documentation mode". *)</span>
<span class="ocamlkeyword">type</span> t = string</div></div>
</div><p>The <span class="c006">-no-stop</span> option to <span class="c003">ocamldoc</span> causes the Stop special
comments to be ignored.</p>
<h3 class="subsection" id="ss:ocamldoc-syntax"><a class="section-anchor" href="#ss:ocamldoc-syntax" aria-hidden="true"></a>16.2.3 Syntax of documentation comments</h3>
<p>The inside of documentation comments <span class="c003">(**</span>…<span class="c003">*)</span> consists of
free-form text with optional formatting annotations, followed by
optional <em>tags</em> giving more specific information about parameters,
version, authors, … The tags are distinguished by a leading <span class="c003">@</span>
character. Thus, a documentation comment has the following shape:
</p><pre>(** The comment begins with a description, which is text formatted
according to the rules described in the next section.
The description continues until the first non-escaped '@' character.
@author Mr Smith
@param x description for parameter x
*)
</pre><p>Some elements support only a subset of all @-tags. Tags that are not
relevant to the documented element are simply ignored. For instance,
all tags are ignored when documenting type constructors, record
fields, and class inheritance clauses. Similarly, a <span class="c003">@param</span> tag on a
class instance variable is ignored.</p><p>At last, <span class="c003">(**)</span> is the empty documentation comment.</p>
<h3 class="subsection" id="ss:ocamldoc-formatting"><a class="section-anchor" href="#ss:ocamldoc-formatting" aria-hidden="true"></a>16.2.4 Text formatting</h3>
<p>Here is the BNF grammar for the simple markup language used to format
text descriptions.</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="text"><span class="c010">text</span></a></td><td class="c015">::=</td><td class="c017"> {<a class="syntax" href="#text-element"><span class="c010">text-element</span></a>}<sup>+</sup>
</td></tr>
<tr><td class="c018"> </td></tr>
</table></td></tr>
</table></div><div class="syntaxleft"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="text-element"><span class="c010">text-element</span></a></td><td class="c015">::=</td></tr>
</table></div><table class="c001 cellpading0"><tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{</span> { <span class="c004">0</span> … <span class="c004">9</span> }<sup>+</sup> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">format <a class="syntax" href="#text"><span class="c010">text</span></a> as a section header;
the integer following <span class="c003">{</span> indicates the sectioning level. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{</span> { <span class="c004">0</span> … <span class="c004">9</span> }<sup>+</sup> <span class="c004">:</span> <span class="c010">label</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020"> same, but also associate the name <span class="c010">label</span> to the current point.
This point can be referenced by its fully-qualified label in a
<span class="c003">{!</span> command, just like any other element. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{b</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">set <a class="syntax" href="#text"><span class="c010">text</span></a> in bold. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{i</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">set <a class="syntax" href="#text"><span class="c010">text</span></a> in italic. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{e</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">emphasize <a class="syntax" href="#text"><span class="c010">text</span></a>. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{C</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">center <a class="syntax" href="#text"><span class="c010">text</span></a>. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{L</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">left align <a class="syntax" href="#text"><span class="c010">text</span></a>. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{R</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">right align <a class="syntax" href="#text"><span class="c010">text</span></a>. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{ul</span> <a class="syntax" href="#list"><span class="c010">list</span></a> <span class="c004">}</span> </td><td class="c020">build a list. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{ol</span> <a class="syntax" href="#list"><span class="c010">list</span></a> <span class="c004">}</span> </td><td class="c020">build an enumerated list. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c002"><span class="c003">{{:</span> <span class="c010">string</span> <span class="c003">}</span></span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">put a link to the given address
(given as <span class="c010">string</span>) on the given <a class="syntax" href="#text"><span class="c010">text</span></a>. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c002"><span class="c003">[</span> <span class="c010">string</span> <span class="c003">]</span></span> </td><td class="c020">set the given <span class="c010">string</span> in source code style. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c002"><span class="c003">{[</span> <span class="c010">string</span> <span class="c003">]}</span></span> </td><td class="c020">set the given <span class="c010">string</span> in preformatted
source code style.</td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c002"><span class="c003">{v</span> <span class="c010">string</span> <span class="c003">v}</span></span> </td><td class="c020">set the given <span class="c010">string</span> in verbatim style. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c002"><span class="c003">{%</span> <span class="c010">string</span> <span class="c003">%}</span></span> </td><td class="c020">target-specific content
(L<sup>A</sup>T<sub>E</sub>X code by default, see details
in <a href="#sss%3Aocamldoc-target-specific-syntax">16.2.4.4</a>) </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c002"><span class="c003">{!</span> <span class="c010">string</span> <span class="c003">}</span></span> </td><td class="c020">insert a cross-reference to an element
(see section <a href="#sss%3Aocamldoc-crossref">16.2.4.2</a> for the syntax of cross-references).</td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{!modules:</span> <span class="c010">string</span> <span class="c010">string</span> ... <span class="c004">}</span> </td><td class="c020">insert an index table
for the given module names. Used in HTML only.</td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{!indexlist}</span> </td><td class="c020">insert a table of links to the various indexes
(types, values, modules, ...). Used in HTML only.</td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{^</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">set text in superscript.</td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{_</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">set text in subscript.</td></tr>
<tr><td class="c024">∣ </td><td class="c023"><span class="c010">escaped-string</span></td><td class="c020">typeset the given string as is;
special characters (’<span class="c003">{</span>’, ’<span class="c003">}</span>’, ’<span class="c003">[</span>’, ’<span class="c003">]</span>’ and ’<span class="c003">@</span>’)
must be escaped by a ’<span class="c003">\</span>’</td></tr>
<tr><td class="c024">∣ </td><td class="c023"><span class="c010">blank-line</span></td><td class="c020">force a new line.
</td></tr>
</table><p> <br>
</p>
<h4 class="subsubsection" id="sss:ocamldoc-list"><a class="section-anchor" href="#sss:ocamldoc-list" aria-hidden="true"></a>16.2.4.1 List formatting</h4>
<div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="list"><span class="c010">list</span></a></td><td class="c015">::=</td><td class="c017">
</td></tr>
<tr><td class="c018"> </td><td class="c015">∣</td><td class="c017"> { <span class="c004">{-</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> }<sup>+</sup>
</td></tr>
<tr><td class="c018"> </td><td class="c015">∣</td><td class="c017"> { <span class="c004">{li</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> }<sup>+</sup>
</td></tr>
</table></td></tr>
</table></div><p>A shortcut syntax exists for lists and enumerated lists:
</p><pre>(** Here is a {b list}
- item 1
- item 2
- item 3
The list is ended by the blank line.*)
</pre><p>is equivalent to:
</p><pre>(** Here is a {b list}
{ul {- item 1}
{- item 2}
{- item 3}}
The list is ended by the blank line.*)
</pre><p>
The same shortcut is available for enumerated lists, using ’<span class="c003">+</span>’
instead of ’<span class="c003">-</span>’.
Note that only one list can be defined by this shortcut in nested lists.</p>
<h4 class="subsubsection" id="sss:ocamldoc-crossref"><a class="section-anchor" href="#sss:ocamldoc-crossref" aria-hidden="true"></a>16.2.4.2 Cross-reference formatting</h4>
<p>Cross-references are fully qualified element names, as in the example
<span class="c003">{!Foo.Bar.t}</span>. This is an ambiguous reference as it may designate
a type name, a value name, a class name, etc. It is possible to make
explicit the intended syntactic class, using <span class="c003">{!type:Foo.Bar.t}</span> to
designate a type, and <span class="c003">{!val:Foo.Bar.t}</span> a value of the same name.</p><p>The list of possible syntactic class is as follows:
</p><div class="center">
<table class="c001 cellpading0"><tr><td class="c015"><span class="c003">tag</span></td><td class="c015">syntactic class</td></tr>
<tr><td class="hbar" colspan=2></td></tr>
<tr><td class="c018"><span class="c003">module:</span></td><td class="c017">module </td></tr>
<tr><td class="c018"><span class="c003">modtype:</span></td><td class="c017">module type </td></tr>
<tr><td class="c018"><span class="c003">class:</span></td><td class="c017">class </td></tr>
<tr><td class="c018"><span class="c003">classtype:</span></td><td class="c017">class type </td></tr>
<tr><td class="c018"><span class="c003">val:</span></td><td class="c017">value </td></tr>
<tr><td class="c018"><span class="c003">type:</span></td><td class="c017">type </td></tr>
<tr><td class="c018"><span class="c003">exception:</span></td><td class="c017">exception </td></tr>
<tr><td class="c018"><span class="c003">attribute:</span></td><td class="c017">attribute </td></tr>
<tr><td class="c018"><span class="c003">method:</span></td><td class="c017">class method </td></tr>
<tr><td class="c018"><span class="c003">section:</span></td><td class="c017">ocamldoc section </td></tr>
<tr><td class="c018"><span class="c003">const:</span></td><td class="c017">variant constructor </td></tr>
<tr><td class="c018"><span class="c003">recfield:</span></td><td class="c017">record field
</td></tr>
</table>
</div><p>In the case of variant constructors or record field, the constructor
or field name should be preceded by the name of the correspond type –
to avoid the ambiguity of several types having the same constructor
names. For example, the constructor <span class="c003">Node</span> of the type <span class="c003">tree</span> will be
referenced as <span class="c003">{!tree.Node}</span> or <span class="c003">{!const:tree.Node}</span>, or possibly
<span class="c003">{!Mod1.Mod2.tree.Node}</span> from outside the module.</p>
<h4 class="subsubsection" id="sss:ocamldoc-preamble"><a class="section-anchor" href="#sss:ocamldoc-preamble" aria-hidden="true"></a>16.2.4.3 First sentence</h4>
<p>In the description of a value, type, exception, module, module type, class
or class type, the <em>first sentence</em> is sometimes used in indexes, or
when just a part of the description is needed. The first sentence
is composed of the first characters of the description, until
</p><ul class="itemize"><li class="li-itemize">
the first dot followed by a blank, or
</li><li class="li-itemize">the first blank line
</li></ul><p>
outside of the following text formatting :
<span class="c004">{ul</span> <a class="syntax" href="#list"><span class="c010">list</span></a> <span class="c004">}</span> ,
<span class="c004">{ol</span> <a class="syntax" href="#list"><span class="c010">list</span></a> <span class="c004">}</span> ,
<span class="c002"><span class="c003">[</span> <span class="c010">string</span> <span class="c003">]</span></span> ,
<span class="c002"><span class="c003">{[</span> <span class="c010">string</span> <span class="c003">]}</span></span> ,
<span class="c002"><span class="c003">{v</span> <span class="c010">string</span> <span class="c003">v}</span></span> ,
<span class="c002"><span class="c003">{%</span> <span class="c010">string</span> <span class="c003">%}</span></span> ,
<span class="c002"><span class="c003">{!</span> <span class="c010">string</span> <span class="c003">}</span></span> ,
<span class="c004">{^</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> ,
<span class="c004">{_</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> .</p>
<h4 class="subsubsection" id="sss:ocamldoc-target-specific-syntax"><a class="section-anchor" href="#sss:ocamldoc-target-specific-syntax" aria-hidden="true"></a>16.2.4.4 Target-specific formatting</h4>
<p>The content inside <span class="c003">{%foo: ... %}</span> is target-specific and will only be
interpreted by the backend <span class="c003">foo</span>, and ignored by the others. The
backends of the distribution are <span class="c003">latex</span>, <span class="c003">html</span>, <span class="c003">texi</span> and <span class="c003">man</span>. If
no target is specified (syntax <span class="c003">{% ... %}</span>), <span class="c003">latex</span> is chosen by
default. Custom generators may support their own target prefix.</p>
<h4 class="subsubsection" id="sss:ocamldoc-html-tags"><a class="section-anchor" href="#sss:ocamldoc-html-tags" aria-hidden="true"></a>16.2.4.5 Recognized HTML tags</h4>
<p>
The HTML tags <span class="c003"><b>..</b></span>,
<span class="c003"><code>..</code></span>,
<span class="c003"><i>..</i></span>,
<span class="c003"><ul>..</ul></span>,
<span class="c003"><ol>..</ol></span>,
<span class="c003"><li>..</li></span>,
<span class="c003"><center>..</center></span> and
<span class="c003"><h[0-9]>..</h[0-9]></span> can be used instead of, respectively,
<span class="c004">{b ..}</span> ,
<span class="c004">[..]</span> ,
<span class="c004">{i ..}</span> ,
<span class="c004">{ul ..}</span> ,
<span class="c004">{ol ..}</span> ,
<span class="c004">{li ..}</span> ,
<span class="c004">{C ..}</span> and
<span class="c003">{[0-9] ..}</span>.</p>
<h3 class="subsection" id="ss:ocamldoc-tags"><a class="section-anchor" href="#ss:ocamldoc-tags" aria-hidden="true"></a>16.2.5 Documentation tags (@-tags)</h3>
<h4 class="subsubsection" id="sss:ocamldoc-builtin-tags"><a class="section-anchor" href="#sss:ocamldoc-builtin-tags" aria-hidden="true"></a>Predefined tags</h4>
<p>
The following table gives the list of predefined @-tags, with their
syntax and meaning.<br>
</p><table class="cellpadding1" border=1 style="border-spacing:0;"><tr><td class="c021"> <span class="c004">@author</span> <span class="c010">string</span> </td><td class="c021">The author of the element. One author per
<span class="c003">@author</span> tag.
There may be several <span class="c003">@author</span> tags for the same element. </td></tr>
<tr><td class="c021">
<span class="c004">@deprecated</span> <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">The <a class="syntax" href="#text"><span class="c010">text</span></a> should describe when the element was
deprecated, what to use as a replacement, and possibly the reason
for deprecation. </td></tr>
<tr><td class="c021">
<span class="c004">@param</span> <span class="c010">id</span> <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Associate the given description (<a class="syntax" href="#text"><span class="c010">text</span></a>) to the
given parameter name <span class="c010">id</span>. This tag is used for functions,
methods, classes and functors. </td></tr>
<tr><td class="c021">
<span class="c004">@raise</span> <span class="c010">Exc</span> <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Explain that the element may raise
the exception <span class="c010">Exc</span>. </td></tr>
<tr><td class="c021">
<span class="c004">@return</span> <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Describe the return value and
its possible values. This tag is used for functions
and methods. </td></tr>
<tr><td class="c021">
<span class="c002"><span class="c003">@see</span> <span class="c003"><</span> <span class="c010">URL</span> <span class="c003">></span></span> <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Add a reference to the <span class="c010">URL</span>
with the given <a class="syntax" href="#text"><span class="c010">text</span></a> as comment. </td></tr>
<tr><td class="c021">
<span class="c002"><span class="c003">@see</span> <span class="c003">'</span><span class="c010">filename</span><span class="c003">'</span></span> <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Add a reference to the given file name
(written between single quotes), with the given <a class="syntax" href="#text"><span class="c010">text</span></a> as comment. </td></tr>
<tr><td class="c021">
<span class="c002"><span class="c003">@see</span> <span class="c003">"</span><span class="c010">document-name</span><span class="c003">"</span></span> <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Add a reference to the given
document name (written between double quotes), with the given <a class="syntax" href="#text"><span class="c010">text</span></a>
as comment. </td></tr>
<tr><td class="c021">
<span class="c004">@since</span> <span class="c010">string</span> </td><td class="c021">Indicate when the element was introduced. </td></tr>
<tr><td class="c021">
<span class="c004">@before</span> <span class="c010">version</span> <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Associate the given description (<a class="syntax" href="#text"><span class="c010">text</span></a>)
to the given <span class="c010">version</span> in order to document compatibility issues. </td></tr>
<tr><td class="c021">
<span class="c004">@version</span> <span class="c010">string</span> </td><td class="c021">The version number for the element. </td></tr>
</table>
<h4 class="subsubsection" id="sss:ocamldoc-custom-tags"><a class="section-anchor" href="#sss:ocamldoc-custom-tags" aria-hidden="true"></a>Custom tags</h4>
<p>
You can use custom tags in the documentation comments, but they will
have no effect if the generator used does not handle them. To use a
custom tag, for example <span class="c003">foo</span>, just put <span class="c003">@foo</span> with some text in your
comment, as in:
</p><pre>(** My comment to show you a custom tag.
@foo this is the text argument to the [foo] custom tag.
*)
</pre><p>
To handle custom tags, you need to define a custom generator,
as explained in section <a href="#ss%3Aocamldoc-handling-custom-tags">16.3.2</a>.</p>
<h2 class="section" id="s:ocamldoc-custom-generators"><a class="section-anchor" href="#s:ocamldoc-custom-generators" aria-hidden="true"></a>16.3 Custom generators</h2>
<p>OCamldoc operates in two steps:
</p><ol class="enumerate" type=1><li class="li-enumerate">
analysis of the source files;
</li><li class="li-enumerate">generation of documentation, through a documentation generator,
which is an object of class <span class="c003">Odoc_args.class_generator</span>.
</li></ol><p>
Users can provide their own documentation generator to be used during
step 2 instead of the default generators.
All the information retrieved during the analysis step is available through
the <span class="c003">Odoc_info</span> module, which gives access to all the types and functions
representing the elements found in the given modules, with their associated
description.</p><p>The files you can use to define custom generators are installed in the
<span class="c003">ocamldoc</span> sub-directory of the OCaml standard library.</p>
<h3 class="subsection" id="ss:ocamldoc-generators"><a class="section-anchor" href="#ss:ocamldoc-generators" aria-hidden="true"></a>16.3.1 The generator modules</h3>
<p>
The type of a generator module depends on the kind of generated documentation.
Here is the list of generator module types, with the name of the generator
class in the module :
</p><ul class="itemize"><li class="li-itemize">
for HTML : <span class="c003">Odoc_html.Html_generator</span> (class <span class="c003">html</span>),
</li><li class="li-itemize">for L<sup>A</sup>T<sub>E</sub>X : <span class="c003">Odoc_latex.Latex_generator</span> (class <span class="c003">latex</span>),
</li><li class="li-itemize">for TeXinfo : <span class="c003">Odoc_texi.Texi_generator</span> (class <span class="c003">texi</span>),
</li><li class="li-itemize">for man pages : <span class="c003">Odoc_man.Man_generator</span> (class <span class="c003">man</span>),
</li><li class="li-itemize">for graphviz (dot) : <span class="c003">Odoc_dot.Dot_generator</span> (class <span class="c003">dot</span>),
</li><li class="li-itemize">for other kinds : <span class="c003">Odoc_gen.Base</span> (class <span class="c003">generator</span>).
</li></ul><p>
That is, to define a new generator, one must implement a module with
the expected signature, and with the given generator class, providing
the <span class="c003">generate</span> method as entry point to make the generator generates
documentation for a given list of modules :</p><pre> method generate : Odoc_info.Module.t_module list -> unit
</pre><p>
This method will be called with the list of analysed and possibly
merged <span class="c003">Odoc_info.t_module</span> structures.</p><p>It is recommended to inherit from the current generator of the same
kind as the one you want to define. Doing so, it is possible to
load various custom generators to combine improvements brought by each one.</p><p>This is done using first class modules (see chapter <a href="firstclassmodules.html#s%3Afirst-class-modules">8.5</a>).</p><p>The easiest way to define a custom generator is the following this example,
here extending the current HTML generator. We don’t have to know if this is
the original HTML generator defined in ocamldoc or if it has been extended
already by a previously loaded custom generator :</p><pre>module Generator (G : Odoc_html.Html_generator) =
struct
class html =
object(self)
inherit G.html as html
(* ... *)
method generate module_list =
(* ... *)
()
(* ... *)
end
end;;
let _ = Odoc_args.extend_html_generator (module Generator : Odoc_gen.Html_functor);;
</pre><p>
To know which methods to override and/or which methods are available,
have a look at the different base implementations, depending on the
kind of generator you are extending :
</p><ul class="itemize"><li class="li-itemize">
for HTML : <a href="https://github.com/ocaml/ocaml/blob/4.11/ocamldoc/odoc_html.ml"><span class="c003">odoc_html.ml</span></a>,
</li><li class="li-itemize">for L<sup>A</sup>T<sub>E</sub>X : <a href="https://github.com/ocaml/ocaml/blob/4.11/ocamldoc/odoc_latex.ml"><span class="c003">odoc_latex.ml</span></a>,
</li><li class="li-itemize">for TeXinfo : <a href="https://github.com/ocaml/ocaml/blob/4.11/ocamldoc/odoc_texi.ml"><span class="c003">odoc_texi.ml</span></a>,
</li><li class="li-itemize">for man pages : <a href="https://github.com/ocaml/ocaml/blob/4.11/ocamldoc/odoc_man.ml"><span class="c003">odoc_man.ml</span></a>,
</li><li class="li-itemize">for graphviz (dot) : <a href="https://github.com/ocaml/ocaml/blob/4.11/ocamldoc/odoc_dot.ml"><span class="c003">odoc_dot.ml</span></a>.
</li></ul>
<h3 class="subsection" id="ss:ocamldoc-handling-custom-tags"><a class="section-anchor" href="#ss:ocamldoc-handling-custom-tags" aria-hidden="true"></a>16.3.2 Handling custom tags</h3>
<p>Making a custom generator handle custom tags (see
<a href="#sss%3Aocamldoc-custom-tags">16.2.5</a>) is very simple.</p><h4 class="subsubsection" id="sss:ocamldoc-html-generator"><a class="section-anchor" href="#sss:ocamldoc-html-generator" aria-hidden="true"></a>For HTML</h4>
<p>
Here is how to develop a HTML generator handling your custom tags.</p><p>The class <span class="c003">Odoc_html.Generator.html</span> inherits
from the class <span class="c003">Odoc_html.info</span>, containing a field <span class="c003">tag_functions</span> which is a
list pairs composed of a custom tag (e.g. <span class="c003">"foo"</span>) and a function taking
a <span class="c003">text</span> and returning HTML code (of type <span class="c003">string</span>).
To handle a new tag <span class="c003">bar</span>, extend the current HTML generator
and complete the <span class="c003">tag_functions</span> field:
</p><pre>module Generator (G : Odoc_html.Html_generator) =
struct
class html =
object(self)
inherit G.html
(** Return HTML code for the given text of a bar tag. *)
method html_of_bar t = (* your code here *)
initializer
tag_functions <- ("bar", self#html_of_bar) :: tag_functions
end
end
let _ = Odoc_args.extend_html_generator (module Generator : Odoc_gen.Html_functor);;
</pre><p>
Another method of the class <span class="c003">Odoc_html.info</span> will look for the
function associated to a custom tag and apply it to the text given to
the tag. If no function is associated to a custom tag, then the method
prints a warning message on <span class="c003">stderr</span>.</p>
<h4 class="subsubsection" id="sss:ocamldoc-other-generators"><a class="section-anchor" href="#sss:ocamldoc-other-generators" aria-hidden="true"></a>For other generators</h4>
<p>
You can act the same way for other kinds of generators.</p>
<h2 class="section" id="s:ocamldoc-adding-flags"><a class="section-anchor" href="#s:ocamldoc-adding-flags" aria-hidden="true"></a>16.4 Adding command line options</h2>
<p>
The command line analysis is performed after loading the module containing the
documentation generator, thus allowing command line options to be added to the
list of existing ones. Adding an option can be done with the function
</p><pre> Odoc_args.add_option : string * Arg.spec * string -> unit
</pre><p>Note: Existing command line options can be redefined using
this function.</p>
<h3 class="subsection" id="ss:ocamldoc-compilation-and-usage"><a class="section-anchor" href="#ss:ocamldoc-compilation-and-usage" aria-hidden="true"></a>16.4.1 Compilation and usage</h3>
<h4 class="subsubsection" id="sss:ocamldoc-generator-class"><a class="section-anchor" href="#sss:ocamldoc-generator-class" aria-hidden="true"></a>Defining a custom generator class in one file</h4>
<p>
Let <span class="c003">custom.ml</span> be the file defining a new generator class.
Compilation of <span class="c003">custom.ml</span> can be performed by the following command :
</p><pre>
ocamlc -I +ocamldoc -c custom.ml
</pre><p>
The file <span class="c003">custom.cmo</span> is created and can be used this way :
</p><pre>
ocamldoc -g custom.cmo <span class="c009">other-options source-files</span>
</pre><p>
Options selecting a built-in generator to <span class="c003">ocamldoc</span>, such as
<span class="c003">-html</span>, have no effect if a custom generator of the same kind is provided using
<span class="c003">-g</span>. If the kinds do not match, the selected built-in generator is used and the
custom one is ignored.</p>
<h4 class="subsubsection" id="sss:ocamldoc-modular-generator"><a class="section-anchor" href="#sss:ocamldoc-modular-generator" aria-hidden="true"></a>Defining a custom generator class in several files</h4>
<p>
It is possible to define a generator class in several modules, which
are defined in several files <span class="c009">file</span><sub>1</sub><span class="c003">.ml</span>[<span class="c003">i</span>],
<span class="c009">file</span><sub>2</sub><span class="c003">.ml</span>[<span class="c003">i</span>], ..., <span class="c009">file</span><sub><span class="c009">n</span></sub><span class="c003">.ml</span>[<span class="c003">i</span>]. A <span class="c003">.cma</span>
library file must be created, including all these files.</p><p>The following commands create the <span class="c003">custom.cma</span> file from files
<span class="c009">file</span><sub>1</sub><span class="c003">.ml</span>[<span class="c003">i</span>], ..., <span class="c009">file</span><sub><span class="c009">n</span></sub><span class="c003">.ml</span>[<span class="c003">i</span>] :
</p><pre>
ocamlc -I +ocamldoc -c <span class="c009">file</span><sub>1</sub>.ml[i]
ocamlc -I +ocamldoc -c <span class="c009">file</span><sub>2</sub>.ml[i]
...
ocamlc -I +ocamldoc -c <span class="c009">file</span><sub><span class="c009">n</span></sub>.ml[i]
ocamlc -o custom.cma -a <span class="c009">file</span><sub>1</sub>.cmo <span class="c009">file</span><sub>2</sub>.cmo ... <span class="c009">file</span><sub><span class="c009">n</span></sub>.cmo
</pre><p>
Then, the following command uses <span class="c003">custom.cma</span> as custom generator:
</p><pre>
ocamldoc -g custom.cma <span class="c009">other-options source-files</span>
</pre>
<hr>
<a href="browser.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="index.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="debugger.html"><img src="next_motif.svg" alt="Next"></a>
</body>
</html>
|
