[docs][exported_values] document limitations

fantazio · fantazio · commit 94ae41753dc3 · 2026-03-16T15:15:56.000+01:00
As for the examples, code presented in the limitations is added to the
testsuite.
diff --git a/check/classic/classic.exp b/check/classic/classic.exp
@@ -569,6 +569,8 @@ Nothing else to report in this section
 ./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/docs/exported_values/limitations/sigincl/sigincl_lib.ml:9: unit pattern x
+
 ./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: ... -> (... -> ?_:_ -> ...) -> ...
diff --git a/check/classic/classic.ref b/check/classic/classic.ref
@@ -25,6 +25,7 @@
 ./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/docs/exported_values/limitations/sigincl/sigincl_lib.mli:10: I.x: Should not be detected
 ./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
@@ -569,6 +570,8 @@ Nothing else to report in this section
 ./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/docs/exported_values/limitations/sigincl/sigincl_lib.ml:9: unit pattern x
+
 ./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: ... -> (... -> ?_:_ -> ...) -> ...
@@ -616,7 +619,7 @@ Nothing else to report in this section
 --------------------------------------------------------------------------------
 
 
-Total: 530
-Success: 530
-Failed: 0
-Ratio: 100.%
+Total: 532
+Success: 531
+Failed: 1
+Ratio: 99.8120300752%
diff --git a/check/internal/internal.exp b/check/internal/internal.exp
@@ -524,6 +524,8 @@ Nothing else to report in this section
 ./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/docs/exported_values/limitations/sigincl/sigincl_lib.ml:9: unit pattern x
+
 ./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: ... -> (... -> ?_:_ -> ...) -> ...
diff --git a/check/internal/internal.ref b/check/internal/internal.ref
@@ -15,6 +15,7 @@
 
 ./examples/docs/exported_values/code_constructs/module/module_lib.mli:6: M.unused
 
+./examples/docs/exported_values/limitations/sigincl/sigincl_lib.mli:10: I.x: Should not be detected
 ./examples/using_dune/preprocessed_lib/preprocessed.mli:1: unused
 ./examples/using_dune/preprocessed_lib/preprocessed_no_intf.ml:2: unused
 
@@ -524,6 +525,8 @@ Nothing else to report in this section
 ./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/docs/exported_values/limitations/sigincl/sigincl_lib.ml:9: unit pattern x
+
 ./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: ... -> (... -> ?_:_ -> ...) -> ...
@@ -571,7 +574,7 @@ Nothing else to report in this section
 --------------------------------------------------------------------------------
 
 
-Total: 488
-Success: 488
-Failed: 0
-Ratio: 100.%
+Total: 490
+Success: 489
+Failed: 1
+Ratio: 99.7959183673%
diff --git a/check/threshold-1/threshold-1.exp b/check/threshold-1/threshold-1.exp
@@ -901,6 +901,8 @@ Nothing else to report in this section
 ./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/docs/exported_values/limitations/sigincl/sigincl_lib.ml:9: unit pattern x
+
 ./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: ... -> (... -> ?_:_ -> ...) -> ...
diff --git a/check/threshold-1/threshold-1.ref b/check/threshold-1/threshold-1.ref
@@ -15,6 +15,7 @@
 
 ./examples/docs/exported_values/code_constructs/module/module_lib.mli:6: M.unused
 
+./examples/docs/exported_values/limitations/sigincl/sigincl_lib.mli:10: I.x: Should not be detected
 ./examples/using_dune/preprocessed_lib/preprocessed.mli:1: unused
 ./examples/using_dune/preprocessed_lib/preprocessed_no_intf.ml:2: unused
 
@@ -901,6 +902,8 @@ Nothing else to report in this section
 ./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/docs/exported_values/limitations/sigincl/sigincl_lib.ml:9: unit pattern x
+
 ./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: ... -> (... -> ?_:_ -> ...) -> ...
@@ -948,7 +951,7 @@ Nothing else to report in this section
 --------------------------------------------------------------------------------
 
 
-Total: 819
-Success: 819
-Failed: 0
-Ratio: 100.%
+Total: 821
+Success: 820
+Failed: 1
+Ratio: 99.8781973203%
diff --git a/check/threshold-3-0.5/threshold-3-0.5.exp b/check/threshold-3-0.5/threshold-3-0.5.exp
@@ -1290,6 +1290,8 @@ Nothing else to report in this section
 ./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/docs/exported_values/limitations/sigincl/sigincl_lib.ml:9: unit pattern x
+
 ./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: ... -> (... -> ?_:_ -> ...) -> ...
diff --git a/check/threshold-3-0.5/threshold-3-0.5.ref b/check/threshold-3-0.5/threshold-3-0.5.ref
@@ -15,6 +15,7 @@
 
 ./examples/docs/exported_values/code_constructs/module/module_lib.mli:6: M.unused
 
+./examples/docs/exported_values/limitations/sigincl/sigincl_lib.mli:10: I.x: Should not be detected
 ./examples/using_dune/preprocessed_lib/preprocessed.mli:1: unused
 ./examples/using_dune/preprocessed_lib/preprocessed_no_intf.ml:2: unused
 
@@ -1290,6 +1291,8 @@ Nothing else to report in this section
 ./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/docs/exported_values/limitations/sigincl/sigincl_lib.ml:9: unit pattern x
+
 ./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: ... -> (... -> ?_:_ -> ...) -> ...
@@ -1337,7 +1340,7 @@ Nothing else to report in this section
 --------------------------------------------------------------------------------
 
 
