Ensure source files in a cargo project do not contain TODOX issues.
To install:
console
cargo install cargo-todox
To run on a cargo project in the current working directory:
console
cargo todox
This will list all (case insensitive) occurrences of the string TODOX anywhere in any of the project source files
(taken from git ls-files). It will succeed if and only if there are no such occurrences.
Supported command line flags are:
* Run cargo todox DIRECTORY to only check files in a specific directory.
* Run cargo todox --output FILE to redirect the output to a file.
* Run cargo todox --version to report the version number.
* Run cargo todox --help to get a help message listing the options.
Using TODOX allows making temporary changes to the code which must be addressed before checking the code in. This can
for any of several reasons: debugging, getting something quick-and-dirty running, investigating alternatives, or just
noting an issue which must be addressed.
Whatever the reason, using TODOX allows marking the issue and moving on without having to worry about it. Before
completing the work, all such markers need to be removed, either by converting them into a TODO for later work or by
fixing the issue. This is where cargo todox comes in - it emits a nicely formatted list of all the locations of this
marker anywhere in the project, and only exits with a zero status only if no such markers are found. It is therefore
easy to include cargo todox in the pre-commit checks, and/or in CI builds.
This is a generalization of using report_fixme = "Always" in rustfmt, a feature which seems on its way to be
removed. The differences between report_fixme and cargo todox
are:
It looks everywhere in all source files, rather than only in comments in .rs files. This allows using todox as
a part of the name of a variable, inside comments, inside printed debugging messages, inside .toml files, inside
.yaml files, in the README files, etc. In contrast, FIXME is only detected in comments in rust files, which
allows for most, but not all, of the useful cases for such a marker.
It allows for exempting lines by saying ALLOW TODOX (typically in a comment). This allows configuration files to
specify running cargo todox without being reported themselved.
It looks for the (case insensitive) string TODOX, rather than the string FIXME.
cargo-todox is distributed under the GNU General Public License (Version 3.0). See the LICENSE for
details.