-
-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
v1.7.0 (NuGet) - add readme & DevDependency
- Loading branch information
Showing
3 changed files
with
126 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,106 @@ | ||
| # Warn about TODOs | ||
|
|
||
| Create warnings (or errors) based on comments that indicate work is not complete. | ||
| The goal is to prevent accidentally committing code that is not ready. | ||
|
|
||
| Works for single-line, multi-line, and documentation comments in both VB.Net and C#. | ||
|
|
||
| ## Configuration | ||
|
|
||
| The default behavior is to create a warning about any comment line that starts with `TODO`. | ||
|
|
||
| ### Simple configuration | ||
|
|
||
| This can be overridden by including an `AdditionalFile` in the project called **todo-warn.config**. | ||
| If this file exists, warnings will only be reported for comments that start with any of the non-blank lines in that file. | ||
|
|
||
|  | ||
|
|
||
| A **todo-warn.config** file can also be specified in your user's [ApplicationData](https://docs.microsoft.com/en-us/dotnet/api/system.environment.specialfolder?view=netstandard-2.0) directory. (You can get to this by entering `%appdata%` in the File Explorer address bar.) | ||
| Project-level configurations will override the user level configuration if they exist. | ||
|
|
||
| For example, if the config file contained the line `TODO BEFORE CHECK-IN`, only comments that start that way are reported. | ||
|
|
||
|  | ||
|
|
||
| ### Advanced configuration | ||
|
|
||
| It is possible to control the type of error that is reported and filter beyond just how a comment starts. | ||
|
|
||
| #### Setting the output type | ||
|
|
||
| A line in the config file may, optionally, start with one of the following. | ||
|
|
||
| `[INFO]` - which will cause any comment identified by the rest of the line to be reported as information/message. | ||
| `[ERROR]` - which will cause any comment identified by the rest of the line to be reported as an error. Errors reported in this way will not cause a build to fail as they are separate from the build process. | ||
| `[WARN]` - which will cause any comment identified by the rest of the line to be reported as a warning. This is the same as not including any of these output indicators. | ||
|
|
||
| #### Filtering output by line content | ||
|
|
||
| In addition to a config file line containing plain text, that is treated as the line start value to use when identifying comments of interest, it is also possible for a line in a config file to be comprised of "config blocks." | ||
|
|
||
| A config block takes the format `[KEYWORD(value)]`. | ||
|
|
||
| The following keywords are supported | ||
|
|
||
| - STARTS | ||
| - CONTAINS | ||
| - DOESNOTCONTAIN | ||
| - MATCHESREGEX | ||
|
|
||
| Each config block is optional but must be listed in the order shown above and can only be included once. | ||
|
|
||
| This allows for the creation of rules such as "Show a message if a comment starting 'TODO' includes an issue number but isn't 'low-priority'." | ||
| It would look like: | ||
| `[INFO][STARTS(TODO)][CONTAINS(Issue#)][DOESNOTCONTAIN(low-priority)]`. | ||
|
|
||
| Or you could have an error displayed if a comment line included, at any point, the text "before check-in" with the line `[ERROR][CONTAINS(before check-in)]`. | ||
|
|
||
| #### Excluding files from output | ||
|
|
||
| If you do not wish a warning to be raised in a specific file (or files) this can be achieved with the `[EXCLUDE]` instruction. | ||
|
|
||
| Specify a line in the config that starts with `[EXCLUDE]` followed by the name of the file to exclude. | ||
| e.g. | ||
| ``` | ||
| [EXCLUDE]Program.cs | ||
| ``` | ||
|
|
||
| This will prevent the reporting of any file named "Program.cs" or has a name that ends this way and so will, for example, also matches "MyProgram.cs". | ||
| To match the filename exactly, include the path separator, like so `[EXCLUDE]\Program.cs` | ||
|
|
||
| A single wild card (*) can be included in the path and one is assumed at the start. | ||
| The following lines are treated as identical. | ||
| ``` | ||
| [EXCLUDE]\Program.cs | ||
| [EXCLUDE]*\Program.cs | ||
| ``` | ||
|
|
||
| Adding a wildcard at the end of the instruction can be useful to exclude all files in a directory. The following would prevent the reporting of warnings about any files in the "Controllers" directory, including in any sub-directory. | ||
| ``` | ||
| [EXCLUDE]\Controllers\* | ||
| ``` | ||
|
|
||
| A wildcard can also be included in the middle of the text. The following prevents reporting of warnings about any file in the "Views" directory that ends with "Page" and has the ".cs" extension. | ||
| ``` | ||
| [EXCLUDE]\Views\*Page.cs | ||
| ``` | ||
|
|
||
| Multiple exclusion instructions can be specified in the config file and if any match the full path of a file being analyzed it will prevent any warnings for that file being reported. | ||
|
|
||
| #### Example configuration | ||
|
|
||
| The following are all examples of valid lines in a config file. | ||
|
|
||
| ```ascii | ||
| TO DO | ||
| [WARN]temp | ||
| [WARN]for-review | ||
| [WARN]for review | ||
| [ERROR][CONTAINS(before check-in)] | ||
| [WARN][STARTS(TODO)][DOESNOTCONTAIN(Issue#)] | ||
| [INFO][STARTS(TODO)][CONTAINS(Issue#)][DOESNOTCONTAIN(low-priority)] | ||
| [EXCLUDE]Config\*.cs | ||
| [MATCHESREGEX(Issue #[\d]+)] | ||
| ``` | ||
|
|