Skip to content

Commit c702368

Browse files
panglesdpanglesd
committed
Adds explanations and improve occurrence tests
Signed-off-by: Paul-Elliot <peada@free.fr>
1 parent 0d774b6 commit c702368

File tree

5 files changed

+39
-165
lines changed

5 files changed

+39
-165
lines changed

‎test/occurrences/double_wrapped.t/run.t‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
This is what happens when a dune user write a toplevel module.
1+
This test simulates the conditions when a dune user write a toplevel module.
2+
3+
The module C is not exposed in the handwritten toplevel module.
4+
The module A and B are exposed.
5+
The module B depends on both B and C, the module C only depends on A.
26

37
$ odoc compile -c module-a -c src-source root.mld
48

@@ -8,6 +12,9 @@ This is what happens when a dune user write a toplevel module.
812
$ ocamlc -c -open Main__ -o main__B.cmo b.ml -bin-annot -I .
913
$ ocamlc -c -open Main__ main.ml -bin-annot -I .
1014

15+
Passing the count-occurrences flag to odoc compile makes it collect the
16+
occurrences information.
17+
1118
$ odoc compile --count-occurrences -I . main__A.cmt
1219
$ odoc compile --count-occurrences -I . main__C.cmt
1320
$ odoc compile --count-occurrences -I . main__B.cmt
@@ -20,12 +27,15 @@ This is what happens when a dune user write a toplevel module.
2027
$ odoc link -I . main__C.odoc
2128
$ odoc link -I . main__.odoc
2229

23-
Count occurrences
30+
The count occurrences command currently outputs two files: a textual one (using the name given in the command line) and a marshalled hashtable, whose keys are odoc identifiers, and whose values are integers corresponding to the number of uses.
2431

2532
$ odoc count-occurrences -I . -o occurrences.txt
2633

27-
Uses of A and B are counted correctly, since the path is rewritten correctly.
28-
Uses of C are not counted, since the canonical destination does not exists.
34+
$ du -h occurrences.txt.bin
35+
4.0K occurrences.txt.bin
36+
37+
Uses of A and B are counted correctly, with the path rewritten correctly.
38+
Uses of C are not counted, since the canonical destination (generated by dune) does not exists.
2939
Uses of values Y.x and Z.y (in b.ml) are not counted since they come from a "local" module.
3040
Uses of values Main__.C.y and Main__.A.x are not rewritten since we use references instead of paths.
3141

‎test/occurrences/dune‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,5 @@
77

88
(cram
99
(enabled_if
10-
(= %{ocaml_version} 4.14.0))
10+
(= %{ocaml_version} 4.14.1))
1111
(deps %{bin:odoc} %{bin:odoc_print}))

‎test/occurrences/source.t/a.ml‎

Lines changed: 1 addition & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1 @@
1-
type t = string
2-
3-
let x = 2
4-
let y = x + 1
5-
let z a = if x = 1 || true then x + y else 0
6-
7-
module A = struct end
8-
module B = A
9-
10-
module type T = sig end
11-
module type U = T
12-
13-
type ext = ..
14-
type ext += Foo
15-
16-
exception Exn
17-
18-
class cls = object end
19-
class cls' = cls
20-
class type ct = object end
1+
let a = B.b

‎test/occurrences/source.t/b.ml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
let b = 3

‎test/occurrences/source.t/run.t‎

Lines changed: 22 additions & 140 deletions
Original file line numberDiff line numberDiff line change
@@ -1,155 +1,37 @@
1-
Files containing some values:
1+
When both source rendering and occurrence counting are enabled, the occurrences information are used to generate "jump to documentation" links.
22

3-
$ cat a.ml
4-
type t = string
5-
6-
let x = 2
7-
let y = x + 1
8-
let z a = if x = 1 || true then x + y else 0
9-
10-
module A = struct end
11-
module B = A
12-
13-
module type T = sig end
14-
module type U = T
15-
16-
type ext = ..
17-
type ext += Foo
18-
19-
exception Exn
20-
21-
class cls = object end
22-
class cls' = cls
23-
class type ct = object end
3+
This test tests this.
244

25-
Source pages require a parent:
5+
Files containing some values:
266

27-
$ odoc compile -c module-a -c src-source root.mld
7+
$ cat a.ml | head -n 3
8+
let a = B.b
289

29-
Compile the modules:
10+
$ cat b.ml | head -n 3
11+
let b = 3
3012

31-
$ ocamlc -c a.ml -bin-annot
13+
Source pages require a parent:
3214

33-
Compile the pages without --source:
15+
$ odoc compile -c module-a -c module-b -c src-source root.mld
3416

35-
$ odoc compile a.cmt
36-
$ odoc link -I . a.odoc
37-
$ odoc html-generate --indent -o html a.odocl
38-
39-
No source links are generated in the documentation:
17+
Compile the modules:
4018

41-
$ ! grep source_link html/A/index.html -B 2
19+
$ ocamlc -c b.ml -bin-annot
20+
$ ocamlc -c a.ml -I . -bin-annot
4221

43-
Now, compile the pages with the --source option:
22+
Compile the pages with the source and occurrences options
4423

