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.

Table of Contents

• 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