Skip to content

Add doc for exported values #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fantazio merged 16 commits into from
Mar 13, 2026
Merged

Add doc for exported values #63

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
bba0012
[docs][exported_values][1/n] initial documentation
fantazio Feb 9, 2026
a6ed15e
[docs][exported_values][2/n] add multiple comp units example
fantazio Feb 10, 2026
d07c0d4
[docs][exported_values][3/n] add example grouping all the hello world…
fantazio Feb 11, 2026
ff9a91b
[docs][exported_values][4/n] group the hello world examples
fantazio Feb 11, 2026
7ee535c
[docs][exported_values][5/n] add a module example
fantazio Feb 11, 2026
3987df5
[docs][exported_values][6/n] add a functor example
fantazio Feb 14, 2026
e0466fb
[docs][exported_values][7/n] add a function example
fantazio Feb 25, 2026
71d3f00
[docs][exported_values][8/n] add a modtyp example
fantazio Feb 28, 2026
7f31425
[docs][exported_values][9/n] add a modsig example
fantazio Mar 5, 2026
260c084
[docs][exported_values][10/n] add an include example
fantazio Mar 5, 2026
4d963c9
[docs][exported_values][11/n] fix typos and wordings
fantazio Mar 10, 2026
1d0a626
[docs][exported_values][12/n] add compiler warnings section
fantazio Mar 10, 2026
50ed4da
[docs][exported_values][13/n] extract code examples to `examples`
fantazio Mar 10, 2026
b6a2bfc
[docs][exported_values][14/n] rename hello_world examples
fantazio Mar 10, 2026
6d403d6
[docs][exported_values][15/n] extract examples to their own `.md`
fantazio Mar 10, 2026
482ab96
[docs][exported_values][16/n] use snake_case in functor example
fantazio Mar 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions check/classic/classic.exp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,30 @@
.> UNUSED EXPORTED VALUES:
=========================
./examples/docs/exported_values/code_constructs/function/function_lib.mli:7: unused

./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:9: F.internally_used
./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:10: F.unused
./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:14: Internal_param.used_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:15: Internal_param.unused_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:25: Internal_app.internally_used
./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:26: Internal_app.unused

./examples/docs/exported_values/code_constructs/include/include_lib.ml:5: Original.unused
./examples/docs/exported_values/code_constructs/include/include_lib.ml:15: Redefine.unused

./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:6: Original.unused
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:12: Alias_with_sig.used_by_requirement

./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.mli:18: M_redef.internally_used
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.mli:19: M_redef.unused

./examples/docs/exported_values/code_constructs/module/module_lib.mli:5: M.internally_used
./examples/docs/exported_values/code_constructs/module/module_lib.mli:6: M.unused

./examples/docs/exported_values/hello_world/hello_world_with_intf.mli:2: hello
./examples/docs/exported_values/hello_world/hello_world_with_intf.mli:3: goodbye
./examples/docs/exported_values/hello_world/hello_world_with_intf.mli:4: world

./examples/using_dune/preprocessed_lib/preprocessed.mli:1: unused
./examples/using_dune/preprocessed_lib/preprocessed.mli:3: internally_used
./examples/using_dune/preprocessed_lib/preprocessed.mli:38: internally_used_f
Expand Down Expand Up @@ -518,6 +543,32 @@ Nothing else to report in this section

.> CODING STYLE:
===============
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:16: unit pattern used_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:17: unit pattern unused_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:21: unit pattern used_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:22: unit pattern unused_required

./examples/docs/exported_values/code_constructs/include/include_lib.ml:3: unit pattern used_directly
./examples/docs/exported_values/code_constructs/include/include_lib.ml:4: unit pattern used_indirectly
./examples/docs/exported_values/code_constructs/include/include_lib.ml:5: unit pattern unused
./examples/docs/exported_values/code_constructs/include/include_lib.ml:14: unit pattern used_directly
./examples/docs/exported_values/code_constructs/include/include_lib.ml:15: unit pattern unused

./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:3: unit pattern used_directly
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:4: unit pattern used_indirectly
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:5: unit pattern used_by_requirement
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:6: unit pattern unused

./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:11: unit pattern externally_used
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:12: unit pattern internally_used
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:13: unit pattern unused
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:14: unit pattern unused_unexported

