Update the root md files

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.
 
 

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 <options> <path>`
 
-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 `<subset>.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 <subset>`.
 
-To run a subset of the tests call `make -C check <subset>`.
+To get statistics about passing/failing tests run `make -C check stats`.
 
+For each subset of the tests executed, a file `check/<subset>.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