Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

"@param {function(number)} myParam" only renders as "function" #1510

Open
lll000111 opened this issue Feb 26, 2018 · 2 comments · May be fixed by #1735
Open

"@param {function(number)} myParam" only renders as "function" #1510

lll000111 opened this issue Feb 26, 2018 · 2 comments · May be fixed by #1735

Comments

@lll000111
Copy link

lll000111 commented Feb 26, 2018 •
edited

Functions with types like function(number):boolean are only rendered as the single word "function".

Using Closure compiler syntax for function annotations: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler

image

Input code

/**
 * @param {ExporterEventFunctions} EventFunctions Functions to send events to the remote instance
 * @param {function(function())} onWebsocketClose Takes a function that is called the websocket
 * closes, regardless of reason
 * @param {function(SHA256Hash,?SHA256Hash)} addAccessibleHashToCache The cache is used for
 * access control for incoming requests
 * @param {function(function(number))} subscribeToOnAcknowledgeMsg
 */
...

JSDoc configuration

{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "source": {
        "include": ["src/"],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": [
        "node_modules/jsdoc-strip-async-await",
        "plugins/markdown",
        "plugins/underscore",
        "node_modules/jsdoc-babel"
    ],
    "babel": {
        "presets": ["es2017"],
        "plugins": ["transform-flow-strip-types"]
    },
    "templates": {
        "default": {
            "includeDate": false
        },
        "cleverLinks": false,
        "monospaceLinks": false
    },
    "markdown" : {
        "idInHeadings" : true
    },
    "opts": {
        "template": "./doc/JSDoc.template",
        "encoding": "utf8",
        "destination": "doc/API/",
        "recurse": true,
        "readme": "doc/README.md"
    }
}

JSDoc debug output

$ node_modules/.bin/jsdoc --debug --verbose -a undefined -a public -c jsdoc.json
DEBUG: JSDoc 3.5.5 (Thu, 14 Sep 2017 02:51:54 GMT)
DEBUG: Environment info: {"env":{"conf":{"plugins":["node_modules/jsdoc-strip-async-await","plugins/markdown","plugins/underscore","node_modules/jsdoc-babel"],"recurseDepth":10,"source":{"includePattern":".+\\.js(doc|x)?$","excludePattern":"(^|\\/|\\\\)_","include":["src/"]},"sourceType":"module","tags":{"allowUnknownTags":true,"dictionaries":["jsdoc","closure"]},"templates":{"monospaceLinks":false,"cleverLinks":false,"default":{"includeDate":false}},"babel":{"presets":["es2017"],"plugins":["transform-flow-strip-types"]},"markdown":{"idInHeadings":true},"opts":{"template":"./doc/JSDoc.template","encoding":"utf8","destination":"doc/API/","recurse":true,"readme":"doc/README.md"}},"opts":{"_":[],"debug":true,"verbose":true,"access":["undefined","public"],"configure":"jsdoc.json","template":"./doc/JSDoc.template","encoding":"utf8","destination":"doc/API/","recurse":true,"readme":"doc/README.md"}}}
DEBUG: Parsing source files: [....]
Parsing....
...
DEBUG: Finished parsing source files.
DEBUG: Indexing doclets...
DEBUG: Adding inherited symbols, mixins, and interface implementations...
DEBUG: Adding borrowed doclets...
DEBUG: Post-processing complete.
Generating output files...
Finished running in 5.17 seconds.

Expected behavior

Render the full function including its types.

Current behavior

See screenshot.

Your environment

Software Version
JSDoc 3.5.5
Node.js 9.6.1
npm 5.6.0
Operating system Windows 10
codeworrior added a commit to codeworrior/jsdoc that referenced this issue Jan 10, 2020
@codeworrior
Properly stringify function types with signature
e829235 
When function types contain a signature (e.g. `function(string, boolean): string`), `catharsis` parses them correctly, but the type handling in JSDoc stringified them as `function`, the signature was omitted.

With this change, the signature is added, too.  
 
Fixes jsdoc#1510 .
@codeworrior codeworrior linked a pull request Jan 10, 2020 that will close this issue
Open
@codeworrior
Copy link

I understand that using @typedefs (or @callbacks) is an alternative, but sometimes, a simple inline signature is faster to grasp for the reader and less effort to write in the source code.

At a first glance, a fix seems to be as simple as PR #1735.

However, fixing this might cause regressions for other users, e.g. when they post-process the symbol information provided by JSDoc and can't handle the signatures. If this is considered a bigger issue, some kind of feature switch might be needed in addition.

@germanz
Copy link

germanz commented Mar 2, 2020

I am also interested in this fix. @codeworrior any chance to make the crosslinks working for the callback argument types in that PR #1735 ?

openui5bot pushed a commit to SAP/openui5 that referenced this issue Jun 25, 2021
@codeworrior
[INTERNAL] JSDoc: fix issue with function types and record types
ff8dec9 
JSDoc reduces function types to the keyword "function", all other
details of the signature (parameters, return type, constructor type) are
lost. This has been reported as
jsdoc/jsdoc#1510 and a fix has been proposed
in jsdoc/jsdoc#1735 .

This change monkey patches JSDoc 3.6.x with the change from the
mentioned PR 1735.

At the same time, a similar problem regarding record types (structures)
is fixed.

Change-Id: I0e8de19cedf13751ff512f6c8900d441a5862435
codeworrior added a commit to SAP/ui5-builder that referenced this issue Jun 9, 2022
@codeworrior
[INTERNAL] JSDoc: fix issue with function types and record types
1e84e2a 
JSDoc reduces function types to the keyword "function", all other
details of the signature (parameters, return type, constructor type) are
lost. This has been reported as
jsdoc/jsdoc#1510 and a fix has been proposed
in jsdoc/jsdoc#1735 .

This change monkey patches JSDoc 3.6.x with the change from the
mentioned PR 1735.

At the same time, a similar problem regarding record types (structures)
is fixed.

Cherry picked from SAP/openui5@ff8dec90f
codeworrior added a commit to SAP/ui5-builder that referenced this issue Jun 13, 2022
@codeworrior
[INTERNAL] JSDoc: fix issue with function types and record types
86f95bc 
JSDoc reduces function types to the keyword "function", all other
details of the signature (parameters, return type, constructor type) are
lost. This has been reported as
jsdoc/jsdoc#1510 and a fix has been proposed
in jsdoc/jsdoc#1735 .

This change monkey patches JSDoc 3.6.x with the change from the
mentioned PR 1735.

At the same time, a similar problem regarding record types (structures)
is fixed.

Cherry picked from SAP/openui5@ff8dec90f
RandomByte pushed a commit to SAP/ui5-builder that referenced this issue Jun 14, 2022
@codeworrior @RandomByte
[INTERNAL] JSDoc: fix issue with function types and record types
909af67 
JSDoc reduces function types to the keyword "function", all other
details of the signature (parameters, return type, constructor type) are
lost. This has been reported as
jsdoc/jsdoc#1510 and a fix has been proposed
in jsdoc/jsdoc#1735 .

This change monkey patches JSDoc 3.6.x with the change from the
mentioned PR 1735.

At the same time, a similar problem regarding record types (structures)
is fixed.

Cherry picked from SAP/openui5@ff8dec90f
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Properly stringify function types with signature codeworrior/jsdoc
3 participants
@germanz @codeworrior @lll000111