./examples/docs/exported_values/code_constructs/module/module_lib.ml:4: unit pattern externally_used
./examples/docs/exported_values/code_constructs/module/module_lib.ml:5: unit pattern internally_used
./examples/docs/exported_values/code_constructs/module/module_lib.ml:6: unit pattern unused
./examples/docs/exported_values/code_constructs/module/module_lib.ml:7: unit pattern unused_unexported

./examples/using_dune/preprocessed_lib/preprocessed.ml:83: let () = ... in ... (=> use sequence)
./examples/using_dune/preprocessed_lib/preprocessed.ml:83: unit pattern unit_binding
./examples/using_dune/preprocessed_lib/preprocessed.ml:84: val f: ... -> (... -> ?_:_ -> ...) -> ...
Expand Down Expand Up @@ -563,3 +614,5 @@ Nothing else to report in this section

Nothing else to report in this section
--------------------------------------------------------------------------------


60 changes: 56 additions & 4 deletions check/classic/classic.ref
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,31 @@
.> UNUSED EXPORTED VALUES:
=========================
./examples/docs/exported_values/code_constructs/function/function_lib.mli:7: unused

./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:9: F.internally_used
./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:10: F.unused
./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:14: Internal_param.used_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:15: Internal_param.unused_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:25: Internal_app.internally_used
./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:26: Internal_app.unused

./examples/docs/exported_values/code_constructs/include/include_lib.ml:5: Original.unused
./examples/docs/exported_values/code_constructs/include/include_lib.ml:5: Reexport.unused: Should not be detected
./examples/docs/exported_values/code_constructs/include/include_lib.ml:15: Redefine.unused

./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:6: Original.unused
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:12: Alias_with_sig.used_by_requirement

./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.mli:18: M_redef.internally_used
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.mli:19: M_redef.unused

./examples/docs/exported_values/code_constructs/module/module_lib.mli:5: M.internally_used
./examples/docs/exported_values/code_constructs/module/module_lib.mli:6: M.unused

./examples/docs/exported_values/hello_world/hello_world_with_intf.mli:2: hello
./examples/docs/exported_values/hello_world/hello_world_with_intf.mli:3: goodbye
./examples/docs/exported_values/hello_world/hello_world_with_intf.mli:4: world

./examples/using_dune/preprocessed_lib/preprocessed.mli:1: unused
./examples/using_dune/preprocessed_lib/preprocessed.mli:3: internally_used
./examples/using_dune/preprocessed_lib/preprocessed.mli:38: internally_used_f
Expand Down Expand Up @@ -518,6 +544,32 @@ Nothing else to report in this section

.> CODING STYLE:
===============
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:16: unit pattern used_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:17: unit pattern unused_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:21: unit pattern used_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:22: unit pattern unused_required

./examples/docs/exported_values/code_constructs/include/include_lib.ml:3: unit pattern used_directly
./examples/docs/exported_values/code_constructs/include/include_lib.ml:4: unit pattern used_indirectly
./examples/docs/exported_values/code_constructs/include/include_lib.ml:5: unit pattern unused
./examples/docs/exported_values/code_constructs/include/include_lib.ml:14: unit pattern used_directly
./examples/docs/exported_values/code_constructs/include/include_lib.ml:15: unit pattern unused

./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:3: unit pattern used_directly
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:4: unit pattern used_indirectly
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:5: unit pattern used_by_requirement
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:6: unit pattern unused

./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:11: unit pattern externally_used
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:12: unit pattern internally_used
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:13: unit pattern unused
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:14: unit pattern unused_unexported

./examples/docs/exported_values/code_constructs/module/module_lib.ml:4: unit pattern externally_used
./examples/docs/exported_values/code_constructs/module/module_lib.ml:5: unit pattern internally_used
./examples/docs/exported_values/code_constructs/module/module_lib.ml:6: unit pattern unused
./examples/docs/exported_values/code_constructs/module/module_lib.ml:7: unit pattern unused_unexported

./examples/using_dune/preprocessed_lib/preprocessed.ml:83: let () = ... in ... (=> use sequence)
./examples/using_dune/preprocessed_lib/preprocessed.ml:83: unit pattern unit_binding
./examples/using_dune/preprocessed_lib/preprocessed.ml:84: val f: ... -> (... -> ?_:_ -> ...) -> ...
Expand Down Expand Up @@ -565,7 +617,7 @@ Nothing else to report in this section
--------------------------------------------------------------------------------


