diff --git a/check/classic/classic.exp b/check/classic/classic.exp
index 84b5e98c..fa87157e 100644
--- a/check/classic/classic.exp
+++ b/check/classic/classic.exp
@@ -1,5 +1,13 @@
.> UNUSED EXPORTED VALUES:
=========================
+./examples/docs/coding_style/bind/bind.ml:2: v
+
+./examples/docs/coding_style/opt/opt.ml:14: add_index_to_negative
+
+./examples/docs/coding_style/seq/seq.ml:2: compute_answer
+
+./examples/docs/coding_style/unit/unit.ml:2: compute_answer
+
./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
@@ -325,6 +333,8 @@ Nothing else to report in this section
.> OPTIONAL ARGUMENTS: ALWAYS:
=============================
+./examples/docs/coding_style/opt/opt.ml:15: ?index
+
./examples/docs/optional_arguments/code_constructs/external_app/external_app_lib.mli:3: ?max
./examples/docs/optional_arguments/code_constructs/hof/hof_bin.ml:2: ?index
@@ -613,6 +623,17 @@ Nothing else to report in this section
.> CODING STYLE:
===============
+./examples/docs/coding_style/bind/bind.ml:3: let x = ... in x (=> useless binding)
+
+./examples/docs/coding_style/opt/opt.ml:2: val f: ... -> (... -> ?_:_ -> ...) -> ...
+
+./examples/docs/coding_style/seq/seq.ml:3: let () = ... in ... (=> use sequence)
+
+./examples/docs/coding_style/unit/unit.ml:2: unit pattern input
+./examples/docs/coding_style/unit/unit.ml:3: let () = ... in ... (=> use sequence)
+./examples/docs/coding_style/unit/unit.ml:3: unit pattern print
+./examples/docs/coding_style/unit/unit.ml:5: unit pattern r
+
./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
diff --git a/check/classic/classic.ref b/check/classic/classic.ref
index 1b141239..35ae2f3d 100644
--- a/check/classic/classic.ref
+++ b/check/classic/classic.ref
@@ -1,5 +1,13 @@
.> UNUSED EXPORTED VALUES:
=========================
+./examples/docs/coding_style/bind/bind.ml:2: v
+
+./examples/docs/coding_style/opt/opt.ml:14: add_index_to_negative
+
+./examples/docs/coding_style/seq/seq.ml:2: compute_answer
+
+./examples/docs/coding_style/unit/unit.ml:2: compute_answer
+
./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
@@ -330,6 +338,8 @@ Nothing else to report in this section
.> OPTIONAL ARGUMENTS: ALWAYS:
=============================
+./examples/docs/coding_style/opt/opt.ml:15: ?index
+
./examples/docs/optional_arguments/code_constructs/external_app/external_app_lib.mli:3: ?max
./examples/docs/optional_arguments/code_constructs/hof/hof_bin.ml:2: ?index
@@ -618,6 +628,17 @@ Nothing else to report in this section
.> CODING STYLE:
===============
+./examples/docs/coding_style/bind/bind.ml:3: let x = ... in x (=> useless binding)
+
+./examples/docs/coding_style/opt/opt.ml:2: val f: ... -> (... -> ?_:_ -> ...) -> ...
+
+./examples/docs/coding_style/seq/seq.ml:3: let () = ... in ... (=> use sequence)
+
+./examples/docs/coding_style/unit/unit.ml:2: unit pattern input
+./examples/docs/coding_style/unit/unit.ml:3: let () = ... in ... (=> use sequence)
+./examples/docs/coding_style/unit/unit.ml:3: unit pattern print
+./examples/docs/coding_style/unit/unit.ml:5: unit pattern r
+
./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
@@ -698,7 +719,7 @@ Nothing else to report in this section
--------------------------------------------------------------------------------
-Total: 581
-Success: 574
+Total: 593
+Success: 586
Failed: 7
-Ratio: 98.7951807229%
+Ratio: 98.8195615514%
diff --git a/check/internal/internal.exp b/check/internal/internal.exp
index 08398ab7..899c4c9d 100644
--- a/check/internal/internal.exp
+++ b/check/internal/internal.exp
@@ -1,5 +1,13 @@
.> UNUSED EXPORTED VALUES:
=========================
+./examples/docs/coding_style/bind/bind.ml:2: v
+
+./examples/docs/coding_style/opt/opt.ml:14: add_index_to_negative
+
+./examples/docs/coding_style/seq/seq.ml:2: compute_answer
+
+./examples/docs/coding_style/unit/unit.ml:2: compute_answer
+
./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
@@ -277,6 +285,8 @@ Nothing else to report in this section
.> OPTIONAL ARGUMENTS: ALWAYS:
=============================
+./examples/docs/coding_style/opt/opt.ml:15: ?index
+
./examples/docs/optional_arguments/code_constructs/external_app/external_app_lib.mli:3: ?max
./examples/docs/optional_arguments/code_constructs/hof/hof_bin.ml:2: ?index
@@ -565,6 +575,17 @@ Nothing else to report in this section
.> CODING STYLE:
===============
+./examples/docs/coding_style/bind/bind.ml:3: let x = ... in x (=> useless binding)
+
+./examples/docs/coding_style/opt/opt.ml:2: val f: ... -> (... -> ?_:_ -> ...) -> ...
+
+./examples/docs/coding_style/seq/seq.ml:3: let () = ... in ... (=> use sequence)
+
+./examples/docs/coding_style/unit/unit.ml:2: unit pattern input
+./examples/docs/coding_style/unit/unit.ml:3: let () = ... in ... (=> use sequence)
+./examples/docs/coding_style/unit/unit.ml:3: unit pattern print
+./examples/docs/coding_style/unit/unit.ml:5: unit pattern r
+
./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
diff --git a/check/internal/internal.ref b/check/internal/internal.ref
index 9d79c4c8..5c83976b 100644
--- a/check/internal/internal.ref
+++ b/check/internal/internal.ref
@@ -1,5 +1,13 @@
.> UNUSED EXPORTED VALUES:
=========================
+./examples/docs/coding_style/bind/bind.ml:2: v
+
+./examples/docs/coding_style/opt/opt.ml:14: add_index_to_negative
+
+./examples/docs/coding_style/seq/seq.ml:2: compute_answer
+
+./examples/docs/coding_style/unit/unit.ml:2: compute_answer
+
./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
@@ -282,6 +290,8 @@ Nothing else to report in this section
.> OPTIONAL ARGUMENTS: ALWAYS:
=============================
+./examples/docs/coding_style/opt/opt.ml:15: ?index
+
./examples/docs/optional_arguments/code_constructs/external_app/external_app_lib.mli:3: ?max
./examples/docs/optional_arguments/code_constructs/hof/hof_bin.ml:2: ?index
@@ -570,6 +580,17 @@ Nothing else to report in this section
.> CODING STYLE:
===============
+./examples/docs/coding_style/bind/bind.ml:3: let x = ... in x (=> useless binding)
+
+./examples/docs/coding_style/opt/opt.ml:2: val f: ... -> (... -> ?_:_ -> ...) -> ...
+
+./examples/docs/coding_style/seq/seq.ml:3: let () = ... in ... (=> use sequence)
+
+./examples/docs/coding_style/unit/unit.ml:2: unit pattern input
+./examples/docs/coding_style/unit/unit.ml:3: let () = ... in ... (=> use sequence)
+./examples/docs/coding_style/unit/unit.ml:3: unit pattern print
+./examples/docs/coding_style/unit/unit.ml:5: unit pattern r
+
./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
@@ -650,7 +671,7 @@ Nothing else to report in this section
--------------------------------------------------------------------------------
-Total: 537
-Success: 530
+Total: 549
+Success: 542
Failed: 7
-Ratio: 98.696461825%
+Ratio: 98.7249544627%
diff --git a/check/threshold-1/threshold-1.exp b/check/threshold-1/threshold-1.exp
index 6d5d62e1..65c58dc3 100644
--- a/check/threshold-1/threshold-1.exp
+++ b/check/threshold-1/threshold-1.exp
@@ -1,5 +1,13 @@
.> UNUSED EXPORTED VALUES:
=========================
+./examples/docs/coding_style/bind/bind.ml:2: v
+
+./examples/docs/coding_style/opt/opt.ml:14: add_index_to_negative
+
+./examples/docs/coding_style/seq/seq.ml:2: compute_answer
+
+./examples/docs/coding_style/unit/unit.ml:2: compute_answer
+
./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
@@ -108,6 +116,8 @@
.>-> ALMOST UNUSED EXPORTED VALUES: Called 1 time(s):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+./examples/docs/coding_style/opt/opt.ml:2: map_with_index_on_negative
+
./examples/docs/exported_values/code_constructs/function/function_lib.mli:3: memoize
./examples/docs/exported_values/code_constructs/function/function_lib.mli:5: heavy_computation
./examples/docs/exported_values/code_constructs/function/function_lib.mli:9: do_nothing
@@ -732,6 +742,8 @@ Nothing else to report in this section
.> OPTIONAL ARGUMENTS: ALWAYS:
=============================
+./examples/docs/coding_style/opt/opt.ml:15: ?index
+
./examples/docs/optional_arguments/code_constructs/external_app/external_app_lib.mli:3: ?max
./examples/docs/optional_arguments/code_constructs/hof/hof_bin.ml:2: ?index
@@ -1020,6 +1032,17 @@ Nothing else to report in this section
.> CODING STYLE:
===============
+./examples/docs/coding_style/bind/bind.ml:3: let x = ... in x (=> useless binding)
+
+./examples/docs/coding_style/opt/opt.ml:2: val f: ... -> (... -> ?_:_ -> ...) -> ...
+
+./examples/docs/coding_style/seq/seq.ml:3: let () = ... in ... (=> use sequence)
+
+./examples/docs/coding_style/unit/unit.ml:2: unit pattern input
+./examples/docs/coding_style/unit/unit.ml:3: let () = ... in ... (=> use sequence)
+./examples/docs/coding_style/unit/unit.ml:3: unit pattern print
+./examples/docs/coding_style/unit/unit.ml:5: unit pattern r
+
./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
diff --git a/check/threshold-1/threshold-1.ref b/check/threshold-1/threshold-1.ref
index a160bc5d..eb6e1268 100644
--- a/check/threshold-1/threshold-1.ref
+++ b/check/threshold-1/threshold-1.ref
@@ -1,5 +1,13 @@
.> UNUSED EXPORTED VALUES:
=========================
+./examples/docs/coding_style/bind/bind.ml:2: v
+
+./examples/docs/coding_style/opt/opt.ml:14: add_index_to_negative
+
+./examples/docs/coding_style/seq/seq.ml:2: compute_answer
+
+./examples/docs/coding_style/unit/unit.ml:2: compute_answer
+
./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
@@ -113,6 +121,8 @@
.>-> ALMOST UNUSED EXPORTED VALUES: Called 1 time(s):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+./examples/docs/coding_style/opt/opt.ml:2: map_with_index_on_negative
+
./examples/docs/exported_values/code_constructs/function/function_lib.mli:3: memoize
./examples/docs/exported_values/code_constructs/function/function_lib.mli:5: heavy_computation
./examples/docs/exported_values/code_constructs/function/function_lib.mli:9: do_nothing
@@ -736,6 +746,8 @@ Nothing else to report in this section
.> OPTIONAL ARGUMENTS: ALWAYS:
=============================
+./examples/docs/coding_style/opt/opt.ml:15: ?index
+
./examples/docs/optional_arguments/code_constructs/external_app/external_app_lib.mli:3: ?max
./examples/docs/optional_arguments/code_constructs/hof/hof_bin.ml:2: ?index
@@ -1024,6 +1036,17 @@ Nothing else to report in this section
.> CODING STYLE:
===============
+./examples/docs/coding_style/bind/bind.ml:3: let x = ... in x (=> useless binding)
+
+./examples/docs/coding_style/opt/opt.ml:2: val f: ... -> (... -> ?_:_ -> ...) -> ...
+
+./examples/docs/coding_style/seq/seq.ml:3: let () = ... in ... (=> use sequence)
+
+./examples/docs/coding_style/unit/unit.ml:2: unit pattern input
+./examples/docs/coding_style/unit/unit.ml:3: let () = ... in ... (=> use sequence)
+./examples/docs/coding_style/unit/unit.ml:3: unit pattern print
+./examples/docs/coding_style/unit/unit.ml:5: unit pattern r
+
./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
@@ -1104,7 +1127,7 @@ Nothing else to report in this section
--------------------------------------------------------------------------------
-Total: 916
-Success: 908
+Total: 929
+Success: 921
Failed: 8
-Ratio: 99.1266375546%
+Ratio: 99.1388589882%
diff --git a/check/threshold-3-0.5/threshold-3-0.5.exp b/check/threshold-3-0.5/threshold-3-0.5.exp
index 0f4a43b4..93d15ada 100644
--- a/check/threshold-3-0.5/threshold-3-0.5.exp
+++ b/check/threshold-3-0.5/threshold-3-0.5.exp
@@ -1,5 +1,13 @@
.> UNUSED EXPORTED VALUES:
=========================
+./examples/docs/coding_style/bind/bind.ml:2: v
+
+./examples/docs/coding_style/opt/opt.ml:14: add_index_to_negative
+
+./examples/docs/coding_style/seq/seq.ml:2: compute_answer
+
+./examples/docs/coding_style/unit/unit.ml:2: compute_answer
+
./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
@@ -108,6 +116,8 @@
.>-> ALMOST UNUSED EXPORTED VALUES: Called 1 time(s):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+./examples/docs/coding_style/opt/opt.ml:2: map_with_index_on_negative
+
./examples/docs/exported_values/code_constructs/function/function_lib.mli:3: memoize
./examples/docs/exported_values/code_constructs/function/function_lib.mli:5: heavy_computation
./examples/docs/exported_values/code_constructs/function/function_lib.mli:9: do_nothing
@@ -957,6 +967,8 @@ Nothing else to report in this section
.> OPTIONAL ARGUMENTS: ALWAYS:
=============================
+./examples/docs/coding_style/opt/opt.ml:15: ?index
+
./examples/docs/optional_arguments/code_constructs/external_app/external_app_lib.mli:3: ?max
./examples/docs/optional_arguments/code_constructs/hof/hof_bin.ml:2: ?index
@@ -1116,6 +1128,8 @@ Nothing else to report in this section
.>-> OPTIONAL ARGUMENTS: ALMOST ALWAYS: Except 1 time(s):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+./examples/docs/coding_style/opt/opt.ml:2: ?index (1/2 calls)
+
./examples/using_dune/preprocessed_lib/preprocessed.ml:59: ?sometimes (1/2 calls)
./examples/using_dune/preprocessed_lib/preprocessed.ml:64: ?sometimes (1/2 calls)
./examples/using_dune/preprocessed_lib/preprocessed.mli:44: ?sometimes (1/2 calls)
@@ -1341,6 +1355,8 @@ Nothing else to report in this section
.>-> OPTIONAL ARGUMENTS: ALMOST NEVER: Except 1 time(s):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+./examples/docs/coding_style/opt/opt.ml:2: ?index (1/2 calls)
+
./examples/using_dune/preprocessed_lib/preprocessed.ml:59: ?sometimes (1/2 calls)
./examples/using_dune/preprocessed_lib/preprocessed.ml:64: ?sometimes (1/2 calls)
./examples/using_dune/preprocessed_lib/preprocessed.mli:44: ?sometimes (1/2 calls)
@@ -1424,6 +1440,17 @@ Nothing else to report in this section
.> CODING STYLE:
===============
+./examples/docs/coding_style/bind/bind.ml:3: let x = ... in x (=> useless binding)
+
+./examples/docs/coding_style/opt/opt.ml:2: val f: ... -> (... -> ?_:_ -> ...) -> ...
+
+./examples/docs/coding_style/seq/seq.ml:3: let () = ... in ... (=> use sequence)
+
+./examples/docs/coding_style/unit/unit.ml:2: unit pattern input
+./examples/docs/coding_style/unit/unit.ml:3: let () = ... in ... (=> use sequence)
+./examples/docs/coding_style/unit/unit.ml:3: unit pattern print
+./examples/docs/coding_style/unit/unit.ml:5: unit pattern r
+
./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
diff --git a/check/threshold-3-0.5/threshold-3-0.5.ref b/check/threshold-3-0.5/threshold-3-0.5.ref
index 8e6323ad..f3f1da53 100644
--- a/check/threshold-3-0.5/threshold-3-0.5.ref
+++ b/check/threshold-3-0.5/threshold-3-0.5.ref
@@ -1,5 +1,13 @@
.> UNUSED EXPORTED VALUES:
=========================
+./examples/docs/coding_style/bind/bind.ml:2: v
+
+./examples/docs/coding_style/opt/opt.ml:14: add_index_to_negative
+
+./examples/docs/coding_style/seq/seq.ml:2: compute_answer
+
+./examples/docs/coding_style/unit/unit.ml:2: compute_answer
+
./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
@@ -113,6 +121,8 @@
.>-> ALMOST UNUSED EXPORTED VALUES: Called 1 time(s):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+./examples/docs/coding_style/opt/opt.ml:2: map_with_index_on_negative
+
./examples/docs/exported_values/code_constructs/function/function_lib.mli:3: memoize
./examples/docs/exported_values/code_constructs/function/function_lib.mli:5: heavy_computation
./examples/docs/exported_values/code_constructs/function/function_lib.mli:9: do_nothing
@@ -961,6 +971,8 @@ Nothing else to report in this section
.> OPTIONAL ARGUMENTS: ALWAYS:
=============================
+./examples/docs/coding_style/opt/opt.ml:15: ?index
+
./examples/docs/optional_arguments/code_constructs/external_app/external_app_lib.mli:3: ?max
./examples/docs/optional_arguments/code_constructs/hof/hof_bin.ml:2: ?index
@@ -1120,6 +1132,8 @@ Nothing else to report in this section
.>-> OPTIONAL ARGUMENTS: ALMOST ALWAYS: Except 1 time(s):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+./examples/docs/coding_style/opt/opt.ml:2: ?index (1/2 calls)
+
./examples/using_dune/preprocessed_lib/preprocessed.ml:59: ?sometimes (1/2 calls)
./examples/using_dune/preprocessed_lib/preprocessed.ml:64: ?sometimes (1/2 calls)
./examples/using_dune/preprocessed_lib/preprocessed.mli:44: ?sometimes (1/2 calls)
@@ -1345,6 +1359,8 @@ Nothing else to report in this section
.>-> OPTIONAL ARGUMENTS: ALMOST NEVER: Except 1 time(s):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+./examples/docs/coding_style/opt/opt.ml:2: ?index (1/2 calls)
+
./examples/using_dune/preprocessed_lib/preprocessed.ml:59: ?sometimes (1/2 calls)
./examples/using_dune/preprocessed_lib/preprocessed.ml:64: ?sometimes (1/2 calls)
./examples/using_dune/preprocessed_lib/preprocessed.mli:44: ?sometimes (1/2 calls)
@@ -1428,6 +1444,17 @@ Nothing else to report in this section
.> CODING STYLE:
===============
+./examples/docs/coding_style/bind/bind.ml:3: let x = ... in x (=> useless binding)
+
+./examples/docs/coding_style/opt/opt.ml:2: val f: ... -> (... -> ?_:_ -> ...) -> ...
+
+./examples/docs/coding_style/seq/seq.ml:3: let () = ... in ... (=> use sequence)
+
+./examples/docs/coding_style/unit/unit.ml:2: unit pattern input
+./examples/docs/coding_style/unit/unit.ml:3: let () = ... in ... (=> use sequence)
+./examples/docs/coding_style/unit/unit.ml:3: unit pattern print
+./examples/docs/coding_style/unit/unit.ml:5: unit pattern r
+
./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
@@ -1508,7 +1535,7 @@ Nothing else to report in this section
--------------------------------------------------------------------------------
-Total: 1236
-Success: 1228
+Total: 1251
+Success: 1243
Failed: 8
-Ratio: 99.3527508091%
+Ratio: 99.3605115907%
diff --git a/docs/USER_DOC.md b/docs/USER_DOC.md
index 59e43d23..6d69e268 100644
--- a/docs/USER_DOC.md
+++ b/docs/USER_DOC.md
@@ -57,6 +57,7 @@ This documentation is split accross different topics:
- [Methods](methods/METHODS.md) describes the semantics and usage of the "unused methods" report section, and provides examples.
- [Constructors/Record fields](fields_and_constructors/FIELDS_AND_CONSTRUCTORS.md) describes the semantics and usage of the "unused constructors/record fields" report section, and provides examples.
- [Optional arguments](optional_arguments/OPTIONAL_ARGUMENTS.md) describes the semantics and usage of the optional arguments always/never used report sections, and provides examples.
+- [Coding style](coding_style/CODING_STYLE.md) describes the semantics and usage of the "coding style" report section, and provides examples.
## Footnotes
diff --git a/docs/coding_style/CODING_STYLE.md b/docs/coding_style/CODING_STYLE.md
new file mode 100644
index 00000000..e4f58c51
--- /dev/null
+++ b/docs/coding_style/CODING_STYLE.md
@@ -0,0 +1,509 @@
+# Table of contents
+
++ [Coding style](#coding-style)
+ + [Usage](#usage)
+ + [Useless binding](#useless-binding)
+ + [Example](#bind-example)
+ + [Limitation](#bind-limitation)
+ + [Optional arg in arg](#optional-arg-in-arg)
+ + [Example](#opt-example)
+ + [Limitation](#opt-limitation)
+ + [Use sequence](#use-sequence)
+ + [Example](#seq-example)
+ + [Unit pattern](#unit-pattern)
+ + [Example](#unit-example)
+ + [Limitation](#unit-limitation)
+
+# Coding style
+
+This section relates to coding patterns. Although this is not related to dead
+code, the tool has been reporting style issues almost since its conception
+(commit [0adbc0d](https://github.com/LexiFi/dead_code_analyzer/commit/0adbc0d504830a01d64a701572b5e7cb3b29f03e)).
+Tracking stylistic issues comes for "free" during the analysis and can be handy
+when cleaning up a codebase so it was kept as part of the tool.
+
+The analyzer only reports 4 different kinds of stylistic issues :
+- `bind`: useless binding
+- `opt`: parameter of arrow type expecting an optional argument
+- `seq`: binding to unit instead of using sequence
+- `unit`: binding unit to a name
+
+## Usage
+
+Stylistic issues are not reported by default.
+Their reports can be activated by using the `--all` or `-S +all` command line
+arguments.
+They can be deactivated by using the `--nothing` or `-S -all` command line
+arguments.
+Each of the sylistic issue category can be selectively activated/deactivated as
+described in their respective sections.
+For more details about the command line arguments see [the more general Usage
+documentation](../USAGE.md).
+
+The report section looks like:
+```
+.> CODING STYLE:
+===============
+filepath:line: issue
+
+Nothing else to report in this section
+--------------------------------------------------------------------------------
+```
+The report line format is `filepath:line: issue` with `filepath` the absolute
+path to the file where the `issue` lies, `line` the line index in `filepath` at
+which the `issue` is, and `issue` the description of the stylistic issue.
+There can be any number of such lines.
+
+The expected resolution depends on the reported issue category. This is
+described in their respective sections.
+
+## Useless binding
+
+A.k.a `bind`.
+This issue is different from unused variables or unused values (for more
+details, see the [Exported Values](../exported_values/EXPORTED_VALUES.md)
+documentation).
+
+This stylistic issue category can be selectively activated by using the
+`-S +bind` command line argument.
+It can be deactivated by using the `-S -bind` command line argument.
+
+This category targets patterns of the form:
+```OCaml
+let x = ... in x
+```
+I.e. the variable is immediately returned.
+
+The expected resolution is to remove the intermediate binding:
+```Diff
+- let x =
+ ...
+- in x
+```
+
+### Example
+
+The reference files for this example are in the
+[bind](../../examples/docs/coding_style/bind) directory.
+
+The reference takes place in `/tmp/docs/coding_style`, which
+is a copy of the [coding\_style](../../examples/docs/coding_style)
+directory. Reported locations may differ depending on the location of the source
+files.
+
+The compilation command is :
+```
+make -C bind build
+```
+
+The analysis command is :
+```
+make -C bind analyze
+```
+
+The compile + analyze command is :
+```
+make -C bind
+```
+
+Code:
+```OCaml
+(* bind.ml *)
+let v =
+ let interm = 42 in
+ interm
+```
+
+Compile and analyze:
+```
+$ make -C bind
+make: Entering directory '/tmp/docs/coding_style/bind'
+ocamlopt -bin-annot bind.ml
+dead_code_analyzer --nothing -S +bind .
+Scanning files...
+ [DONE]
+
+.> CODING STYLE:
+===============
+/tmp/docs/coding_style/bind/bind.ml:3: let x = ... in x (=> useless binding)
+
+Nothing else to report in this section
+--------------------------------------------------------------------------------
+
+
+make: Leaving directory '/tmp/docs/coding_style/bind'
+```
+
+The analyzer reports a coding style issue in `/tmp/docs/coding_style/bind/bind.ml`
+at line `3`. The reported issue is `let x = ... in x (=> useless binding)`, aka
+a `bind` issue.
+
+The reported location points to `let interm = 42 in`. Removing the binding to
+`interm` and replacing its use by its value (`42`) fixes the issue.
+
+Code:
+```OCaml
+(* bind.ml *)
+let v = 42
+```
+
+### Limitation
+
+`bind` issues are always reported with the same content :
+`let x = ... in x (=> useless binding)`. The name of the variable is not
+adapted to fit the actual name found in code (`interm` in the example above).
+
+
+## Optional arg in arg
+
+A.k.a `opt`.
+
+This stylistic issue category can be selectively activated by using the
+`-S +opt` command line argument.
+It can be deactivated by using the `-S -opt` command line argument.
+
+This category targets functions with types of the form:
+```OCaml
+val f: ... -> (... -> ?_:_ -> ...) -> ...
+```
+I.e. higher-order functions expecting a function with an optional argument.
+
+The expected resolution is to make the optional argument mandatory.
+
+### Example
+
+The reference files for this example are in the
+[opt](../../examples/docs/coding_style/opt) directory.
+
+The reference takes place in `/tmp/docs/coding_style`, which
+is a copy of the [coding\_style](../../examples/docs/coding_style)
+directory. Reported locations may differ depending on the location of the source
+files.
+
+The compilation command is :
+```
+make -C opt build
+```
+
+The analysis command is :
+```
+make -C opt analyze
+```
+
+The compile + analyze command is :
+```
+make -C opt
+```
+
+Code:
+```OCaml
+(* opt.ml *)
+let map_with_index_on_negative (f : ?index:int -> int -> 'a) l =
+ let index = ref 0 in
+ let f' x =
+ let res =
+ if x < 0 then f ~index:(!index) x
+ else f x
+ in
+ incr index;
+ res
+ in
+ List.map f' l
+
+let add_index_to_negative l =
+ let add_index ?(index=0) x = x + index in
+ map_with_index_on_negative add_index l
+```
+
+Compile and analyze:
+```
+$ make -C opt
+make: Entering directory '/tmp/docs/coding_style/opt'
+ocamlopt -bin-annot opt.ml
+dead_code_analyzer --nothing -S +opt .
+Scanning files...
+ [DONE]
+
+.> CODING STYLE:
+===============
+/tmp/docs/coding_style/opt/opt.ml:2: val f: ... -> (... -> ?_:_ -> ...) -> ...
+
+Nothing else to report in this section
+--------------------------------------------------------------------------------
+
+
+make: Leaving directory '/tmp/docs/coding_style/opt'
+```
+
+The analyzer reports a coding style issue in `/tmp/docs/coding_style/opt/opt.ml`
+at line `2`. The reported issue is `val f: ... -> (... -> ?_:_ -> ...) -> ...`,
+aka an `opt` issue.
+
+The reported location points to `let map_with_index_on_negative ...` which
+expects a function as argument (`f`), which itself expects an optional argument (`?index`).
+Making `?index` mandatory, and updating the code accordingly, fixes the issue.
+
+Code:
+```OCaml
+(* opt.ml *)
+let map_with_index_on_negative f l =
+ let index = ref 0 in
+ let f' x =
+ let res =
+ if x < 0 then f ~index:(Some !index) x
+ else f ~index:None x
+ in
+ incr index;
+ res
+ in
+ List.map f' l
+
+let add_index_to_negative l =
+ let add_index ?(index=0) x = x + index in
+ let add_index ~index = add_index ?index in
+ map_with_index_on_negative add_index l
+```
+
+> [!NOTE]
+> We made `~index` madatory but changed its type to an option, and added a
+> redefinition of `add_index` to convert the mandatory argument into the
+> optional one. This is the "easiest" and most re-appliable solution for this
+> issue but not necessarily the best one. Context is key to decide on the
+> refactors that should help resolve the issue.
+> E.g. in this example, a possible refactor would be :
+> ```OCaml
+> (* opt.ml *)
+> let map_with_index f l =
+> let index = ref 0 in
+> let f' x =
+> let res = f ~index:(!index) x in
+> incr index;
+> res
+> in
+> List.map f' l
+>
+> let add_index_to_negative l =
+> let add_index_to_negative ~index x =
+> if x < 0 then x + index
+> else x
+> in
+> map_with_index add_index_to_negative l
+> ```
+
+### Limitation
+
+`opt` issues are always reported with the same content :
+`val f: ... -> (... -> ?_:_ -> ...) -> ...`. The name of the function is not
+adapted to fit the actual name found in code (`map_with_index_on_negative` in
+the example above), and the names of the parameters (`f` and `?index` in the
+example above) are not shown.
+
+## Use sequence
+
+A.k.a `seq`.
+
+This stylistic issue category can be selectively activated by using the
+`-S +seq` command line argument.
+It can be deactivated by using the `-S -seq` command line argument.
+
+This category targets patterns of the form:
+```OCaml
+let () = e1 in e2
+```
+I.e. binding to unit instead of using a sequence.
+
+The expected resolution is to use a sequence instead of the intermediate binding:
+```OCaml
+e1;
+e2
+```
+
+> [!TIP]
+> If you are using this pattern to ensure `e1` is of type `unit`, the compiler
+> will report a warning 10 `non-unit-statement` when using the suggested
+> sequence pattern if `e1` is not `unit`. Alternatively, you may use a type
+> annotation `(e1 : unit)` to enforce it and the compiler will report an error
+> if `e1` is not `unit`.
+
+### Example
+
+The reference files for this example are in the
+[seq](../../examples/docs/coding_style/seq) directory.
+
+The reference takes place in `/tmp/docs/coding_style`, which
+is a copy of the [coding\_style](../../examples/docs/coding_style)
+directory. Reported locations may differ depending on the location of the source
+files.
+
+The compilation command is :
+```
+make -C seq build
+```
+
+The analysis command is :
+```
+make -C seq analyze
+```
+
+The compile + analyze command is :
+```
+make -C seq
+```
+
+Code:
+```OCaml
+(* seq.ml *)
+let compute_answer () =
+ let () = print_endline "Computing answer" in
+ 42
+```
+
+Compile and analyze:
+```
+$ make -C seq
+make: Entering directory '/tmp/docs/coding_style/seq'
+ocamlopt -bin-annot seq.ml
+dead_code_analyzer --nothing -S +seq .
+Scanning files...
+ [DONE]
+
+.> CODING STYLE:
+===============
+/tmp/docs/coding_style/seq/seq.ml:3: let () = ... in ... (=> use sequence)
+
+Nothing else to report in this section
+--------------------------------------------------------------------------------
+
+
+make: Leaving directory '/tmp/docs/coding_style/seq'
+```
+
+The analyzer reports a coding style issue in `/tmp/docs/coding_style/seq/seq.ml`
+at line `3`. The reported issue is `let () = ... in ... (=> use sequence)`, aka
+a `seq` issue.
+
+The reported location points to `let () = print_endline "Computing answer" in`
+which can be replaced by a sequence `print_endline "Computing answer;`
+
+Code:
+```OCaml
+(* seq.ml *)
+let compute_answer () =
+ print_endline "Computing answer";
+ 42
+```
+
+## Unit pattern
+
+A.k.a `unit`.
+
+This stylistic issue category can be selectively activated by using the
+`-S +unit` command line argument.
+It can be deactivated by using the `-S -unit` command line argument.
+
+This category targets patterns giving a name to expressions of type `unit`.
+
+The expected resolution is to use `()` in place of the name.
+
+### Example
+
+The reference files for this example are in the
+[unit](../../examples/docs/coding_style/unit) directory.
+
+The reference takes place in `/tmp/docs/coding_style`, which
+is a copy of the [coding\_style](../../examples/docs/coding_style)
+directory. Reported locations may differ depending on the location of the source
+files.
+
+The compilation command is :
+```
+make -C unit build
+```
+
+The analysis command is :
+```
+make -C unit analyze
+```
+
+The compile + analyze command is :
+```
+make -C unit
+```
+
+Code:
+```OCaml
+(* unit.ml *)
+let compute_answer input =
+ let print = print_endline "Computing answer" in
+ match print with
+ | r when input = print -> 42
+ | _ -> assert false
+```
+
+Compile and analyze:
+```
+$ make -C unit
+make -C unit
+make: Entering directory '/tmp/docs/coding_style/unit'
+ocamlopt -bin-annot unit.ml
+dead_code_analyzer --nothing -S +unit .
+Scanning files...
+ [DONE]
+
+.> CODING STYLE:
+===============
+/tmp/docs/coding_style/unit/unit.ml:2: unit pattern input
+/tmp/docs/coding_style/unit/unit.ml:3: unit pattern print
+/tmp/docs/coding_style/unit/unit.ml:5: unit pattern r
+
+Nothing else to report in this section
+--------------------------------------------------------------------------------
+
+
+make: Leaving directory '/tmp/docs/coding_style/unit'
+```
+
+The analyzer reports 3 coding style issues in `/tmp/docs/coding_style/unit/unit.ml`.
+They all have the form `unit pattern `.
+The names listed (`input`, `print`, `r`) are the values of type `unit`.
+
+> [!TIP]
+> Using the `--underscore` command line argument of the `dead_code_analyzer`
+> will trigger the reports for values named `_` or with names prefixed by `_`.
+
+Fixing the reports is done by replacing the reported values by `()`.
+
+Code:
+```OCaml
+(* unit.ml *)
+let compute_answer () =
+ let () = print_endline "Computing answer" in
+ match () with
+ | () when () = () -> 42
+ | _ -> assert false
+```
+
+Now this code can be further simplified by removing the useless pattern matching.
+
+Code:
+```OCaml
+(* unit.ml *)
+let compute_answer () =
+ let () = print_endline "Computing answer" in
+ 42
+```
+
+This can be further improved as detailed in the above
+[Use sequence example](#seq-example). To trigger the `seq` reports, add `+seq`
+to the `-S +unit` command line argument in the `Makefile` :
+```Diff
+analyze:
+- dead_code_analyzer --nothing -S +unit .
++ dead_code_analyzer --nothing -S +unit+seq .
+```
+
+### Limitation
+
+In some cases, the analyzer may report `!!pattern!!` instead of the actual
+pattern of type `unit`. This happens for patterns that are more complex
+than names.
diff --git a/examples/docs/Makefile b/examples/docs/Makefile
index 0405a9b2..87e4dab0 100644
--- a/examples/docs/Makefile
+++ b/examples/docs/Makefile
@@ -7,6 +7,7 @@ build:
make -C methods
make -C fields_and_constructors
make -C optional_arguments
+ make -C coding_style
clean:
rm -f *~ *.cm* *.o *.obj
@@ -14,4 +15,5 @@ clean:
make -C methods clean
make -C fields_and_constructors clean
make -C optional_arguments clean
+ make -C coding_style clean
diff --git a/examples/docs/coding_style/Makefile b/examples/docs/coding_style/Makefile
new file mode 100644
index 00000000..55a9ef4c
--- /dev/null
+++ b/examples/docs/coding_style/Makefile
@@ -0,0 +1,17 @@
+.PHONY: clean build
+
+all: build
+
+build:
+ make -C bind build
+ make -C opt build
+ make -C seq build
+ make -C unit build
+
+clean:
+ rm -f *~ *.cm* *.o *.obj
+ make -C bind clean
+ make -C opt clean
+ make -C seq clean
+ make -C unit clean
+
diff --git a/examples/docs/coding_style/bind/Makefile b/examples/docs/coding_style/bind/Makefile
new file mode 100644
index 00000000..6a6a7932
--- /dev/null
+++ b/examples/docs/coding_style/bind/Makefile
@@ -0,0 +1,12 @@
+SRC:=bind.ml
+
+all: build analyze
+
+build:
+ ocamlopt -bin-annot ${SRC}
+
+analyze:
+ dead_code_analyzer --nothing -S +bind .
+
+clean:
+ rm -f *.cm* *.o a.out
diff --git a/examples/docs/coding_style/bind/bind.ml b/examples/docs/coding_style/bind/bind.ml
new file mode 100644
index 00000000..7c84adb0
--- /dev/null
+++ b/examples/docs/coding_style/bind/bind.ml
@@ -0,0 +1,4 @@
+(* bind.ml *)
+let v =
+ let interm = 42 in
+ interm
diff --git a/examples/docs/coding_style/opt/Makefile b/examples/docs/coding_style/opt/Makefile
new file mode 100644
index 00000000..d2b4f6c8
--- /dev/null
+++ b/examples/docs/coding_style/opt/Makefile
@@ -0,0 +1,12 @@
+SRC:=opt.ml
+
+all: build analyze
+
+build:
+ ocamlopt -bin-annot ${SRC}
+
+analyze:
+ dead_code_analyzer --nothing -S +opt .
+
+clean:
+ rm -f *.cm* *.o a.out
diff --git a/examples/docs/coding_style/opt/opt.ml b/examples/docs/coding_style/opt/opt.ml
new file mode 100644
index 00000000..f40883cf
--- /dev/null
+++ b/examples/docs/coding_style/opt/opt.ml
@@ -0,0 +1,16 @@
+(* opt.ml *)
+let map_with_index_on_negative (f : ?index:int -> int -> 'a) l =
+ let index = ref 0 in
+ let f' x =
+ let res =
+ if x < 0 then f ~index:(!index) x
+ else f x
+ in
+ incr index;
+ res
+ in
+ List.map f' l
+
+let add_index_to_negative l =
+ let add_index ?(index=0) x = x + index in
+ map_with_index_on_negative add_index l
diff --git a/examples/docs/coding_style/seq/Makefile b/examples/docs/coding_style/seq/Makefile
new file mode 100644
index 00000000..756b3313
--- /dev/null
+++ b/examples/docs/coding_style/seq/Makefile
@@ -0,0 +1,12 @@
+SRC:=seq.ml
+
+all: build analyze
+
+build:
+ ocamlopt -bin-annot ${SRC}
+
+analyze:
+ dead_code_analyzer --nothing -S +seq .
+
+clean:
+ rm -f *.cm* *.o a.out
diff --git a/examples/docs/coding_style/seq/seq.ml b/examples/docs/coding_style/seq/seq.ml
new file mode 100644
index 00000000..8db329bf
--- /dev/null
+++ b/examples/docs/coding_style/seq/seq.ml
@@ -0,0 +1,4 @@
+(* seq.ml *)
+let compute_answer () =
+ let () = print_endline "Computing answer" in
+ 42
diff --git a/examples/docs/coding_style/unit/Makefile b/examples/docs/coding_style/unit/Makefile
new file mode 100644
index 00000000..f3c34a78
--- /dev/null
+++ b/examples/docs/coding_style/unit/Makefile
@@ -0,0 +1,12 @@
+SRC:=unit.ml
+
+all: build analyze
+
+build:
+ ocamlopt -bin-annot ${SRC}
+
+analyze:
+ dead_code_analyzer --nothing -S +unit .
+
+clean:
+ rm -f *.cm* *.o a.out
diff --git a/examples/docs/coding_style/unit/unit.ml b/examples/docs/coding_style/unit/unit.ml
new file mode 100644
index 00000000..160a73f6
--- /dev/null
+++ b/examples/docs/coding_style/unit/unit.ml
@@ -0,0 +1,6 @@
+(* unit.ml *)
+let compute_answer input =
+ let print = print_endline "Computing answer" in
+ match print with
+ | r when input = print -> 42
+ | _ -> assert false
diff --git a/src/deadCode.ml b/src/deadCode.ml
index a05a491b..faaf0fa4 100644
--- a/src/deadCode.ml
+++ b/src/deadCode.ml
@@ -228,10 +228,10 @@ let pat: type k. Tast_mapper.mapper -> Tast_mapper.mapper -> k general_pattern -
| Tpat_any -> if state.config.underscore then u "_"
| Tpat_value tpat_arg ->
begin match (tpat_arg :> value general_pattern) with
- | {pat_desc=Tpat_construct _; _} -> ()
- | _ -> u "other"
+ | {pat_desc=(Tpat_construct _ | Tpat_var _ | Tpat_any); _} -> ()
+ | _ -> u "!!pattern!!"
end
- | _ -> u ""
+ | _ -> u "!!pattern!!"
end;
begin match p.pat_desc with
| Tpat_record (l, _) ->