JSDoc To Do

Turn "to do" comments in your JavaScript code into a handy checklist in your project's README.md (or a different) file.

• JSDoc To Do
  • Features
  • Installation
  • Usage
  • Example
    • Input
    • Output
  • Marking a task/to-do as completed.
    • todoPlugin Configuration
  • Development
    • Testing
  • Known issues
  • To Do

Features

• Extracts "to do" items into an easily accessible checklist.
• Links each "to do" item to its source file and line number.
• Marks "to do" items as completed directly in JS files.
• Updates "to do" list when @todo or @todolist comments are added or removed.

Installation

npm install -D jsdoc-todo

Usage

1. Add the below to your JSDoc configuration file.

   // jsdoc.config.js
   const { todoPlugin } = require("jsdoc-todo");
   
   module.exports = {
     plugins: [todoPlugin],
   };

   OR

   // jsdoc.config.json
   {
     "plugins": ["node_modules/jsdoc-todo/jsdoc-todo.js"]
   }

2. Run jsdoc with the configuration file created in the previous step.

   jsdoc -c path/to/jsdoc-config-file .

[!NOTE] jsdoc-todo writes the generated "to do" list to a project's README.md file by default. If you wish to have jsdoc-todo write the generated "to do" list to a different file, add a todoPlugin.outFile property to the project's JSDoc configuration file as shown below.

const { todoPlugin } = require("jsdoc-todo");

module.exports = {
  plugins: [todoPlugin],
  todoPlugin: {
    outFile: "some/other/file.md",
  },
};

OR

{
  "plugins": ["node_modules/jsdoc-todo/jsdoc-todo.js"],
  "todoPlugin": {
    "outFile": "some/other/file.md"
  }
}

[!TIP] See todoPlugin for all todoPlugin configuration options.

Example

Input

/**
 * @todolist
 * The below will match anything that's an instance of Object (i.e., Arrays, Maps etc.). Use `Object.prototype.toString.call(arg)` instead.
 * Don't forget to test it before your next PR.
 * Consider using Zod's `z.object(arg)` etc. for this and other validators/validations.
 */
function isObject(arg) {
  if (arg instanceof Object) {
    return true;
  }
}

/** @todo Capitalize this and other constant identifiers +x */
const { NODE_ENV, JWT_PRIVATE_KEY } = process.env;

/**
 * @todo
 * A multi-line @todo item
 * is processed
 * as a single line.
 * Use @todolist tags if you want each line to contain a to do item.
 */

Output

<!-- @todolist
DO NOT MANUALLY EDIT THIS TO DO LIST !!!
THIS WHOLE SECTION, INCLUDING ITS HEADING IS AUTO-GENERATED BY `jsdoc-todo` plugin.
ALL MANUAL CHANGES WILL BE OVERWRITTEN THE NEXT TIME jsdoc RUNS !!!!

IF YOU MUST DIRECTLY/MANUALLY INCLUDE TO DO ITEMS IN THIS DOCUMENT,
PLEASE ADD THEM DIRECTLY BELOW THE "@endtodolist" HTML COMMENT BELOW. -->

## To Do

- [ ] A multi-line @todo item is processed as a single line. Use @todolist tags if you want each line to contain a to do item.&nbsp;-&nbsp;[review](tests/jsdoc-todo.test.js#L116)
- [ ] The below will match anything that's an instance of Object (i.e., Arrays, Maps etc.). Use `Object.prototype.toString.call(arg)` instead.&nbsp;-&nbsp;[review](tests/jsdoc-todo.test.js#L101)
- [ ] Don't forget to test it before your next PR.&nbsp;-&nbsp;[review](tests/jsdoc-todo.test.js#L102)
- [ ] Consider using Zod's `z.object(arg)` etc. for this and other validators/validations.&nbsp;-&nbsp;[review](tests/jsdoc-todo.test.js#L103)
- [x] Capitalize this and other constant identifiers&nbsp;-&nbsp;[review](tests/jsdoc-todo.test.js#L111)

<!-- @endtodolist -->

Marking a task/to-do as completed.

Append +x to the end of a line in a @todolist or a single-line @todo to mark the task as completed.

If you're working with a multiline @todo, append +x to the end of the last line instead.

todoPlugin Configuration

| Setting | Description | Type | Required | Default | | -------------- | --------------------------------------- | -------- | -------- | ----------- | | heading | "To Do" section's heading. | string | false | To Do | | headingLevel | HTML heading type (1 to 6). | number | false | 2 | | outFile | Output file. | number | false | README.md | | tag | Marks the start of the "To Do" section. | string | false | todolist |

Development

git clone https://github.com/achianumba/jsdoc-todo.git

cd jsdoc-todo

pnpm install

pnpm run build

Testing

# Run pnpm run build beforehand
pnpm run test

Known issues

• Doesn't support TypeScript. Consider setting "removeComments": true in your tsconfig.json file for now and parsing the emitted files.

To Do

• [ ] Generate "to do" list from TS files too. - review
• [ ] Test against JSX and TSX files. - review
• [ ] Delete todolist section from config.outFile if no "to do" comments are found in source code. - review
• [ ] JSDoc has a built-in @todo tag. Allow users to configure whether @todo doclets are omitted from the generated HTML docs instead of omitting it by default. - review