diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bebb6f8..08535c0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -You are welcome to clone this repository and send us back pull requests. +You are welcome to clone this repository, open issues, and send us back pull requests. ## Coding guidelines @@ -8,31 +8,29 @@ You should not: - use more than 100 columns. Less than 80 is even better; - leave trailing whitespace. -Otherwise, try to keep consistent with surrounding code and avoid any super-weird construct -(unless it is really useful, very well documented and maintainable). +Otherwise, try to keep consistent with surrounding code. ## Testing Please verify that your modifications are valid: - Add tests for your work in the `examples` directory; -- Update the expected results found in the `check` directory according to your changes -and common sense (i.e. do not expect a result that is obviously wrong); +- Update the expected results found in the `check` directory according to your changes; - Run `make check` and verify nothing is broken; -- Optionally: compare your old and new results on external projects like OPAM or js_of_ocaml -and check that no errors have been introduced -(some cases may not have their corresponding simplified test written yet). +- Optionally: compare your old and new results on external projects and check + that no error has been introduced + (some cases may not have their corresponding simplified test written yet). ## Misc -Any kind of contribution may be accepted, from fixing typos to adding a new killer feature -with its documentation. +Any kind of contribution may be accepted: fixing typos, fixing bug, new features, documentation. -If you would like to contribute but do not know where to start, you can still check the `TODO.md` +If you would like to contribute but do not know where to start, you can still check the +[opened issues](https://github.com/LexiFi/dead_code_analyzer/issues). Separating style-related, code cleaning and similar changes from functional ones would be nice. -Writing new tests (i.e. not something already existing) for existing features would be very nice. +Writing new tests and improving the documentation would be very nice. Having fun would be the best. diff --git a/README.md b/README.md index a02f486..4715a11 100644 --- a/README.md +++ b/README.md @@ -6,39 +6,50 @@ Dead-code analyzer for OCaml ## Overview -The tool assumes that **.mli** files are compiled with **-keep-locs** and **.ml** -files with **-bin-annot**. Exported values are collected by reading .cmi or .cmt -files (depending on the existence of an explicit .mli interface). -References to such values are collected by reading typed trees from .cmt files +The tool assumes that **.mli** files are compiled with **-keep-locs** (activated +by default) and **.ml** files with **-bin-annot**. +Tracked elements of code are collected by reading **.cmi** and **.cmt** files. +Uses of such elements are collected by reading typed trees from **.cmt** files This tool scans a compiled OCaml project and reports various warnings about suspicious code: - - Exported values never used. - (The declaration can be dropped from the interface, and then from - the implementation if there is no internal use -- which will be reported - by standard OCaml warnings). +- Exported values never used. + The declaration can be dropped from the interface, and then from + the implementation if there is no internal use -- which will be reported + by standard OCaml warnings.\ + For more information, see the [Exported values documentation](docs/exported_values/EXPORTED_VALUES.md). - - Types' fields and constructors never used. (Can be dropped from the type) +- Record fields and variant constructors never used. + They can be dropped from the type definition and then the compiler will report + the affected locations.\ + For more information, see the [Constructors/Record fields documentation](docs/fields_and_constructors/FIELDS_AND_CONSTRUCTORS.md). - - Class fields never used. (Can be dropped from the signature) +- Exported public methods never used. + They can be dropped from the class/object.\ + For more information, see the [Methods documentation](docs/methods/METHODS.md). - - Optional arguments for which either all call sites or none of them - provide a value (other than `None`). (The argument can be made mandatory or dropped.) +- Optional arguments for which either all call sites or none of them + provide a value (other than `None`). + They can be made mandatory or dropped.\ + For more information, see the [Optional arguments documentation](docs/optional_arguments/OPTIONAL_ARGUMENTS.md). - - Other stylistic issues: patterns matching a value of type `unit` - which are not `()` (typically, `_` or a variable); let-binding to unit - `let () = ... in ...` (it's usually better to use sequencing); - let-binding of the form `let x = ... in x` (the binding is useless); - optional argument in an argument's type: `val f: ... -> (... -> ?_:_ -> ...) -> ...` +- Other stylistic issues: + - patterns matching a value of type `unit` which are not `()` (typically, `_` or a variable); + - let-binding to unit `let () = ... in ...` (it's usually better to use sequencing); + - let-binding of the form `let x = ... in x` (the binding is useless); + - optional argument in an argument's type: `val f: ... -> (... -> ?_:_ -> ...) -> ...` -For more information, see [the documentation](docs/USER_DOC.md) + For more information, see the [Coding style documentation](coding_style/CODING_STYLE.md). + +For more information, see the [User documentation](docs/USER_DOC.md) ## Requirements - Currently tested and working on **OCaml 5.2** +- **dune >= 3.20** ## Install @@ -58,38 +69,42 @@ For more information, see [the documentation](docs/USER_DOC.md) `dead_code_analyzer ` -The given paths can be files and directories. -For more information about the usage, use the *-help* option. +The given paths can be files and directories.\ +For more information about the usage, use the `-help` option, or see the +[Usage documentation](docs/USAGE.md). ## Testing -To run the tests use `make check`. -For each subset of the tests a file `.out` is generated, containing the output -of the execution on it. +`make check` runs each subset of the tests sequentially. In case of success, +they all run. Otherwise it stops at the first failing one and prints the diff +between the expected results and the current results. + +To run a specific subset of the tests, run `make -C check `. -To run a subset of the tests call `make -C check `. +To get statistics about passing/failing tests run `make -C check stats`. +For each subset of the tests executed, a file `check/.out` is generated. +It contains the output of running the `dead_code_analyzer` on the tests with +annotations on failures: +- `Should not be detected` for false positives +- `Not detected` for false negatives ## Contribute -You are welcome to clone this repository and send us back pull requests. +You are welcome to clone this repository, open issues and send us back pull requests. Read `CONTRIBUTING.md` at the root of this directory for more information on how to contribute. -## Status - -The project is used internally at LexiFi. - -There has been no official release yet. - - ## Limitations Tracking the optional arguments uses may consume a lot of memory. + Tracking the methods uses may consume a lot of memory. +For more limitations, see each [report section documentation](docs/USERDOC.md#Topics). + ## Copyright diff --git a/TODO.md b/TODO.md deleted file mode 100644 index eb3c3a8..0000000 --- a/TODO.md +++ /dev/null @@ -1,22 +0,0 @@ -# Waiting -- better doc -- handle module types better -- improve optional arguments memory cost -- handle branching (for methods and opt args) -- make check/\*.ml Str-independent -- improve performances - - -# Testing -- \[X\] Test suite -- \[ \] Create tests for all options - - -# Note -- The `UNUSED EXPORTED VALUES` section may have both FN and FP (none known). -- The `UNUSED METHODS` section may have both FN and FP. - It may consume a lot of memory to compute. -- The `UNUSED CONSTRUCTORS/RECORD FIELDS` section may have both FN and FP (none known). -- The `OPTIONAL ARGUMENTS` sections may have both FN and FP. - It may consume a lot of memory to compute. -- The `CODING STYLE` section may have both FN and FP (none known).