@callback not generated if tags.dictionaries contains closure and jsdoc
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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