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, _) ->