englercj / tsd-jsdoc Goto Github PK

View Code? Open in Web Editor NEW

307.0 307.0 42.0 449 KB

Compiles JSDoc annotated JavaScript into a Typescript Definition file (.d.ts)

License: MIT License

TypeScript 99.87% JavaScript 0.13%

tsd-jsdoc's People

Contributors

Stargazers

Watchers

tsd-jsdoc's Issues

Interfaces name is prefixed with 'I'

When running tsd-jsdoc on openlayers 3, it prefixes the interface names with 'I' which lead to errors since typescript cannot find the original type. For example, the olx.style.CircleOptions interface is created as:

interface ICircleOptions {
...
}

but others types still reference it as CircleOptions:

class Circle ... {
    constructor(opt_options?: olx.style.CircleOptions);
...
}

What is the reason for that 'I' prefix?

Output files are not recognized without exports

Sorry if I'm understanding something wrong here. I'm still learning TypeScript (or rather exporting TypeScript definitions from a JavaScript project).

The generated d.ts files don't have any export statements. Your readme states that the JSDoc @exports annotation is not needed as everything is exported, but I'm not sure how the generated definitions are supposed to work without export statements.

VSCode

VSCode uses the DefinitelyTyped repository in order to automatically fetch TypeScript definitions for auto completion and documentation tooltips.

Every single of them has export statements and they don't seem to work without them.

`fast-deep-equal`

fast-deep-equal is distributed with its own definition file and VSCode recognizes that one and displays basic typing info.

`resource-loader`

Your module resource-loader also gets distributed with its own definition file, but that one doesn't have export statement as it comes from tsd-jsdoc.

Trying with module.default.

Trying with new module.default().

Trying with new module.Loader().

Question

Do you think tsd-jsdoc could need the option to create a TypeScript definition file that contains export statements? If not, I guess I will have to write a post processor that takes tsd-jsdoc-generated files as input and outputs TypeScript definitions with export statements.

Promise that resolves an object with a generic type parameter as array is unable to be resolved

/**
 *
 * @typedef {Object} Channel
 * @alias Channel
 * @property {String} channelId 
 */

This works:

* @returns {Channel[]}

This works too:

* @returns {Promise<Channel[]>}

This works too:

* @returns {Promise<{newChannel:Channel}>}

This does not work:

* @returns {Promise<{newChannels:Channel[]}>}

=> [TSD-JSDoc] Unable to resolve generic type parameter, defaulting to any.

Unable to resolve type name "Uint8Array".

When I define a variable to be of type Uint8Array, I get the following error:
[TSD-JSDoc] Unable to resolve type name "Uint8Array". No type found with that name, defaulting to "any".

Code example:

/** @class */
class TestClass {
  /**
   * @param arr {Uint8Array}
   * @returns {Uint8Array}
   */
  testReturn(arr) {
    return arr;
  }
}

Configuration option for "types.d.ts" location

If I use tsd-jsdoc as a JSDoc template, then it will write the types.d.ts file into JSDoc's documentation directory. It would be nice if I could specify a separate location where I want the types.d.ts file to go.

My current setup is this (package.json):

  "scripts": {
    "jsdoc": "jsdoc --template node_modules/tsd-jsdoc --readme ./README.md --destination ./doc src/uuid.js"
  }

At the moment types.d.ts will be inside of doc/types.d.ts.

Refactor/Cleanup Emitter

The emitter is too monolithic, was fine for getting it working quickly but this needs to be split out and modularized.

Function parameters don't receive types which causes an error

