jsdoc / jsdoc/jsdoc

@typedef {Object} with function properties: Does not get past "function" (the word), ignores the types

Open
#1,444 0 comments 7 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

I define a few object types for "API objects", i.e. objects returned by a function that export an "API" from within that functions scope.

Example:

/**
 * `SystemReadStream` objects are created by factory function
 * @global
 * @typedef {Object} SimpleReadStream
 * @property {function((string|ArrayBuffer)):undefined} ondata <b>Assign your event handler</b>
 * @property {function(Error):undefined} onerror <b>Assign your event handler</b>
 * @property {function():undefined} onfinished <b>Assign your event handler</b>
 * @property {function():undefined} pause Pause the read stream
 * @property {function():undefined} resume Resume the read stream
 * @property {function():undefined} close Cancel the read stream
 */

This works in WebStorm:

unbenannt-1

But from JSDoc (using the default template from 3.5.5 with four minor custom CSS rules added) I only get "function", it leaves out all the type information:

unbenannt-2

This is a function syntax used by many, just one of numerous examples (not to mention that WebStorm would not have bothered to support this if that wasn't the case): https://stackoverflow.com/a/38586423/544779

Also, it should be supported at least through the Closure Compiler types, go to "Function Type": https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System or https://github.com/google/closure-compiler/wiki/Annotating-Types#function-declarations or https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#function-type

or go to https://github.com/Microsoft/TypeScript/wiki/JSDoc-support-in-JavaScript "Define function type" (Example)

So... virtually everybody says that this is the syntax to specify a function type, and the IDEs support it too. Only JSDoc doesn't?

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

Reproduce the issue with the supplied @typedef example, then trace JSDoc's type parsing and generated documentation output. Done means function-property parameter and return types are preserved in the output instead of being rendered only as "function".

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.