otris / jsdoc-tsd Goto Github PK

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

• Restore old behaviour
  ** Add test to ensure this

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.

1. With jsdoc comments it is now possible to mark module members static or inner (see myModule2).

2. 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

e.g
https://github.com/wehrstedt/jsdoc-tsd/blob/0a2acff3bad140db43fecfd43034ed95cc5fd519/src/core/jsdoc-tsd-parser.ts#L157

https://github.com/wehrstedt/jsdoc-tsd/blob/0a2acff3bad140db43fecfd43034ed95cc5fd519/src/core/jsdoc-tsd-parser.ts#L169

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

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