otris / jsdoc-tsd Goto Github PK
View Code? Open in Web Editor NEWJSDoc template for generating TypeScript definition files based on JSDoc comments.
License: MIT License
JSDoc template for generating TypeScript definition files based on JSDoc comments.
License: MIT License
Let's say I have a @module
with an inner @typedef
:
/**
* @module my-module
*/
/**
* @typedef {object} MyType
*/
If I wanted to pass MyType
as a @param
to a function or as a @property
of another @typedef
, based on JSDoc convention you should use a namepath whenever using modules like this:
/**
* My function:
*
* @param {module:my-module~MyType} obj - The object
*/
module.exports.myFunc = function (obj) {
// ...
}
jsdoc
and related templates (like the template to convert to markdown) handle this properly but whenever @otris/jsdoc-tsd
generates the TSD, I get something like this:
declare module 'my-module' {
declare interface MyType {}
export function myFunc(obj: module:my-module~MyType): void;
}
So instead of obj: MyType
, I get obj: module:my-module~MyType
. The same thing happens when you use a namepath for any other place where a namepath is used, like @property
.
The reason this has come up is that my JSDoc either generates proper TSD (via @otris/jsdoc-tsd
) or MD (via jsdoc2md/jsdoc-to-markdown
) but never both at the same time. I realize that jsdoc2md/jsdoc-to-markdown
could very well be the culprit but when I looked into this from the JSDoc site, it looks like any namepath should be fully-qualified when using modules.
I'm running jsdoc-tsd version 3.0.0 and jsdoc version 4.0.2. Command is simply jsdoc -t node_modules/@otris/jsdoc-tsd Node.js
I have a class file that can be reduced to this:
/**
* @property {string} value The value of the node.
*/
export class Node {
constructor (value = '') {
this.value = value;
}
}
Which only yields an error: "Can't add member 'Node' to parent item 'Node'. Unsupported member type: 'class'".
Same thing with the ES 2015 Classes example in the JSDoc documentation.
I've been able to get rid of the error by tagging with @class
and @constructs
, but that still doesn't give me any output.
With #58 the handling of typedefs was changed. Before these changes, typedefs without types (@typedef MyTypeDef
) were implicit handled as @typedef {object} MyTypeDef
. With the refactoring, typedefs without types will no be ignored. Instead an error message will be logged to the console.
TO-DO
Let's say I have a function that has a @returns {module:sway~Operation[]}
, the generated TSD has any[]
. For example, this JSDoc is generated as this TSD. It should be Operation[]
and not any[]
.
The following jsdoc type trigger this error:
/**
* @param {number} digits
* @returns {[bigint, bigint]}
*/
TypeError: Do not know how to serialize a BigInt
Any way to handle this?
In the meantime is there a way to specify files to exclude when using the command?
pnpm exec jsdoc -t node_modules/@otris/jsdoc-tsd -r ./algorithms -d types.d.ts
Many Thanks!
For JS-Callbacks you have the possibility to describe a callback function with the @callback
-annotation. The module generates currently an empty interface for that
Example:
/**
* Description of my callback
* @memberof myNamespace
* @callback myCallback
* @param {string} param1 Description of param1
* @returns {string} Description of the return value
*/
/**
* Description of my function
* @memberof myNamespace
* @param {myNamespace.myCallback} callback My callback param
*/
function test(callback) {
// ...
}
Generated output:
declare namespace myNamespace {
interface myCallback {
}
function test(callback: myCallback): void;
}
Expected output:
declare namespace myNamespace {
declare type myCallback = (param1: string) => string;
function test(callback: myCallback): void;
}
If you try to use this template with grunt, you will get the following error:
Running "jsdoc:typings" (jsdoc) task
>> FATAL: Unable to load template: Cannot find module 'E:\<project>\node_modules\jsdoc-tsd/publish'
Warning: jsdoc terminated with a non-zero exit code Use --force to continue.
Aborted due to warnings.
Version: v0.1.0
Grunt-Config:
jsdoc: {
typings: {
src: "src",
options: {
destination: "dist/typings",
recurse: true,
template: "node_modules/jsdoc-tsd"
}
}
}
}
Hi,
How should we document external modules in the code?
A simple example would be this:
/**
* @returns {Readable}
*/
function() { return fs.createReadStream('some-file.txt') }
In this case we mean import {Readable} from "stream"
which should appear in the definition file.
It would be really nice to have some way to dictate how things are sorted in the generated .d.ts
, even if only for the class
/interface
members.
With jsdoc
comments it is now possible to mark module members static
or inner
(see myModule2).
With module.export
in javascript
code it is now possible to mark module members exported
or inner
(see myModule1).
Both, the static
and the exported
members will be exported in the generated file.
But for now it is not quite clear why the @static
tag has to be used in jsdoc
comments and how the @exports
tag can be used.
Additional some tests must be added for module member flags.
For some items the property "description" is used for other items the property "comment" is used. Thats the reason why some description values missing in the result d.ts
The right way is to use the "comment" property. The description property contains only the value which is annotated with "@description"
Parameters with properties are described in
http://usejsdoc.org/tags-param.html#parameters-with-properties
The paramters with properties are required to generate d.ts
files for additional DOCUMENTS modules like DocumentsContext.
At the moment all parameter properties are added to the parameters in the function declaration.
In JSDoc, you have the possibility to describe an object param as follow:
/**
* @typedef {object} myCustomType
* @property {string} myProp
*/
/**
* @param {Object<string, myCustomType>} myParam Description
*/
function test(myParam) {
}
With this syntax, you define that the param myParam
has some string properties with which value can only be of type myCustomType
.
The typescript equivalent would be
function test(myParam: { [key: string]: myCustomType }): void;
I have the following function definition
/**
* My function
* @param {boolean} [myParam=true] bla
*/
function myFunction(myParam) {
}
The generated output looks like this
function myFunction(myParam?: boolean);
The expected output looks like this
function myFunction(myParam: boolean = true);
Let's say I've got the following JSDoc to describe a callback:
/**
* Callback used to provide access to altering a remote request prior to the request being made.
*
* @callback PrepareRequestCallback
*
* @param {object} req - The Superagent request object
* @param {string} location - The location being retrieved
* @param {function} callback - First callback
*/
Right now, I have an NPM module that wants to describe a callback but it's not something exported. If I use @callback
, I get the following error when generating the TSD:
Can't add member 'module:path-loader~PrepareRequestCallback' to parent item 'undefined'. Unsupported member type: 'alias'
If I replace @callback
with @function
, no error but the function is exported and I end up with something like this:
/**
* Utility that provides a single API for loading the content of a path/URL.
*/
declare module 'path-loader' {
// ...
/**
* Callback used to provide access to altering a remote request prior to the request being made.
* @param req - The Superagent request object
* @param location - The location being retrieved
* @param callback - First callback
*/
export function PrepareRequestCallback(req: object, location: string, callback: Function): void;
// ...
}
I need a way within a @module
to describe a callback so that it gets generated as declare function {MY_CALLBACK}
so that it's documented but not exported. (I'm new to TypeScript and TSD so bear with me please.)
See discussion in #56
Whenever I use class B extends A
in JavaScript, with the appropriate @extends
tag, instead of the TSD containing class B extends A
, I end up with all members of A
being duplicated in B
. Is this the desired approach?
JSDoc has the ability to hide the constructor from the documentation with the tag above.:
/**
* @class
* @hideconstructur
*/
function myClass() {
}
will result in
declare class myClass {
}
For debugging purpose it would be useful to write the passed tuffy db from jsdoc to the file system in verbose mode
Let's say I have a function
that returns Promise<*>
. When that is converted to TSD, shouldn't that be Promise.<any>
and not Promise.<*>
?
...as the title says
See
jsdoc-tsd/src/core/jsdoc-tsd-parser.ts
Line 153 in df4e0bc
You can do something like this:
/**
* @typedef {string} SomeType
*/
/**
* @param {SomeType|object} fuu Some string identifier or an object
* @param {string} fuu.bar Some property of object fuu
*/
function fuuBar(fuu) {
}
*/
This will fail because the plugin tries to create a type alias definition but will reject because properties are defined. The code above should instead create a type definition for the passed object. Both types should be keep in the parameter type.
Given I have the following jsdoc for a function,
/**
* @param {Array<Array<string|CustomObject>>} [field] ...
*/
function myFunction(field) {}
This is the resulting invalid TS that I get:
static myFunction(field?: Array.<(string|CustomObject)[]): void;
Is there a correct way of handling multi-dimensional arrays of different types or is this a bug in the generation?
As reported in whitlockjc/json-refs#140, it seems like a declare
in a module
, namespace
, ... causes the error thrown in the title. whitlockjc/json-refs#143 shows how to fix this and has some details.
The function prune()
of jsdoc/util/templateHelper
should be called in template.
The flag ignorePrivateMembers
can be removed then.
You can set the this-reference via "@this" for functions. We need a way to support this, e.g. with functions
/**
* @class myClass
*/
/**
* @function myFunc
* @this myClass
*/
Will result in
function myFunc(this: myClass): void;
For example, the below code does not generate the correct typing definition
/**
* @module test1
*/
class One {}
export default One
exports.tag = "one"
It generates the below type description which does not include the default export
declare module 'test1' {
class One { };
export var tag: string;
}
It's missing the default export
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.