[erelcolak]

Q	A
Bug fix?	no
New feature?	yes
Breaking change?	no
Deprecations?	no
Tests added?	yes
Fixed issues	n/a
License	Apache-2.0

Problem

AI coding tools tend to leave history, rationale, and decision notes as inline comments scattered through a file. Running into a note written by a tool in the middle of a function is confusing, and over time it makes the surrounding code noticeably harder to read.

There is currently no conventional place for that kind of note, so it ends up wherever the tool happened to be editing.

Proposal

Add an @ai block tag that gives those notes a single, predictable home inside the JSDoc comment block:

/**
 * Fetches all users from the API.
 *
 * @author erelcolak
 * @function getUsers
 * @ai Refactored to async/await. -- Claude
 * @ai Added a null guard for `id`. -- Copilot
 * @returns {Promise<Object[]>} The users.
 */
const getUsers = () => { /* ... */ };

To be clear about the scope: this PR only adds the tag. Getting an AI tool to actually write its notes there is up to the user's own instructions to the tool, or to the tool reading the JSDoc documentation. That part is deliberately out of scope here.

Design

The tag takes a required value and can be repeated:

• mustHaveValue: true -- an empty @ai is not meaningful.
• Repeatable -- values accumulate in an ai array on the doclet, so notes from several tools or several sessions do not overwrite each other.

It is defined in core.js, which feeds the JSDoc dictionary. The Closure dictionary picks its tags individually rather than spreading the core set, so it is unaffected -- @ai is not a Closure Compiler tag and does not appear there.

DOCLET_SCHEMA uses additionalProperties: false, so the ai property is added to the schema as well.

The default template renders the notes under an "AI Notes:" heading in details.tmpl.

Changes

File	Change
packages/jsdoc-tag/lib/definitions/core.js	Tag definition
packages/jsdoc-doclet/lib/schema.js	ai property on the doclet schema
packages/jsdoc-template-legacy/tmpl/details.tmpl	"AI Notes:" section
packages/jsdoc/test/fixtures/aitag.js	New fixture
packages/jsdoc/test/specs/tags/aitag.js	New spec

5 files, +56 lines, no deletions.

Testing

• npm run lint -- clean
• npm run license-check -- clean
• npm test -- 568 suites, 1626 specs, 0 failures
• Verified end to end by running JSDoc over a sample file: the notes render in the generated HTML under "AI Notes:", and appear in -X JSON output as an ai array.

On adding tags to core

I realize proposals for new core tags come up fairly often -- #1162 (@chainable), #1277 (time complexity), #2047 (@scope) and #2139 (@legacy) are all still open -- and I could not find a written policy on where the line sits between a core tag and a plugin-defined one.

So rather than asking for a merge outright, I would mostly like a direction:

1. If @ai belongs in core, this branch is ready as-is.
2. If new tags generally belong in a plugin, say the word and I will move this to dictionary.defineTag() and close the PR. The implementation is nearly identical, so it costs me very little.
3. If the answer is "not this tag", that is a perfectly good answer too and I will close it myself.

Either way, if this lands I am happy to follow up with documentation in jsdoc/jsdoc.github.io.