Total: 491
Success: 491
Failed: 0
Ratio: 100.%
Total: 531
Success: 530
Failed: 1
Ratio: 99.8116760829%
43 changes: 43 additions & 0 deletions check/internal/internal.exp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,20 @@
.> UNUSED EXPORTED VALUES:
=========================
./examples/docs/exported_values/code_constructs/function/function_lib.mli:7: unused

./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:10: F.unused
./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:26: Internal_app.unused

./examples/docs/exported_values/code_constructs/include/include_lib.ml:5: Original.unused
./examples/docs/exported_values/code_constructs/include/include_lib.ml:15: Redefine.unused

./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:6: Original.unused
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:12: Alias_with_sig.used_by_requirement

./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.mli:19: M_redef.unused

./examples/docs/exported_values/code_constructs/module/module_lib.mli:6: M.unused

./examples/using_dune/preprocessed_lib/preprocessed.mli:1: unused
./examples/using_dune/preprocessed_lib/preprocessed_no_intf.ml:2: unused

Expand Down Expand Up @@ -483,6 +498,32 @@ Nothing else to report in this section

.> CODING STYLE:
===============
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:16: unit pattern used_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:17: unit pattern unused_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:21: unit pattern used_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:22: unit pattern unused_required

./examples/docs/exported_values/code_constructs/include/include_lib.ml:3: unit pattern used_directly
./examples/docs/exported_values/code_constructs/include/include_lib.ml:4: unit pattern used_indirectly
./examples/docs/exported_values/code_constructs/include/include_lib.ml:5: unit pattern unused
./examples/docs/exported_values/code_constructs/include/include_lib.ml:14: unit pattern used_directly
./examples/docs/exported_values/code_constructs/include/include_lib.ml:15: unit pattern unused

./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:3: unit pattern used_directly
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:4: unit pattern used_indirectly
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:5: unit pattern used_by_requirement
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:6: unit pattern unused

./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:11: unit pattern externally_used
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:12: unit pattern internally_used
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:13: unit pattern unused
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:14: unit pattern unused_unexported

./examples/docs/exported_values/code_constructs/module/module_lib.ml:4: unit pattern externally_used
./examples/docs/exported_values/code_constructs/module/module_lib.ml:5: unit pattern internally_used
./examples/docs/exported_values/code_constructs/module/module_lib.ml:6: unit pattern unused
./examples/docs/exported_values/code_constructs/module/module_lib.ml:7: unit pattern unused_unexported

./examples/using_dune/preprocessed_lib/preprocessed.ml:83: let () = ... in ... (=> use sequence)
./examples/using_dune/preprocessed_lib/preprocessed.ml:83: unit pattern unit_binding
./examples/using_dune/preprocessed_lib/preprocessed.ml:84: val f: ... -> (... -> ?_:_ -> ...) -> ...
Expand Down Expand Up @@ -528,3 +569,5 @@ Nothing else to report in this section

Nothing else to report in this section
--------------------------------------------------------------------------------


50 changes: 46 additions & 4 deletions check/internal/internal.ref
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,21 @@
.> UNUSED EXPORTED VALUES:
=========================
./examples/docs/exported_values/code_constructs/function/function_lib.mli:7: unused

./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:10: F.unused
./examples/docs/exported_values/code_constructs/functor/functor_lib.mli:26: Internal_app.unused

./examples/docs/exported_values/code_constructs/include/include_lib.ml:5: Original.unused
./examples/docs/exported_values/code_constructs/include/include_lib.ml:5: Reexport.unused: Should not be detected
./examples/docs/exported_values/code_constructs/include/include_lib.ml:15: Redefine.unused

./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:6: Original.unused
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:12: Alias_with_sig.used_by_requirement

./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.mli:19: M_redef.unused

./examples/docs/exported_values/code_constructs/module/module_lib.mli:6: M.unused

./examples/using_dune/preprocessed_lib/preprocessed.mli:1: unused
./examples/using_dune/preprocessed_lib/preprocessed_no_intf.ml:2: unused

