From 50f8e1181d6f5a6e60b2397a44bdd9c7f960f6e2 Mon Sep 17 00:00:00 2001 From: Paul-Elliot Date: Wed, 26 Jul 2023 10:56:31 +0200 Subject: [PATCH] Adds explanations and improve occurrence tests Signed-off-by: Paul-Elliot --- test/occurrences/double_wrapped.t/run.t | 18 ++- test/occurrences/dune | 2 +- test/occurrences/source.t/a.ml | 21 +-- test/occurrences/source.t/b.ml | 1 + test/occurrences/source.t/run.t | 162 ++++-------------------- 5 files changed, 39 insertions(+), 165 deletions(-) create mode 100644 test/occurrences/source.t/b.ml diff --git a/test/occurrences/double_wrapped.t/run.t b/test/occurrences/double_wrapped.t/run.t index aeff8baed5..368f21893c 100644 --- a/test/occurrences/double_wrapped.t/run.t +++ b/test/occurrences/double_wrapped.t/run.t @@ -1,4 +1,8 @@ -This is what happens when a dune user write a toplevel module. +This test simulates the conditions when a dune user write a toplevel module. + +The module C is not exposed in the handwritten toplevel module. +The module A and B are exposed. +The module B depends on both B and C, the module C only depends on A. $ odoc compile -c module-a -c src-source root.mld @@ -8,6 +12,9 @@ This is what happens when a dune user write a toplevel module. $ ocamlc -c -open Main__ -o main__B.cmo b.ml -bin-annot -I . $ ocamlc -c -open Main__ main.ml -bin-annot -I . +Passing the count-occurrences flag to odoc compile makes it collect the +occurrences information. + $ odoc compile --count-occurrences -I . main__A.cmt $ odoc compile --count-occurrences -I . main__C.cmt $ odoc compile --count-occurrences -I . main__B.cmt @@ -20,12 +27,15 @@ This is what happens when a dune user write a toplevel module. $ odoc link -I . main__C.odoc $ odoc link -I . main__.odoc -Count occurrences +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. $ odoc count-occurrences -I . -o occurrences.txt -Uses of A and B are counted correctly, since the path is rewritten correctly. -Uses of C are not counted, since the canonical destination does not exists. + $ du -h occurrences.txt.bin + c865409ce5dd5251f4b5da25551c0dba occurrences.txt.bin + +Uses of A and B are counted correctly, with the path rewritten correctly. +Uses of C are not counted, since the canonical destination (generated by dune) does not exists. Uses of values Y.x and Z.y (in b.ml) are not counted since they come from a "local" module. Uses of values Main__.C.y and Main__.A.x are not rewritten since we use references instead of paths. diff --git a/test/occurrences/dune b/test/occurrences/dune index d407bf69ff..7df8ab388a 100644 --- a/test/occurrences/dune +++ b/test/occurrences/dune @@ -7,5 +7,5 @@ (cram (enabled_if - (= %{ocaml_version} 4.14.0)) + (= %{ocaml_version} 4.14.1)) (deps %{bin:odoc} %{bin:odoc_print})) diff --git a/test/occurrences/source.t/a.ml b/test/occurrences/source.t/a.ml index abfd6af152..e09e5d02a3 100644 --- a/test/occurrences/source.t/a.ml +++ b/test/occurrences/source.t/a.ml @@ -1,20 +1 @@ -type t = string - -let x = 2 -let y = x + 1 -let z a = if x = 1 || true then x + y else 0 - -module A = struct end -module B = A - -module type T = sig end -module type U = T - -type ext = .. -type ext += Foo - -exception Exn - -class cls = object end -class cls' = cls -class type ct = object end +let a = B.b diff --git a/test/occurrences/source.t/b.ml b/test/occurrences/source.t/b.ml new file mode 100644 index 0000000000..56d2d5273c --- /dev/null +++ b/test/occurrences/source.t/b.ml @@ -0,0 +1 @@ +let b = 3 diff --git a/test/occurrences/source.t/run.t b/test/occurrences/source.t/run.t index 14642320be..4f404a005e 100644 --- a/test/occurrences/source.t/run.t +++ b/test/occurrences/source.t/run.t @@ -1,155 +1,37 @@ -Files containing some values: +When both source rendering and occurrence counting are enabled, the occurrences information are used to generate "jump to documentation" links. - $ cat a.ml - type t = string - - let x = 2 - let y = x + 1 - let z a = if x = 1 || true then x + y else 0 - - module A = struct end - module B = A - - module type T = sig end - module type U = T - - type ext = .. - type ext += Foo - - exception Exn - - class cls = object end - class cls' = cls - class type ct = object end +This test tests this. -Source pages require a parent: +Files containing some values: - $ odoc compile -c module-a -c src-source root.mld + $ cat a.ml | head -n 3 + let a = B.b -Compile the modules: + $ cat b.ml | head -n 3 + let b = 3 - $ ocamlc -c a.ml -bin-annot +Source pages require a parent: -Compile the pages without --source: + $ odoc compile -c module-a -c module-b -c src-source root.mld - $ odoc compile a.cmt - $ odoc link -I . a.odoc - $ odoc html-generate --indent -o html a.odocl - -No source links are generated in the documentation: +Compile the modules: - $ ! grep source_link html/A/index.html -B 2 + $ ocamlc -c b.ml -bin-annot + $ ocamlc -c a.ml -I . -bin-annot -Now, compile the pages with the --source option: +Compile the pages with the source and occurrences options - $ printf "a.ml\n" > source_tree.map + $ printf "a.ml\nb.ml\n" > source_tree.map $ odoc source-tree -I . --parent page-root -o src-source.odoc source_tree.map - - $ odoc compile -I . --source-name a.ml --source-parent-file src-source.odoc a.cmt + $ odoc compile --count-occurrences -I . --source-name b.ml --source-parent-file src-source.odoc b.cmt + $ odoc compile --count-occurrences -I . --source-name a.ml --source-parent-file src-source.odoc a.cmt + $ odoc link -I . b.odoc $ odoc link -I . a.odoc + $ odoc html-generate --source b.ml --indent -o html b.odocl $ odoc html-generate --source a.ml --indent -o html a.odocl + $ odoc support-files -o html -Source links generated in the documentation: - - $ grep source_link html/A/index.html -B 2 -
-

Module A - Source - -- -
- - Source - -- -
- - Source - -- -
- - Source - -- -
- - Source - -- -
- - Source - -- -
- - Source - -- -
- - Source - -- -
- - Source - -- -
- - Source - -- -
- - Source - -- -
- - Source - -- -
- - Source - -- -
- - Source - -- -
- - Source - -Ids generated in the source code: +The source for a contains a link to the documentation of `B.b`, as it is used in the implementation: - $ cat html/root/source/a.ml.html | tr '> ' '\n\n' | grep '^id' - id="L1" - id="L2" - id="L3" - id="L4" - id="L5" - id="L6" - id="L7" - id="L8" - id="L9" - id="L10" - id="L11" - id="L12" - id="L13" - id="L14" - id="L15" - id="L16" - id="L17" - id="L18" - id="L19" - id="L20" - id="def-0" - id="x_268" - id="def-1" - id="y_269" - id="def-2" - id="z_270" - id="def-3" - id="a_272" - id="def-5" - id="def-6" - id="def-7" - id="def-8" - id="def-9" - id="def-10" - id="def-11" - id="def-12" - id="def-14" - id="def-15" + $ cat html/root/source/a.ml.html | tr '> ' '\n\n' | grep 'href' | grep val-b + href="../../B/index.html#val-b"