-Total: 1131
-Success: 1131
-Failed: 0
-Ratio: 100.%
+Total: 1133
+Success: 1132
+Failed: 1
+Ratio: 99.9117387467%
diff --git a/docs/exported_values/EXPORTED_VALUES.md b/docs/exported_values/EXPORTED_VALUES.md
@@ -8,6 +8,7 @@
         + [Warning 32: unused-value-declaration](#warning-32-unused-value-declaration)
     + [Usage](#usage)
 + [Examples](#examples)
++ [Limitations](#limitations)
 
 # Exported Values
 
@@ -212,3 +213,106 @@ Warning 26 [unused-var]: unused variable y.
     - [Module type](./code_constructs/MODTYP.md)
     - [Module signature](./code_constructs/MODSIG.md)
     - [Include](./code_constructs/INCLUDE.md)
+
+# Limitations
+
+## Module type
+
+Related issue :
+[issue #50](https://github.com/LexiFi/dead_code_analyzer/issues/50).
+
+As explained in the [Module type](./code_constructs/MODTYP.md) example, the
+analyzer is currently restrcited to not reporting values declared in module
+types. This means that any unused value defined by a module with a module type
+as signature, even with constraints or substitutions, will not be reported.
+
+A future improvement would be to report unused exported values declared in
+module types by considering all the values defined in modules of such types as
+instances of the values in the module types.
+
+## Include module type with substitution
+
+Related issue :
+[issue #64](https://github.com/LexiFi/dead_code_analyzer/issues/64).
+
+According to the above limitation on values in module types, values included
+from a module type should not be reported. Even more so according to the
+semantics described in the [Include](./code_constructs/INCLUDE.md) example.
+This is the case unless there is a substitution on the module type.
+
+### Example
+
+The reference files for this example are in the
+[sigincl](../../../examples/docs/exported_values/limitations/sigincl) directory.
+
+The reference takes place in `/tmp/docs/exported_values/limitations`, which
+is a copy of the [limitations](../../../examples/docs/exported_values/limitations)
+directory. Reported locations may differ depending on the location of the source
+files.
+
+The compilation command is :
+```
+make -C sigincl build
+```
+
+The analysis command is :
+```
+make -C sigincl analyze
+```
+
+The compile + analyze command is :
+```
+make -C sigincl
+```
+
+Code:
+```OCaml
+(* sigincl_lib.mli *)
+module type T = sig
+  type t
+  val x : t
+end
+
+module M : T
+
+module I : sig
+  include T with type t := unit
+end
+```
+```OCaml
+(* sigincl_lib.ml *)
+module type T = sig
+  type t
+  val x : t
+end
+
+module M = struct
+  type t = unit
+  let x = ()
+end
+
+module I = M
+```
+
+Compile and analyze:
+```
+$ make -C sigincl
+make: Entering directory '/tmp/limitations/sigincl'
+ocamlopt -bin-annot sigincl_lib.mli sigincl_lib.ml
+dead_code_analyzer --nothing -E all .
+Scanning files...
+ [DONE]
+
+.> UNUSED EXPORTED VALUES:
+=========================
+/tmp/limitations/sigincl/sigincl_lib.mli:10: I.x
+
+Nothing else to report in this section
+--------------------------------------------------------------------------------
+
+
+make: Leaving directory '/tmp/limitations/sigincl'
+```
+
+The analyzer reports `I.x` at the line where `T` is included although it is
+actually declared in `T`.
diff --git a/examples/docs/exported_values/Makefile b/examples/docs/exported_values/Makefile
@@ -5,9 +5,11 @@ all: build
 build:
 	make -C hello_world
 	make -C code_constructs
+	make -C limitations
 
 clean:
 	rm -f *~ *.cm* *.o *.obj
 	make -C hello_world clean
 	make -C code_constructs clean
+	make -C limitations clean
 
diff --git a/examples/docs/exported_values/limitations/Makefile b/examples/docs/exported_values/limitations/Makefile
@@ -0,0 +1,11 @@
+.PHONY: clean build
+
+all: build
+
+build:
+	make -C sigincl build
+
+clean:
+	rm -f *~ *.cm* *.o *.obj
+	make -C sigincl clean
+
diff --git a/examples/docs/exported_values/limitations/sigincl/Makefile b/examples/docs/exported_values/limitations/sigincl/Makefile
@@ -0,0 +1,12 @@
+SRC:=sigincl_lib.mli sigincl_lib.ml
+
+all: build analyze
+
+build:
+	ocamlopt -bin-annot ${SRC}
+
+analyze:
+	dead_code_analyzer --nothing -E all .
+
+clean:
+	rm -f *.cm* *.o a.out
diff --git a/examples/docs/exported_values/limitations/sigincl/sigincl_lib.ml b/examples/docs/exported_values/limitations/sigincl/sigincl_lib.ml
@@ -0,0 +1,12 @@
+(* sigincl_lib.ml *)
+module type T = sig
+  type t
+  val x : t
+end
+
+module M = struct
+  type t = unit
+  let x = ()
+end
+
+module I = M
diff --git a/examples/docs/exported_values/limitations/sigincl/sigincl_lib.mli b/examples/docs/exported_values/limitations/sigincl/sigincl_lib.mli
@@ -0,0 +1,11 @@
+(* sigincl_lib.mli *)
+module type T = sig
+  type t
+  val x : t
+end
+
+module M : T
+
+module I : sig
+  include T with type t := unit
+end