45-
$ printf "a.ml\n" > source_tree.map
24+
$ printf "a.ml\nb.ml\n" > source_tree.map
4625
$ odoc source-tree -I . --parent page-root -o src-source.odoc source_tree.map
47-
48-
$ odoc compile -I . --source-name a.ml --source-parent-file src-source.odoc a.cmt
26+
$ odoc compile --count-occurrences -I . --source-name b.ml --source-parent-file src-source.odoc b.cmt
27+
$ odoc compile --count-occurrences -I . --source-name a.ml --source-parent-file src-source.odoc a.cmt
28+
$ odoc link -I . b.odoc
4929
$ odoc link -I . a.odoc
30+
$ odoc html-generate --source b.ml --indent -o html b.odocl
5031
$ odoc html-generate --source a.ml --indent -o html a.odocl
32+
$ odoc support-files -o html
5133

52-
Source links generated in the documentation:
53-
54-
$ grep source_link html/A/index.html -B 2
55-
<header class="odoc-preamble">
56-
<h1>Module <code><span>A</span></code>
57-
<a href="../root/source/a.ml.html" class="source_link">Source</a>
58-
--
59-
<div class="spec type anchored" id="type-t">
60-
<a href="#type-t" class="anchor"></a>
61-
<a href="../root/source/a.ml.html#def-0" class="source_link">Source</a>
62-
--
63-
<div class="spec value anchored" id="val-x">
64-
<a href="#val-x" class="anchor"></a>
65-
<a href="../root/source/a.ml.html#def-1" class="source_link">Source</a>
66-
--
67-
<div class="spec value anchored" id="val-y">
68-
<a href="#val-y" class="anchor"></a>
69-
<a href="../root/source/a.ml.html#def-2" class="source_link">Source</a>
70-
--
71-
<div class="spec value anchored" id="val-z">
72-
<a href="#val-z" class="anchor"></a>
73-
<a href="../root/source/a.ml.html#def-3" class="source_link">Source</a>
74-
--
75-
<div class="spec module anchored" id="module-A">
76-
<a href="#module-A" class="anchor"></a>
77-
<a href="../root/source/a.ml.html#def-5" class="source_link">Source</a>
78-
--
79-
<div class="spec module anchored" id="module-B">
80-
<a href="#module-B" class="anchor"></a>
81-
<a href="../root/source/a.ml.html#def-5" class="source_link">Source</a>
82-
--
83-
<div class="spec module-type anchored" id="module-type-T">
84-
<a href="#module-type-T" class="anchor"></a>
85-
<a href="../root/source/a.ml.html#def-7" class="source_link">Source</a>
86-
--
87-
<div class="spec module-type anchored" id="module-type-U">
88-
<a href="#module-type-U" class="anchor"></a>
89-
<a href="../root/source/a.ml.html#def-8" class="source_link">Source</a>
90-
--
91-
<div class="spec type anchored" id="type-ext">
92-
<a href="#type-ext" class="anchor"></a>
93-
<a href="../root/source/a.ml.html#def-9" class="source_link">Source</a>
94-
--
95-
<div class="spec type extension anchored" id="extension-decl-Foo">
96-
<a href="#extension-decl-Foo" class="anchor"></a>
97-
<a href="../root/source/a.ml.html#def-10" class="source_link">Source</a>
98-
--
99-
<div class="spec exception anchored" id="exception-Exn">
100-
<a href="#exception-Exn" class="anchor"></a>
101-
<a href="../root/source/a.ml.html#def-11" class="source_link">Source</a>
102-
--
103-
<div class="spec class anchored" id="class-cls">
104-
<a href="#class-cls" class="anchor"></a>
105-
<a href="../root/source/a.ml.html#def-12" class="source_link">Source</a>
106-
--
107-
<div class="spec class anchored" id="class-cls'">
108-
<a href="#class-cls'" class="anchor"></a>
109-
<a href="../root/source/a.ml.html#def-14" class="source_link">Source</a>
110-
--
111-
<div class="spec class-type anchored" id="class-type-ct">
112-
<a href="#class-type-ct" class="anchor"></a>
113-
<a href="../root/source/a.ml.html#def-15" class="source_link">Source</a>
114-
115-
Ids generated in the source code:
34+
The source for a contains a link to the documentation of `B.b`, as it is used in the implementation:
11635

117-
$ cat html/root/source/a.ml.html | tr '> ' '\n\n' | grep '^id'
118-
id="L1"
119-
id="L2"
120-
id="L3"
121-
id="L4"
122-
id="L5"
123-
id="L6"
124-
id="L7"
125-
id="L8"
126-
id="L9"
127-
id="L10"
128-
id="L11"
129-
id="L12"
130-
id="L13"
131-
id="L14"
132-
id="L15"
133-
id="L16"
134-
id="L17"
135-
id="L18"
136-
id="L19"
137-
id="L20"
138-
id="def-0"
139-
id="x_268"
140-
id="def-1"
141-
id="y_269"
142-
id="def-2"
143-
id="z_270"
144-
id="def-3"
145-
id="a_272"
146-
id="def-5"
147-
id="def-6"
148-
id="def-7"
149-
id="def-8"
150-
id="def-9"
151-
id="def-10"
152-
id="def-11"
153-
id="def-12"
154-
id="def-14"
155-
id="def-15"
36+
$ cat html/root/source/a.ml.html | tr '> ' '\n\n' | grep 'href' | grep val-b
37+
href="../../B/index.html#val-b"

0 commit comments

Comments
 (0)