Expand Down Expand Up @@ -483,6 +499,32 @@ Nothing else to report in this section

.> CODING STYLE:
===============
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:16: unit pattern used_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:17: unit pattern unused_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:21: unit pattern used_required
./examples/docs/exported_values/code_constructs/functor/functor_lib.ml:22: unit pattern unused_required

./examples/docs/exported_values/code_constructs/include/include_lib.ml:3: unit pattern used_directly
./examples/docs/exported_values/code_constructs/include/include_lib.ml:4: unit pattern used_indirectly
./examples/docs/exported_values/code_constructs/include/include_lib.ml:5: unit pattern unused
./examples/docs/exported_values/code_constructs/include/include_lib.ml:14: unit pattern used_directly
./examples/docs/exported_values/code_constructs/include/include_lib.ml:15: unit pattern unused

./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:3: unit pattern used_directly
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:4: unit pattern used_indirectly
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:5: unit pattern used_by_requirement
./examples/docs/exported_values/code_constructs/modsig/modsig_lib.ml:6: unit pattern unused

./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:11: unit pattern externally_used
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:12: unit pattern internally_used
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:13: unit pattern unused
./examples/docs/exported_values/code_constructs/modtyp/modtyp_lib.ml:14: unit pattern unused_unexported

./examples/docs/exported_values/code_constructs/module/module_lib.ml:4: unit pattern externally_used
./examples/docs/exported_values/code_constructs/module/module_lib.ml:5: unit pattern internally_used
./examples/docs/exported_values/code_constructs/module/module_lib.ml:6: unit pattern unused
./examples/docs/exported_values/code_constructs/module/module_lib.ml:7: unit pattern unused_unexported

./examples/using_dune/preprocessed_lib/preprocessed.ml:83: let () = ... in ... (=> use sequence)
./examples/using_dune/preprocessed_lib/preprocessed.ml:83: unit pattern unit_binding
./examples/using_dune/preprocessed_lib/preprocessed.ml:84: val f: ... -> (... -> ?_:_ -> ...) -> ...
Expand Down Expand Up @@ -530,7 +572,7 @@ Nothing else to report in this section
--------------------------------------------------------------------------------


Total: 458
Success: 458
Failed: 0
Ratio: 100.%
Total: 489
Success: 488
Failed: 1
Ratio: 99.7955010225%
17 changes: 9 additions & 8 deletions check/src/path.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,22 +37,23 @@ let normalize path =

(* Relocate a `path` found in a `.got` file as a relative path from the
project's root.
- For files in 'using_make': there is no 'using_make' file or directory in
'<project_root>/examples/using_<dune|make>'. Therefore, taking everything in the
path from the last 'using_make' filename provides the common part for the
relocation. Then, adding an extra './' completes the path as found in the
expected reports
- For files in 'docs' and 'using_make': there is no 'using_make' file or
directory in '<project_root>/examples/*'. Therefore, taking everything in the
path from the last 'docs' or 'using_make' filename provides the common part
for the relocation. Then, adding an extra './iexamples' completes the path as
found in the expected reports
- For files in 'using_dune': the same startegy as for files in 'using_make'
can be applied with the removal of '_build/default' on the way.
Because those directory names are unique, we can actually share the same
logic for both 'using_make' and 'using_dune'. *)
let relocate path =
(* retrieve the subpath starting from the last occurence of
"using_<make|dune>" if it exists, and remove "_build" and "default"
a valid basename if it exists, and remove "_build" and "default"
directories from the path *)
let valid_basenames = ["docs"; "using_make"; "using_dune"] in
let rec extract_subpath acc dirpath =
let basename = Filename.basename dirpath in
if basename = "using_make" || basename = "using_dune" then
if List.mem basename valid_basenames then
basename::acc
else if basename = dirpath (* fixpoint *) then
path::[] (* TODO: error handling *)
Expand All @@ -64,7 +65,7 @@ let relocate path =
in
extract_subpath acc (Filename.dirname dirpath)
in
let relative_path = (* ["using<make|dune>"; <path/to/file>...] *)
let relative_path = (* [valid_basename; <path/to/file>...] *)
extract_subpath [] path
in
String.concat Filename.dir_sep ("."::"examples"::relative_path)
Loading