I was trying to generate a declaration file for https://github.com/twilio/twilio-video.js and I got this error.

Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/dts-dom/bin/index.js:408
            switch (e.kind) {
                     ^

TypeError: Cannot read property 'kind' of null
    at writeReference (/Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/dts-dom/bin/index.js:408:22)
    at writeParameter (/Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/dts-dom/bin/index.js:508:9)
    at writeDelimited (/Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/dts-dom/bin/index.js:517:13)
    at writeFunction (/Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/dts-dom/bin/index.js:496:9)
    at writeDeclaration (/Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/dts-dom/bin/index.js:673:28)
    at Object.emit (/Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/dts-dom/bin/index.js:241:5)
    at Emitter.emit (/Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/tsd-jsdoc/Emitter.js:65:24)
    at Object.publish (/Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/tsd-jsdoc/publish.js:25:39)
    at Object.module.exports.cli.generateDocs (/Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/jsdoc/cli.js:430:39)
    at Object.module.exports.cli.processParseResults (/Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/jsdoc/cli.js:383:20)
    at module.exports.cli.main (/Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/jsdoc/cli.js:227:14)
    at Object.module.exports.cli.runCommand (/Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/jsdoc/cli.js:180:5)
    at /Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/jsdoc/jsdoc.js:103:9
    at Object.<anonymous> (/Users/jskrzypek/dev/twilio/twilio-video.js/node_modules/jsdoc/jsdoc.js:104:3)
    at Module._compile (module.js:570:32)
    at Object.Module._extensions..js (module.js:579:10)

@mixin and @mixes support

First off, well done on v2. It is looking like a huge step forward from v1. 👏

I saw that @mixin is supported but are there plans to support @mixes as well.

I noticed from the source that @mixin is handled like an interface; would it be better if @mixin was handled like a type-def instead? This could make the handling of @mixes easier.

For example, the following code:

/**
 * @mixin A
 * @property {string} one
 * @property {string} two
 */

...

/**
 * @typedef {Object} B
 * @mixes A
 * @property {string} three
 */

... would produce the following types:

declare type A = {
    one: string;
    two: string;
}

declare type B = A & {
    three: string;
}

Interfaces, and class extensions could still be handled by @interface and @extends

If you are yet to think about or work on this, and you agree with using types for @mixin/@mixes, I will start putting together a PR.

Let me know what you think? ❤️

Does not support TypeScript style JSDoc, which were added in TS2.3

Example here puppeteer/puppeteer#1170

Crashes when encountering comment blocks

When running against a file that contains comment blocks ~~without jsdoc tags~~ directly above a variable declaration that does not reference a function or class:

/**
 * Following label is used in the settings to describe values which should be
 * determined by the code while running, from the current data and graph style.
 *
 * Using 'undefined' directly achieves the same thing, but this is more
 * descriptive by describing the intent.
 */
var autoByDefault = undefined;

It appears to crash with:

/Users/mbroad/workspaces/vis/node_modules/dts-dom/bin/index.js:268
    throw new Error(err);
    ^

Error: Unknown declaration kind property
    at never (/Users/mbroad/workspaces/vis/node_modules/dts-dom/bin/index.js:268:11)
    at writeDeclaration (/Users/mbroad/workspaces/vis/node_modules/dts-dom/bin/index.js:780:28)
    at Object.emit (/Users/mbroad/workspaces/vis/node_modules/dts-dom/bin/index.js:276:5)
    at Emitter.emit (/Users/mbroad/workspaces/vis/node_modules/tsd-jsdoc/Emitter.js:65:24)
    at Object.publish (/Users/mbroad/workspaces/vis/node_modules/tsd-jsdoc/publish.js:25:39)
    at Object.module.exports.cli.generateDocs (/usr/local/lib/node_modules/jsdoc/cli.js:448:35)
    at Object.module.exports.cli.processParseResults (/usr/local/lib/node_modules/jsdoc/cli.js:399:20)
    at module.exports.cli.main (/usr/local/lib/node_modules/jsdoc/cli.js:240:14)
    at Object.module.exports.cli.runCommand (/usr/local/lib/node_modules/jsdoc/cli.js:189:5)
    at /usr/local/lib/node_modules/jsdoc/jsdoc.js:105:9
    at Object.<anonymous> (/usr/local/lib/node_modules/jsdoc/jsdoc.js:106:3)
    at Module._compile (module.js:573:30)
    at Object.Module._extensions..js (module.js:584:10)
    at Module.load (module.js:507:32)
    at tryModuleLoad (module.js:470:12)
    at Function.Module._load (module.js:462:3)

I've been able to work around the issue by adding the @ignore tag to the comment block.

Invalid output on functions taking params argument

We're using this template to generate a definition file for our library and we've come across something that doesn't seem to be accounted for. We frequently use the pattern of passing an object named params to different functions throughout the library. These functions take this design with their JSDoc comments:

/**
* A function that does something
* @param {object} params periodicity arguments
* @param {number} [params.var1]
* @param {string} [params.var2] 
* @param {string} [params.var3] 
* @memberof Library.SubNamespace
*/
function something(param){
    ...
}

It seems that this pattern isn't used in Typescript and the only way (in my understanding) to use it to define an interface for each param when its used. By default tsd-jsdoc outputs something like this:

something(params: any, params.var1?: number, params.var2?: string, params.var3?: string): void;

I'm sure that we're not the only people who utilize this design pattern and it would be nice to have this addition. I've taken a look thru the code and I'm not 100% sure whether this should be handled by this code or by dts-dom.

Custom type as any into @module

Hello,

If I add @module on top of my file to generate a virtual namespace, typedef not following as expected.

Example:

/**
 * @module GitGraph
 */
declare namespace GitGraph {
    /**
     * GitGraph Options
     * @typedef {object} GitGraphOptions
     * @property {string} [elementId = "gitGraph"] - Id of the canvas container
     * @property {Template|string|Object} [template] - Template of the graph
     * @property {string} [author = "Sergio Flores <[email protected]>"] - Default author for commits
     * @property {string} [mode = (null|"compact")]  - Display mode
     * @property {HTMLElement} [canvas] - DOM canvas (ex: document.getElementById("id"))
     * @property {string} [orientation = ("vertical-reverse"|"horizontal"|"horizontal-reverse")] - Graph orientation
     * @property {boolean} [reverseArrow = false] - Make arrows point to ancestors if true
     * @property {number} [initCommitOffsetX = 0] - Add custom offsetX to initial commit.
     * @property {number} [initCommitOffsetY = 0] - Add custom offsetY to initial commit.
     * @property {HTMLElement} [tooltipContainer = document.body] - HTML Element containing tooltips in compact mode.
     */
    type GitGraphOptions = {
        elementId: string;
        template: any | string | any;
        author: string;
        mode: string;
        canvas: any;
        orientation: string;
        reverseArrow: boolean;
        initCommitOffsetX: number;
        initCommitOffsetY: number;
        tooltipContainer: any;
    };

    /**
     * GitGraph
     * @constructor
     * @param {GitGraphOptions} options - GitGraph options
     * @this GitGraph
     */
    class GitGraph {
        constructor(options: any);
}

options:any should be options.GitGraph.GitGraphOptions

Issues in generated files

Hi,

I'm just a user of forerunnerdb and they are using your tool to generate their types.d.ts file
I have pointed out a few issues on the generated file.

types are generated inside of a class declaration
- Irrelon/ForerunnerDB#152
Array are defined without type, should be typed by default ?
- Irrelon/ForerunnerDB#154

The generated file is here : https://github.com/Irrelon/ForerunnerDB/blob/master/typescript/types.d.ts

I would like to check with you if this is a bug in this tool, or maybe it's possible to improve their jsdoc in order to fix those generation issues.

Thanks for your help.

Listing properties on an object type does not work

Hello,

I'm trying to generate types.d.ts for gitgraph.js

This is my problem:

/**
 * GitGraph
 * @constructor
 * @param {object} options - GitGraph options
 * @param {string} [options.elementId = "gitGraph"] - Id of the canvas container
 * @param {Template|string|object} [options.template] - Template of the graph
 * @param {string} [options.author = "Sergio Flores <[email protected]>"] - Default author for commits
 * @param {string} [options.mode = (null|"compact")]  - Display mode
 * @param {HTMLElement} [options.canvas] - DOM canvas (ex: document.getElementById("id"))
 * @param {string} [options.orientation = ("vertical-reverse"|"horizontal"|"horizontal-reverse")] - Graph orientation
 * @param {boolean} [options.reverseArrow = false] - Make arrows point to ancestors if true
 * @param {number} [options.initCommitOffsetX = 0] - Add custom offsetX to initial commit.
 * @param {number} [options.initCommitOffsetY = 0] - Add custom offsetY to initial commit.
 * @param {HTMLElement} [options.tooltipContainer = document.body] - HTML Element containing tooltips in compact mode.
 * @this GitGraph
 */
declare class GitGraph {
    constructor(options: any, options.elementId?: string, options.template?: Template | string | any, options.author?: string, options.mode?: string, options.canvas?: any, options.orientation?: string, options.reverseArrow?: boolean, options.initCommitOffsetX?: number, options.initCommitOffsetY?: number, options.tooltipContainer?: any);
}

My options is not correctly parsed, idealy I would like to export an interface of GitGraphOptions but I can't find any jsdoc notations for have the correct output…

If anyone have a simple solution, I take it, otherwise it can be a real issue

Thank you!

Map @typedefs with properties to interfaces

@typedefs can have properties on them. When that occurs, I think they should be mapped to interfaces.

Why do we have to copy the members of interface to class definitions?

see

tsd-jsdoc/src/Emitter.ts

Line 335 in 07c6298

private _resolveInterfaceMembers(docs: TDoclet[]) {

a reasonable version

// jsdoc marked as mixin
interface A {
	a(): void;
}

// jsdoc marked as interface
interface B {
	b(): void;
}

class C implements A, B {
}

current output

// jsdoc marked as mixin
interface A {
	a(): void;
}

// jsdoc marked as interface
interface B {
	b(): void;
}

class C implements A, B {
	static a(): void;
	b(): void;
}

The reason of static occurrence is because in jsdoc mixins do not apply scope: instance.

I can not figure out why should we copy those members to class. IMO, it's unnecessary.

Bug: Duplicated generating text from @module

Input

/**
 * The effection like Thanos snapping finger
 * @author imcuttle
 * @module snap-fade-away
 */
// ...

Output

/**
 * The effection like Thanos snapping finger
 * @author imcuttle
 * @module snap-fade-away
 */
declare module "snap-fade-away" { }

/**
 * The effection like Thanos snapping finger
 * @author imcuttle
 * @module snap-fade-away
 */
declare module "snap-fade-away" { }

Need help regarding how to use

https://github.com/ms10398/openfoodfacts-nodejs

I want to use it on this module but I am unable to use it

Can anyone help me regarding it.

Docmentation in README for how to run

It might not be obvious if you haven't used JSDoc before.

Support of "nullable types" or optional paramaters ({?number}, {string} [myParam], etc)

Hi,

First things first: thanks for this lib. It works beautifully, even if still "experimental".

I started using it to get autocompletion from VSCode intellisense accross my pure javascript object services/controllers (AngularJS app). I recently implemented Flowtype in this same projet and noticed that I could simply use the generated tsd file as a flow-typed definition. Which is quite a good thing, as the flowtype parser/checker use it to operate type-checking accross all my documented code (it was not possible, by default, with pure javascript object services or controllers).

I'm having an issue, though, with nullable types, like:

/**
 * @param {?number} eventValue Value attached to the target event (might be null).
 */

which are converted (in the tsd file) to

/**
 * @param {number} eventValue Value attached to the target event (might be null).
 */

Is there anything I missed about the proper way to use the lib? May I do a PR if I create a clean fix for this?

Thanks

Pixi.js-v5

Suppose you've cloned pixi.js, dev branch, and called tsd-jsdoc on packages. Don't call npm run build or you'll ruin it with unnecessary files. That's the output:

d:\pixi-games\tsd-jsdoc\Emitter.js:196
                    for (let i = 0; i < doclet.params.length; ++i) {
                                                      ^

TypeError: Cannot read property 'length' of undefined
    at Emitter._resolveObjects (d:\pixi-games\tsd-jsdoc\Emitter.js:196:55)
    at Emitter.parse (d:\pixi-games\tsd-jsdoc\Emitter.js:58:14)

We have to specify external classes somewhere:

[TSD-JSDoc] Unable to resolve type name "Float32Array". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Float32Array". No type found with that name, defaulting to "any".

VSCode debug configuration

Has anyone tried to debug with VSCode? I have setup a debug configuration through launch.json but it seems that jsdoc does not understand the --inspect-brk switch that is added from VSCode debuger.

D:\Dev\tsd-jsdoc/node_modules/.bin/jsdoc.cmd -t --inspect-brk=27568 dist\Emitter.js -r .
The command-line option "t" requires a value.

Export module

// cc @dcodeIO

What JSDoc comment do I have to use to export a module? I have this sample code:

/** @module MyModule */

/**
 * @param {string} message
 * @class MyClass
 */
class MyClass {
  constructor(message) {
    this.message = message;
  }
}

module.exports = MyClass;

And with the help of dcodeIO/tsd-jsdoc I can generate the following .d.ts file:

/** @module MyModule */
module MyModule {
   /**
    * @param {string} message
    * @class MyClass
    */
   class MyClass {
       /**
        * @param {string} message
        * @class MyClass
        */
       constructor(message: string);

   }

}

But how can I generate export module MyModule? I read the JSDoc reference but could not figure it out. I'd be happy if you could help me with that 🙂

Params should resolve long name

Right now params seem to output just the name of the object they reference. This means if you do something like this:

    /**
     * Creates a new thing.
     *
     * @param {!testns.CircleOptions} opts - Namespace test!
     * @return {MyThing} the new thing.
     */
    static create(opts)
    {
        return new MyThing();
    }

It will output:

    /**
     * Creates a new thing.
     * @param {!testns.CircleOptions} opts - Namespace test!
     * @return {MyThing} the new thing.
     */
    static create(opts: CircleOptions): MyThing;

Note the missing testns. on the param type.

(This may require dts-dom changes)

Cannot read property 'kind' of null (2.0.0 beta 3)

I was trying to use this project to generate typings for an existing project. If I just use jsdoc, it generates documentation correctly. However, when using tsd-jsdoc I'm getting Cannot read property 'kind' of null in dts-dom.

At the bottom are the configurations I used and the command I run. This should be enough after running npm install to reproduce the error. My goal is to generate types for toneJs.

Update 1

There seemed to be two issues occurring. The first error would occur because dts-dom was trying to write an undefined value, when I added a guard for that condition in dts-dom my original error went away. After that dts-dom would get error that the kind of 'property' wasn't supported. The generated typings looked mostly okay, but every so often there was a missing type or parameter name. So obviously I fixed a symptom not the problem.

packages.json

{
  "name": "blah",
  "version": "1.0.0",
  "dependencies": {
    "dts-dom": "^0.1.18",
    "jsdoc":"~3.4.3",
    "tone": "^0.10.0",
    "tsd-jsdoc":"^2.0.0-beta.3",
    "@types/webaudioapi": "^0.0.27"
  }
}

conf.json

{
    "opts": {
        "template": "./node_modules/tsd-jsdoc",  
        "destination": "./outtsd/",          
        "recurse": true        
    }
}

The command I'm executing
jsdoc ./node_modules/tone/Tone -r -c conf.json

Can the next version of this package be published to NPM?

Would it be possible to get a new version of tsd-jsdoc published? Several of the changes/fixes that have been committed to the codebase since v2.1.3 was published to NPM would be really useful to have available to us.

Thanks!

Cannot find module 'publish'

I'm trying to run jsdoc against an already existing library, but I get the error FATAL: Unable to load template: Cannot find module './node_modules/tsd-jsdoc/publish'. I've confirmed that npm install worked, but it looks like the publish file was removed in this commit: c8b7f3c

this is the command I'm using: jsdoc -c jsdoc.json -t node_modules/tsd-jsdoc

How can I get tsd-jsdoc running now? Do I have to compile it manually, or use a different source?

How to resolve these errors?

Hi, @englercj I came here from: pixijs/pixi-ui#16
Basically, I am trying to create .tsd for pixi-ui, but I see the errors below. How can I solve?

> npm install tsd-jsdoc
> npm install jsdoc@^3.4.0
> node_modules\.bin\jsdoc -t node_modules/tsd-jsdoc -r src
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.Button", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.CheckBox", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "bool". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.Container", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Failed to resolve base type of "PIXI.UI.Container", no object found with name "PIXI.UI.UIBase".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.DynamicText", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "DynamicTextStyle". No type found with that name, defaulting to "any".
[TSD-JSDoc] Failed to resolve base type of "PIXI.UI.DynamicText", no object found with name "PIXI.UI.UIBase".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.InputBase", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Failed to resolve base type of "PIXI.UI.InputBase", no object found with name "PIXI.UI.UIBase".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.ScrollBar", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "Object". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.ScrollingContainer", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "Boolean". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Boolean". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Boolean". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Failed to resolve base type of "PIXI.UI.ScrollingContainer", no object found with name "PIXI.UI.UIBase".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.SliceSprite", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "PIXI.Texture". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Boolean". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Boolean". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Boolean". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.Slider", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "Object". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "callback". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "callback". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.SortableList", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "Boolean". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "PIXI.UI.Ease". No type found with that name, defaulting to "any".
[TSD-JSDoc] Failed to resolve base type of "PIXI.UI.SortableList", no object found with name "PIXI.UI.UIBase".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.Sprite", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "PIXI.Texture". No type found with that name, defaulting to "any".
[TSD-JSDoc] Failed to resolve base type of "PIXI.UI.Sprite", no object found with name "PIXI.UI.UIBase".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.Stage", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.Text", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "PIXI.TextStyle". No type found with that name, defaulting to "any".
[TSD-JSDoc] Failed to resolve base type of "PIXI.UI.Text", no object found with name "PIXI.UI.UIBase".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.TextInput", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Boolean". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "PIXI.TextStyle". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Array". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "String". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.TilingSprite", using memberof "PIXI.UI". No such name found.
[TSD-JSDoc] Unable to resolve type name "PIXI.Texture". No type found with that name, defaulting to "any".
[TSD-JSDoc] Failed to resolve base type of "PIXI.UI.TilingSprite", no object found with name "PIXI.UI.UIBase".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Unable to resolve type name "Number". No type found with that name, defaulting to "any".
[TSD-JSDoc] Failed to resolve base type of "UIBase", no object found with name "PIXI.UI.UIBase".
[TSD-JSDoc] Unable to resolve memberof for "PIXI.UI.UISettings", using memberof "PIXI.UI". No such name found.

Can @file be ignored?

Hi again,
I was wondering if I could submit a PR to have tsd-jsdoc ignore @file JSDoc annotations? Of course there's nothing that those annotations should translate to in a Typescript definition, but I was hoping they could just be ignored.

Currently I have a lot of files that have JSDoc annotations like these at the top of the file:

/**
 * @file Resolves the paths to folders and/or files which is needed by the build script.
 * @requires NODE:url#parse
 * @requires NODE:fs#existsSync
 * @requires NPM:fs-extra#moveFileSync
 * @requires ./paths.js
 * @requires ./flags.js
 */

I use those in a different JSDoc template (although they are of very minor importance) and I'd prefer to keep them in there if I can. Right now it's throwing an error and I'm hoping it can just be modified similar to how you're ignoring @event, then it wouldn't throw an error when building the definition.

I think all I'd need is to add something like this to the src/Emitter.ts to the _parseTreeNode() method [1]. This worked for me locally when I modified the node_modules/tsd-jsdoc/dist/Emitter.js so I think it'll do the trick:

            case 'file'
                return null;

Thanks again!

...type generates incorrectly

/**
 * Constructs!
 * @param {...number} a - The number.
 * @private
 */

Will generate:

constructor(...a: number);

Which is invalid.

Has plan for supporting ES Module?

Hi, tsd-jsdoc is cool!
It throws [TSD-JSDoc] Failed to find parent of doclet 'module.exports' using memberof 'module', this is likely due to invalid JSDoc. when I use ES Module like export default.

getter & setters do not generate correctly

When a getter and a setter both exist the property is defined twice.

Improvements

The openlayers library is very well documented and is a good example to test tsd-jsdoc. Running the tool on the library, I get several errors that could help to improve tsd-jsdoc. Here is a list:

Array of Array: When a type or an argument is defined as Array<Array<something>>, only one Array is processed, ending with Array<something[]>. The same way, an Array<Array<Array<something>>> ends as Array<Array<somthing[]>>.
Inner classes: Inner classes should be generated in a specific module. For example, the Collection class defines an Event inner class. In Typescript, that Event class should be generated in a Collection module:

class Collection {
...
}

module Collection {
    class Event {
    ...
    }
}

Some jsdoc special characters are not ignored: I think this is an issue with jsdoc but it could be managed easily in tsd-jsdoc. For some complex type definitions, the leading '!' or the trailing '=' are kept. For example, {ol.geom.Geometry|Object.<string, *>=} ends in the tsd as (ol.geom.Geometry|{ [k: string]: any }=) or !Array.<string> ends as !string[]. It could be nice to ignore these characters.
Function prototype: openlayers doc precisely defines the function prototypes. It could be nice to generate equivalent Typescript definition. For example, the StyleFunction type is defined as function((ol.Feature|ol.render.Feature), number): (ol.style.Style|Array.<ol.style.Style>) but generated as: () => any. It should be (feature: (ol.Feature|ol.render.Feature), resolution: number) => (ol.style.Style|ol.style.Style[]).
{Array.<function(new: ol.format.Feature)>|undefined} is converted to ((() => any)(new:ol.format.Feature)[] | undefined). The first problem is with the argument that is not well positioned. The second problem comes with the name of the argument: 'new'. Arguments name should be checked to ensure they are not keywords. They could be replaced by the first letter of the argument: (((n: ol.format.Feature) => any)[] | undefined).

To reproduce:

clone the openlayers library
run npm install tsd-jsdoc
update the template line of config/jsdoc/info/conf.json with ./node_modules/tsd-jsdoc
run ./node_modules/.bin/jsdoc config/jsdoc/api/index.md -c config/jsdoc/api/conf.json --package package.json -d build/tsd

Properties missing when adding a module/namespace

Using the current beta, I have this example code:

'use strict';

/** @module util */

/**
 * @class MyClass
 * @param {string} message
 * @returns {MyClass}
 */
class MyClass {
    constructor(message) {
        /** @type {string} */
        this.message = message;
    }
}

Which is converted to

/**
 * @module util
 */
declare namespace util {
    /**
     * @class MyClass
     * @param {string} message
     * @returns {MyClass}
     */
    class MyClass {
        constructor(message: string);

    }

}

As you can see, the message property is missing.

When I use the following code (without module), this.message is not missing:

'use strict';

/**
 * @class MyClass
 * @param {string} message
 * @returns {MyClass}
 */
class MyClass {
    constructor(message) {
        /** @type {string} */
        this.message = message;
    }
}

Converted:

/**
 * @class MyClass
 * @param {string} message
 * @returns {MyClass}
 */
declare class MyClass {
    constructor(message: string);

    /**
     * @type {string}
     */
    message: string;

}

Dot notation property?

Issue coming from
phaserjs/phaser#3869

It looks like the tsd-jsdoc isn't handling dot notation properties.

Is this something in the works, or should we adjust the jsdocs to conform?

Example
GameConfig.js from Phaser

https://github.com/photonstorm/phaser/blob/master/src/boot/Config.js#L61

 * @property {*} [input.mouse.target=null] - [description]
 * @property {boolean} [input.touch=true] - [description]
 * @property {integer} [input.activePointers=1] - [description]
 * @property {*} [input.touch.target=null] - [description]

Output

https://github.com/photonstorm/phaser3-docs/blob/master/typescript/phaser.d.ts (Line 306)

    /**
     * [description]
     */
    "input.keyboard.target"?: any;
    /**
     * [description]
     */
    "input.mouse"?: boolean | object;
    /**
     * [description]
     */
    "input.mouse.target"?: any;
    /**
     * [description]
     */
    "input.touch"?: boolean;
    /**
     * [description]
     */
    "input.activePointers"?: integer;
    /**
     * [description]
     */
    "input.touch.target"?: any;

Error: Cannot read property 'length' of undefined

Hi there, while trying out tsd-jsdoc on vis.js, I got the error mentioned in the title, at this location in the code:

for (let i = 0; i < o.members.length; ++i) {   // <== Cannot read property 'length' of undefined
  if (o.members[i].kind === 'constructor') {
    ctorObj = o.members[i] as dom.ConstructorDeclaration;
  }
}

There is no urgency to have this fixed, just trying it out. But could you supply me with a workaround to continue?

On private members and overrides

I have a config here that reads

{
    "tags": {
        "allowUnknownTags": false
    },
    "source": {
        "include": [
            "./src/"
        ],
        "exclude": [],
        "includePattern": ".+\\.js(doc)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "opts": {
        "encoding"      : "utf8",
        "recurse"       : true,
        "private"       : false,
        "lenient"       : true,
        "destination"   : "./types",
        "template"      : "./node_modules/tsd-jsdoc"
    }
}

When I run this with tsd-jsdoc, it generates definitions for private members with a leading _, which will, on a production build, be renamed to something random. Is there another way to exclude them?

Also, when I /** @override */ a method with a different signature, the overridden signature seems not to be included in the output. Let's say I have a Reader that works with array-like objects and a BufferReader that partly requires a proper buffer, then this would be valuable information for a type checker.

Missing publish file.

After install from npm and trying to generate definition, have this problem.
[JSDOC] FATAL: Unable to load template: Cannot find module '.../node_modules/tsd-jsdoc/publish'

Rewrite emitter code

Need to investigate the TS2 compiler API and see if it is in a place where we can emit output using typescript itself.

If not a good alternative may be: https://github.com/RyanCavanaugh/dts-dom.

Problem on windows

It seems that somewhere in either this reporter or jsdoc itself some path doesn't get resolved correctly on windows. The mix of forward and backwards slashes usually indicate a compatibility problem

PS C:\Users\pbm\git\assetgraph> jsdoc -t node_modules/tsd-jsdoc -r lib
FATAL: Unable to load template: Cannot find module 'C:\Users\pbm\git\assetgraph\node_modules\tsd-jsdoc/publish'

Support for Arrow Functions

Currently, arrow functions expressions are interpreted as var.

export const myFunc = () => {} turns into declare var myFunc : any; when it should resolve to declare function myFunc (): void;

Should generate properties using @prop doc on class

"declare module" may need quotes

Thank you for all the work put into that great project, @englercj!
I currently develop jsdoc-tsd-webpack-plugin which generates tsd-jsdoc output and better-docs output through Webpack compilation.

array-to-object-keys is an example project from me. This is the important part:

/** @module array-to-object-keys */
// Removed for simplicity
/**
 * Converts an array to an object with static keys and customizable values
 * @example
 * arrayToObjectKeys(["a", "b"])
 * // {a: null, b: null}
 * @example
 * arrayToObjectKeys(["a", "b"], "value")
 * // {a: "value", b: "value"}
 * @example
 * arrayToObjectKeys(["a", "b"], (key, index) => `value for ${key} #${index + 1}`)
 * // {a: "value for a #1", b: "value for b #2"}
 * @param {string[]} array Keys for the generated object
 * @param {valueGenerator|*} [valueGenerator=null] Optional function that sets the object values based on key and index
 * @returns {Object<string, *>} A generated object based on the array input
 */
export default (array, valueGenerator = null) => {
// Removed for simplicity
}

tsd-jsdoc generates:

/** @module array-to-object-keys
 */
declare module array-to-object-keys {
    /**
     * Converts an array to an object with static keys and customizable values
     * @example
     * arrayToObjectKeys(["a", "b"])
     * // {a: null, b: null}
     * @example
     * arrayToObjectKeys(["a", "b"], "value")
     * // {a: "value", b: "value"}
     * @example
     * arrayToObjectKeys(["a", "b"], (key, index) => `value for ${key} #${index + 1}`)
     * // {a: "value for a #1", b: "value for b #2"}
     * @param {string[]} array Keys for the generated object
     * @param {valueGenerator|*} [valueGenerator=null] Optional function that sets the object values based on key and index
     * @returns {Object<string, *>} A generated object based on the array input
     */
    function default(array: string[], valueGenerator?: valueGenerator | any): {
        [key: string]: any;
    };
}

This looks fine, but the syntax highlighting in my VSCode looked suspicious.

The module name is not parsed correctly with those dashes. Semi-official sources like this one told me that module names need to be quoted.

Okay, I can fix this as long as JSDoc doesn't mind!

- /** @module array-to-object-keys */
+ /** @module "array-to-object-keys" */

It worked, the TSD output looks legit now, but... what is this abomination?

The underscores in the file name were one of many impacts that told me that the @module annotation is the wrong place to hack in a fix for that.

So what do you recommend? Is this a case that should be included in tsd-jsoc?

Like:

moduleName = moduleName.includes("-") ? `"${moduleName}"` : moduleName

Or did I understand something wrong on my side?

Support for @enum block tag

I have noticed that enum block tag is not recognised by the library. How would one document an object such as the following?

var Intersect = {
    OUTSIDE: -1,
    INTERSECTING: 0,
    INSIDE: 1
};

how to [overload] function

Hi, I have a problem to declare the overload function.

jscomments:

/**
 * @function 
 * @name f
 * @return {number[]}
 */
/**
 * @function 
 * @name f
 * @param {string} key
 * @return {number}
 */

the result:

/**
 * @function
 * @name f
 * @return {number[]}
 */
declare function f(): number;

expect:

declare function f(): number[];
declare function f(key:string): number;

The JSDOC default template can build both functions

f() → {Array.}
f(key) → {number}

it there any way to do like this?

TypeError: o.members is not iterable

$ npm ls | grep jsdoc
+-- [email protected]
`-- [email protected]

First up: its a bit annoying that you changed the required template path from ./node_modules/tsd-jsdoc to ./node_modules/tsd-jsdoc/dist after 2.0.0-beta.3 without mentioning it anywhere.

But my main issue is the following:

$ jsdoc -c config.json
sinusbot-scripting-docs\node_modules\tsd-jsdoc\dist\Emitter.js:183
                for (const member of o.members) {
                                       ^

TypeError: o.members is not iterable
    at Emitter._resolveObjects (sinusbot-scripting-docs\node_modules\tsd-jsdoc\dist\Emitter.js:183:40)
    at Emitter.parse (sinusbot-scripting-docs\node_modules\tsd-jsdoc\dist\Emitter.js:39:14)
    at new Emitter (sinusbot-scripting-docs\node_modules\tsd-jsdoc\dist\Emitter.js:30:14)
    at Object.publish (sinusbot-scripting-docs\node_modules\tsd-jsdoc\dist\publish.js:11:21)
    at Object.module.exports.cli.generateDocs
...

This can be reproduced by cloning SinusBot/scripting-docs, installing [email protected] and running the command provided above.

Almost forgot: you also have to change the template path in the config.json as mentioned at the beginning...

support for including original comments in d.ts file?

I'm not seeing original jsdoc comments included generated d.ts files, would this be hard to implement?

Thanks
Rich

`@constructor` or `@class` in jsdoc above a function declaration crashes

When encountering a top-level function where the @constructor or @class tag is used in the jsdoc:

/**
 * An ItemSet holds a set of items and ranges which can be displayed in a
 * range. The width is determined by the parent of the ItemSet, and the height
 * is determined by the size of the items.
 * @param {{dom: Object, domProps: Object, emitter: Emitter, range: Range}} body
 * @param {Object} [options]      See ItemSet.setOptions for the available options.
 * @constructor ItemSet
 * @extends Component
 */
function ItemSet(body, options) {
  this.body = body;
  ...
}

Crashes with exception:

/Users/macleodbroad/workspaces/vis/node_modules/dts-dom/bin/index.js:471
            switch (e.kind) {
                     ^

TypeError: Cannot read property 'kind' of null
    at writeReference (/Users/macleodbroad/workspaces/vis/node_modules/dts-dom/bin/index.js:471:22)
    at writePropertyDeclaration (/Users/macleodbroad/workspaces/vis/node_modules/dts-dom/bin/index.js:647:9)
    at writeClassMember (/Users/macleodbroad/workspaces/vis/node_modules/dts-dom/bin/index.js:630:24)
    at writeClass (/Users/macleodbroad/workspaces/vis/node_modules/dts-dom/bin/index.js:620:13)
    at writeDeclaration (/Users/macleodbroad/workspaces/vis/node_modules/dts-dom/bin/index.js:760:28)
    at Object.emit (/Users/macleodbroad/workspaces/vis/node_modules/dts-dom/bin/index.js:276:5)
    at Emitter.emit (/Users/macleodbroad/workspaces/vis/node_modules/tsd-jsdoc/Emitter.js:65:24)
    at Object.publish (/Users/macleodbroad/workspaces/vis/node_modules/tsd-jsdoc/publish.js:25:39)
    at Object.module.exports.cli.generateDocs (/usr/local/lib/node_modules/jsdoc/cli.js:448:35)
    at Object.module.exports.cli.processParseResults (/usr/local/lib/node_modules/jsdoc/cli.js:399:20)
    at module.exports.cli.main (/usr/local/lib/node_modules/jsdoc/cli.js:240:14)
    at Object.module.exports.cli.runCommand (/usr/local/lib/node_modules/jsdoc/cli.js:189:5)
    at /usr/local/lib/node_modules/jsdoc/jsdoc.js:105:9
    at Object.<anonymous> (/usr/local/lib/node_modules/jsdoc/jsdoc.js:106:3)
    at Module._compile (module.js:573:30)
    at Object.Module._extensions..js (module.js:584:10)

Can work around it by removing the @constructor or @class tag.

Built-In Non-Primitive Types

There are many built-in non-primitive types (like Promise, HTMLElement, Date, etc). Need a way to support these in the correct way where it works for all the different js environments, but also continues to warn on type resolution errors.

How can I know when a type is not in jsdoc, but will exist in the environment? Maybe I can use TypeScript global defs?

Extending generic objects

When extending a generic object, the output fails to put the template param. Additionally, it doesn't allow you to specify a template param value (specialization) in the @extends tag.

To fix this, need to refactor the object resolution to instead of being this.objects[longname] everywhere, use a utility function that can deal with the generic params.

(This may also require dts-dom updates, to enforce the rules around how generics act)

englercj / tsd-jsdoc Goto Github PK

tsd-jsdoc's People

Contributors

Stargazers

Watchers

Forkers

tsd-jsdoc's Issues

VSCode

fast-deep-equal

resource-loader

Question

Input

Output

Update 1

Recommend Projects

Recommend Topics

Recommend Org

`fast-deep-equal`

`resource-loader`