jsdoc / jsdoc/jsdoc

@callback not generated if tags.dictionaries contains closure and jsdoc

Open
#1,787 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
15.5k
Forks
1.5k
Avg merge
10d 23h
Merged PRs (30d)
1

Description

Input code

Copying from working example in #356:

/** @module notes/notes_db */

/**
 * Callback required by most find methods.
 * @callback module:notes/notes_db.findCallback
 * @param {*} err Error string, null if no error.
 * @param {Object|Array} docs Documents retrieved by the find request.
 */

/**
 * Returns all notes in the database.
 * @param {module:notes/notes_db.findCallback} callback
 */
function functionExpectingACallback(callback) {}
JSDoc configuration
{
  "tags": {
    "dictionaries": [
      "closure",
      "jsdoc"
    ]
  }
}
JSDoc debug output
DEBUG: JSDoc 3.6.4 (Mon, 06 Apr 2020 19:30:09 GMT)
DEBUG: Environment info: {"env":{"conf":{"plugins":[],"recurseDepth":10,"source":{"includePattern":".+\\.js(doc|x)?$","excludePattern":""},"sourceType":"module","tags":{"allowUnknownTags":true,"dictionaries":["closure","jsdoc"]},"templates":{"monospaceLinks":false,"cleverLinks":false}},"opts":{"_":["356.js"],"configure":"/dev/fd/63","debug":true,"destination":"./out/","encoding":"utf8"}}}
DEBUG: Parsing source files: ["/tmp/356.js"]
Parsing /tmp/356.js ...
DEBUG: Finished parsing source files.
DEBUG: Adding inherited symbols, mixins, and interface implementations...
DEBUG: Adding borrowed doclets...
DEBUG: Post-processing complete.
Generating output files...
Finished running in 0.32 seconds.
Expected behavior

Generated documentation includes findCallback in "Type Definitions".

Since Closure Compiler doesn't have a @callback tag, I would have expected JSDoc to use the tag from the jsdoc dictionary, which would generate the same output with or without closure in tags.dictionaries. Perhaps I'm mistaken?

Current behavior

Generated documentation does not include findCallback, and only includes functionExpectingACallback.

Removing closure from tags.dictionaries or moving it after jsdoc avoids the issue.

Your environment
Software Version
JSDoc 3.6.4
Node.js v10.20.1
npm 6.14.5
Operating system Debian GNU/Linux

Similar issue: #1291

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the shown JavaScript input with the tags.dictionaries configuration containing closure and jsdoc, then inspect JSDoc's tag-dictionary handling. Done means the generated Type Definitions include findCallback regardless of dictionary order, while functionExpectingACallback remains documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.