webdoc-labs / webdoc Goto Github PK

Received the following crash error:

(node:47460) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'name' of undefined

when attempting to use rest parameters, here's an example:

const { maxValue, ...options } = { maxValue: 1, foo: 'bar', bar: 'baz' };

JSDoc allows constructor params if they appear in the same doc as the @class declaration. This is not supported in Webdoc.

Example: http://pixijs.download/dev/docs/PIXI.BaseTexture.html (missing constructor)
Source: http://pixijs.download/dev/docs/packages_core_src_textures_BaseTexture.ts.html#line44

Description

If you have a parent class that uses function overloading, only the first method is shown on classes that extend it. This was discovered while working on this: pixijs/pixijs#7633

Reproduction

https://github.com/bigtimebuddy/webdoc-overload-bug

• Docs global explorer should be unfolded to current Doc.
• Members explorer should track current scroll state.

Webdoc does not property infer types for interfaces in TypeScript. Here's an example. The paused property shows up correctly in the docs, but without a type.

/** Description */
interface IMediaInstance
{
    /** Property description */
    paused: boolean;
}

Workaround:

/** Description */
interface IMediaInstance
{
    /**
     * Property description
     * @type {boolean}
     */
    paused: boolean;
}

JSDoc had the ability to document multiple signatures for the same method. We used this a lot in PixiJS. Here's just one example for lineStyle:

• Doc: http://pixijs.download/dev/docs/PIXI.Graphics.html#lineStyle
• Source: http://pixijs.download/dev/docs/packages_graphics_src_Graphics.ts.html#line333

As you can see the second API does not show up correctly.

Detection of the getter's return type and readonly (no setter) not working.

/** Get the duration of the audio in seconds. */
public get duration(): number
{
    return this._duration;
}

Workaround is to explicitly add the type.

/**
 * Get the duration of the audio in seconds.
 * @type {number}
 * @readonly
 */
public get duration(): number
{
    return this._duration;
}

Not sure if this is a bug or an issue with the template, but it different from 1.2.0. In attempting to render interfaces, the "description" field is now missing in the table list of properties.

Before

After

Was having a difficult time documenting interface types as typedef. Here's the example:

/**
 * @memberof PIXI
 * @typedef {object}
 * @property {function} init - Called when Application is constructed, scoped to Application instance.
 *  Passes in `options` as the only argument, which are Application constructor options.
 * @property {function} destroy - Called when destroying Application, scoped to Application instance
 */
export interface IApplicationPlugin {
    init: (...params: any[]) => any;
    destroy: (...params: any[]) => any;
}

This produces a crash when trying to build:

(node:11151) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'steps' of undefined
    at query ([...]/pixi.js/node_modules/@webdoc/model/lib/query/query.js:17:13)
    at LinkerPluginImpl.linkTo ([...]/pixi.js/node_modules/@webdoc/template-library/lib/template-plugins/LinkerPlugin.js:156:23)
    at eval (lodash.templateSources[0]:101:16)
    at Array.forEach (<anonymous>)
    at eval (lodash.templateSources[0]:98:14)
    at Array.forEach (<anonymous>)
    at TemplateRenderer.eval (lodash.templateSources[0]:13:10)
    at TemplateRenderer.partial ([...]/pixi.js/node_modules/@webdoc/template-library/lib/TemplateRenderer.js:128:38)
    at TemplateRenderer.render ([...]/pixi.js/node_modules/@webdoc/template-library/lib/TemplateRenderer.js:140:24)
    at TemplatePipeline.render ([...]/pixi.js/node_modules/@webdoc/template-library/lib/TemplatePipeline.js:23:32)

Workaround

Putting the typedef after the interface and adding the name to typedef didn't break building.

export interface IApplicationPlugin {
    init: (...params: any[]) => any;
    destroy: (...params: any[]) => any;
}

/**
 * @memberof PIXI
 * @typedef {object} IApplicationPlugin
 * @property {function} init - Called when Application is constructed, scoped to Application instance.
 *  Passes in `options` as the only argument, which are Application constructor options.
 * @property {function} destroy - Called when destroying Application, scoped to Application instance
 */

Hello, I faced with this issue

Rendering template: /project/node_modules/@pixi/webdoc-template/tmpl/method.tmpl
Rendering template: /project/node_modules/@pixi/webdoc-template/tmpl/container.tmpl
(node:29059) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'cssClass' of null
    at LinkerPluginImpl.linkTo (/project/node_modules/@pixi/webdoc-template/node_modules/@webdoc/template-library/lib/template-plugins/LinkerPlugin.js:147:35)
    at TemplateRenderer.eval (lodash.templateSources[5]:60:16)
    at TemplateRenderer.partial (/project/node_modules/@pixi/webdoc-template/node_modules/@webdoc/template-library/lib/TemplateRenderer.js:128:38)
    at eval (lodash.templateSources[0]:295:16)
    at Array.forEach (<anonymous>)
    at eval (lodash.templateSources[0]:293:11)
    at Array.forEach (<anonymous>)
    at TemplateRenderer.eval (lodash.templateSources[0]:13:10)
    at TemplateRenderer.partial (/project/node_modules/@pixi/webdoc-template/node_modules/@webdoc/template-library/lib/TemplateRenderer.js:128:38)

If I add @memberof to class it is working

Also I'm not sure that problem relates to @memberof only. Because I'm converting to webdoc very big project and fix error step by step

@bigtimebuddy requested the following formats for template links be added to webdoc to match JSDoc's feature set:

• {@link <url> <text>}
• {@link <url> | <text>}

For new I just included scss files into project from https://github.com/Zekfad/scss-utils
When the upstream issue will be resolved we can move it into submodule, in order to mitigate manual updating of scss-utils.

microsoft/rushstack#1711

These error keep popping up for me when I built the docs.

[DocParser]: Failed to parse doc for (@Unnamed){@packages/basis/src/Basis.ts<118, 0>}
[DocParser]: Failed to parse doc for (@Unnamed){@packages/basis/src/Basis.ts<135, 0>}
[DocParser]: Failed to parse doc for (@Unnamed){@packages/basis/src/Basis.ts<145, 0>}
[DocParser]: Failed to parse doc for (@Unnamed){@packages/compressed-textures/src/loaders/CompressedTextureLoader.ts<6, 0>}
[DocParser]: Failed to parse doc for (@Unnamed){@packages/compressed-textures/src/loaders/CompressedTextureLoader.ts<18, 0>}
[DocParser]: Failed to parse doc for (@Unnamed){@packages/compressed-textures/src/resources/CompressedTextureResource.ts<7, 0>}

All these instances are all trying to document type. Here's an example.

/**
 * API provided by basis_universal WebGL library.
 *
 * @ignore
 */
export type BasisBinding = {
    BasisFile: typeof BasisFile,
    initializeBasis(): void
};

Changing this to the following made it go away:

/**
 * API provided by basis_universal WebGL library.
 *
 * @typedef {object} BasisBinding
 * @ignore
 */
export type BasisBinding = {
    BasisFile: typeof BasisFile,
    initializeBasis(): void
};

Here we have two examples of the same code. The first example adds the type : boolean and the second omits. We are enforcing a lint rule to hide type annotations for basic values @typescript-eslint/no-inferrable-types. Would be nice to infer basic types based on booleans, strings and numbers.

👍 Type Correct in Webdoc

/**
 * Setting this to true will visually show the divs.
 *
 * @default false
 */
public debug: boolean = false;

❌ Type Missing in Webdoc

/**
 * Setting this to true will visually show the divs.
 *
 * @default false
 */
public debug = false;

JSDoc had a @readonly tag (it also supported the @readOnly variant), this would set a flag on the doc which could be used by the template to display if a property is writable or not. This should probably be a first-class citizen both to support backward compatibility with JSDoc, but also so that we could infer readonly from a few situations such as these:

TypeScript keyword

class MyClass {
  /** Should infer `readonly` status from the TS access. */
  static readonly PROP: number = 20;
}

Using const

/**
 * Also, const objects are readonly, this should also infer.
 */
const MyObj: any = {};

Getter with no Setter

class MyClass {
  /** If no setter, should be readonly as well */
  get name(): string {
    return "";
  }
}

Here's a reproduction:
https://github.com/bigtimebuddy/webdoc-ignore-bug

Example

In this example multiple classes are ignored, but the first still shows up in the docs. I expect to see none of these classes.

/**
 * @ignore
 */
export class FirstIgnoreClass {}

/**
 * @ignore
 */
export class SecondIgnoreClass {}

/**
 * @ignore
 */
export class ThirdIgnoreClass {}

Actual Result

Output export looks like this. FirstIgnoreClass is still exported.

{
	"version": "1.0.0",
	"metadata": {
		"linker": "(unsigned)",
		"siteRoot": ""
	},
	"root": {
		"id": "root-UnV77xJ2i155q76tLrj6R",
		"name": "",
		"type": "RootDoc",
		"members": [{
			"id": "Lpv4DtLjtOa78bc6Ijg6R",
			"name": "FirstIgnoreClass",
			"brief": "",
			"type": "ClassDoc",
			"members": [{
				"id": "SMzxRTXGkwVQvmxSZS8jC",
				"name": "constructor",
				"brief": "",
				"access": "public",
				"scope": "instance",
				"type": "MethodDoc"
			}]
		}]
	},
	"registry": {
		"Lpv4DtLjtOa78bc6Ijg6R": {
			"uri": "FirstIgnoreClass.html"
		},
		"SMzxRTXGkwVQvmxSZS8jC": {
			"uri": "FirstIgnoreClass.html#constructor"
		}
	}
}

Workaround

Using @private, while still exports to the class, will hide it from the template.

For now it's hard to find out what fails the build if it's not javascript:

• SCSS: error stacktrace omitted
• Templates: just pain error (e.g. Syntax Error <) nothing more

Notes:

• For scss it's possible to catch unhandledexception and see the error.

Hi!
I use latest versions of @pixi/webdoc-template and webdoc
@pixi/webdoc-template uses webdoc 1.1.3,
I cant understand where issue comes from, but

this code inside linkTo function

const classString = options.cssClass ? ` class="${options.cssClass}"` : "";

fails with error TypeError: Cannot read property 'cssClass' of null;

To fix it locally I just added additional check for options, but maybe you have Idea how to fix it correctly

Source code links next to methods no longer render correctly.

Actual:
http://pixijs.download/dev/docs/PIXI.Application.html#registerPlugin

Expected:
http://pixijs.download/v6.1.3/docs/PIXI.Application.html#registerPlugin

Template source:
https://github.com/pixijs/webdoc-template/blob/d2a76af81311615d8af1b0cb7ebd85508cf715ea/tmpl/method.tmpl#L35-L39

This doesn't not detect private modifier.

/** Description */
private _onPlay(): void
{
    this._playing = true;
}

Workaround:

/**
 * Description
 * @private
 */
private _onPlay(): void
{
    this._playing = true;
}

Has integration with tsdoc been considered?

The margins are hard coded, change it to use flexbox.
Also, add media queries to remove the side bar for mobile devices.

Caused pixijs/webdoc-template#3

Currently, the docs.sort option in the CLI accepts a string for determining the sort order, e.g. "access, scope".

However, it's much easier to parse, validate, provide type-safety, and offer auto-completion in the IDE when the expected type is an array of enumerated valid strings.

In TypeScript (not sure about Flow):

type SortProp = 'access' | 'scope' | 'type' | 'name'
type Sort = Array<SortProp>

const sort: Sort = ['acess'] // oops!

instead of

type Sort = string

const sort: Sort = 'acess, foo, bar' // only runtime error

In JSON schema:

    "sort": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["access", "scope", "type", "name"],
        "uniqueItems": true
      },
      "description": "An array of properties to sort by. Valid properties are: “access”, “scope”, “type” and “name”."
    }

instead of

        "sort": {
          "type": "string",
          "description": "A comma-separated string of properties to sort by. Valid properties are: “access”, “scope”, “type” and “name”."
        }

Not sure what the deprecation policies are at this young stage of the project, but it wouldn't be difficult to support both for a while and print a warning that the string syntax will be removed in the next major version.

I have a directory with classes (for all pages), but not all of them are listed in the class index.

1. Every file that has been named as xxxx_yyyy.js is missing, if there is a xxxx_yyyy_zzzz.js
2. But also I have completely missing files, I have 4 similar files, starting with content_ but only 1 shows in the index.

Secondly, I have class inheritance and methods that exists in different classes, somehow the signature does not take that into account and thinks all method names are unique system wide.
Is there a configuration option that I have missed ?

Causes pixijs/webdoc-template#4

We're getting the following error on our codebase.

Babel couldn't parse file in @webdoc/parser (libs/...component.ts)
C:\...\nvm\v15.4.0\node_modules\@webdoc\cli\node_modules\@babel\parser\lib\index.js:748
    const err = new SyntaxError(message);
                ^
SyntaxError: This experimental syntax requires enabling one of the following parser plugin(s): 'decorators-legacy, decorators' (11:0)

Obviously, the babel parser is missing the decorators and/or decorators-legacy plugin, but I can't figure out how to influence the used babel plugins.

I've checked out source code for @webdoc/parser and saw the babel config file.

But I don't see any way to influence this, so I'm not sure if this issue is a simple question or missing docs or missing feature 😄

Broken

This version shows up correctly in the docs, but is incorrectly tagged as static. This should be an instance method as indicated by @instance.

/**
 * @instance
 * @method PIXI.Graphics#drawChamferRect
 */

Workaround

Tweaking this slightly produce the correct result.

/**
 * @instance
 * @memberof PIXI.Graphics
 * @method drawChamferRect
 */

Related: https://github.com/pixijs/pixi.js/pull/7256/files

I wanted to try this project, but after being met with these messages during the install I will stay away (for now)...

npm install -g @webdoc/cli
npm WARN deprecated [email protected]: gulp-util is deprecated - replace it, following the guidelines at https://medium.com/gulpjs/gulp-util-ca3b1f9f9ac5
npm WARN deprecated [email protected]: https://github.com/lydell/resolve-url#deprecated
npm WARN deprecated [email protected]: Please see https://github.com/lydell/urix#deprecated
npm WARN deprecated [email protected]: fsevents 1 will break on node v14+ and could be using insecure binaries. Upgrade to fsevents 2.
npm WARN deprecated [email protected]: Chokidar 2 will break on node v14+. Upgrade to chokidar 3 with 15x less dependencies.

pixijs/pixijs#7001

In TypeScript is valid to add access modifiers to the constructor arguments like this:

constructor(protected renderer: any) {}

Supports public, private, protected, and readonly.

Webdoc does not parse these arguments correctly. Resulting in a stack like this:

(node:4625) UnhandledPromiseRejectionWarning: Error: "renderer" is not a parameter & cannot come after the last parameter ""
    at Object.validateParameters [as validate] (/home/runner/work/***/***/node_modules/@webdoc/parser/lib/validators/validate-parameters.js:38:13)
    at /home/runner/work/***/***/node_modules/@webdoc/parser/lib/validators/index.js:22:45
    at Array.forEach (<anonymous>)
    at validate (/home/runner/work/***/***/node_modules/@webdoc/parser/lib/validators/index.js:22:14)
    at symbolToDoc (/home/runner/work/***/***/node_modules/@webdoc/parser/lib/transformer/symbol-to-doc.js:215:29)
    at transformRecursive (/home/runner/work/***/***/node_modules/@webdoc/parser/lib/transformer/transform.js:19:40)
    at transformRecursive (/home/runner/work/***/***/node_modules/@webdoc/parser/lib/transformer/transform.js:35:7)
    at transformRecursive (/home/runner/work/***/***/node_modules/@webdoc/parser/lib/transformer/transform.js:35:7)
    at parse (/home/runner/work/***/***/node_modules/@webdoc/parser/lib/parse.js:110:28)
    at main (/home/runner/work/***/***/node_modules/@webdoc/cli/lib/index.js:125:23)

Reference: https://www.typescriptlang.org/docs/handbook/classes.html#parameter-properties

Not sure if I'm missing something here, but after cloning and installing rush (first time I hear about it, so could be I'm missing something that should've been obvious) and running rush build, I'm getting the example/docs folder with certainly something, but after opening the browser I get a bunch of 404s and missing MIME types.

live-server's output is also complaining:

Currently we just hope that the developer provided a valid configuration object, without checking it. We should add a runtime check for this, and throw a nice error. As is, providing the configuration to the CLI is prone to typos and difficult-to-debug missing behaviors, given that there's no autocomplete in IDEs for the webdoc.conf.json file.

Both of these issues can be solved by providing and exposing a JSON schema -- IDEs could use it to autocomplete and show hints to the developer, and we could use it internally to validate the object against it. It's also a universal documentation language which serves as the source of truth for what the configuration should and shouldn't contain.

Documentation link's that use instance-notation (i.e., #), do not render correctly. It will just show the plain text. Reproducible example can be seen here (search for PIXI.Container#renderAdvanced under Usage, should be a proper link). Also, can be seen here.

When investigating it seems like {@link SomeClass#member} does not render, however, {@link SomeClass.member} does work. The internal list of docPath to URLs does not distinguish between instance or static properties.

Screenshot

Here's a snippet of the internal Map used to generate the links. Most of these should be instance properties not static.

For example, when you change package version, doc rebuild cause additional git diffs, which are actually makes no sense for documentation.
It would be great to make for example metadata.js which will contain such data (e.g. version, module description, last git commint, etc.) and load it on-demand within webpage.
Drawback is that no-js browsers wont be able to see that data.
Here's example of changes in docs, which are makes no sense in terms of documentation: Zekfad/ueue@f10682f

isSamePage helper does not handle default pages well for selecting the ExplorerItem. For instance:

Example

Example: https://pixijs.io/guides/
Notice that "Welcome" IS NOT selected

Example: https://pixijs.io/guides/index.html
Notice that "Welcome" IS selected

Problem

This originates from this logic in the default-template.

When I console.log('isSamePage', data.page, path); with in that function I get:

isSamePage /guides/index.html /guides/.html

It returns false when it should be true.

Details: pixijs/pixijs#6912

I just realized that in the master branch:

/**
 * @typedef {Array} VectorArray
 */

produces a doc named (unnecessary whitespace)

 VectorArray

instead of

VectorArray

That causes a whole class of issues with templates. This needs to be fixed strictly before a release.

Trying to reorganize the documentation in PixiJS so that member documentation is at the class-level. Historically with JSDoc these were added in the constructor when the property was initialized.

Here's an example of what I'd like to do:

class MyClass {
  /** Run in debug mode. */
  public debug: boolean = false;
}

I would expect the output from webdoc to infer the type and default from the TypeScript definition, but it does not.

This, however, works fine:

class MyClass {
  /**
   * Run in debug mode.
   * @type {boolean}
   * @default false
   */
  public debug: boolean = false;
}

One quick note: access-modifiers are handled correctly (public, private, protected).

We have to add type annotations into new default template PR (#24).
I haven't used flow before, so it would be better if @SukantPal work on that, please.

We tried running webdoc with the webdoc.conf.json from the main README, but we encountered the following error.

Babel couldn't parse file in @webdoc/parser (node_modules/cjs-module-lexer/lexer.js)
C:\...\nvm\v15.4.0\node_modules\@webdoc\cli\node_modules\@babel\parser\lib\index.js:748
    const err = new SyntaxError(message);
                ^
SyntaxError: Unexpected token, expected ")" (292:25)
    at _temp._raise (C:\...\nvm\v15.4.0\node_modules\@webdoc\cli\node_modules\@babel\parser\lib\index.js:748:17)
    at _temp.raiseWithData 
  ....
  loc: Position { line: 292, column: 25 },
  pos: 9107
}

The main issue here is that it's not obvious which file has the supposed syntax error. Note that our code is written in TypeScript. We just changed the default top-level "includePattern": ["src/**/*.js"], to "includePattern": ["libs/**/*.ts"],.

Apparently, the actual lexer from the first line node_modules/cjs-module-lexer/lexer.js is parsed wrongly with babel. The pointed line 292:25 is this:

if (ch !== 58/*:*/) break;

It looks like the parses hicks up on the comment (* is the 25th column), and misinterprets it, but it seems weird that a stable parser such as babel would produce this error. Maybe it's an error without our code after all (since our code also doesn't actually work, see #83), but I can't figure it out.

So although I'm unsure why this happens, the simple fix/workaround is to ignore the node_modules folder (I'm unsure why was it even included in the documentation generation step?), using the config we found on the pixi repository:

https://github.com/pixijs/pixi.js/blob/72cb457a2e92dc9bc3f0158562938069f7ea788d/webdoc.conf.json#L5-L12

I'm also not sure where can I find the full documentation for the config file.

If @returns annotation doesn't have type it crashes with this error

(node:29113) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'dataType' of undefined
    at mergeReturns (/project/node_modules/@webdoc/parser/lib/transformer/merge-returns.js:13:

According https://jsdoc.app/tags-returns.html it is optional

On running npm run generate, I got the following at the output.

[02:30:22] Finished 'build' after 4.49 s
car doesn't point to a doc
road doesn't point to a doc
undefined doesn't point to a doc
ford doesn't point to a doc

Car and road appear in the output, but ford seems missing.

Will work on this myself.

When a negative number is set it does not appear in the documentation as the default value

e.g.

 public lastTime = -1;

This happens because of how the Class-Index.html URI is passed to getURI (should be just Class-Index).

Hello!

I've migrated to latest version of webdoc. In generated output I see that all links to files prefixed with packageName in package.json. When I tested migration with webdoc 1.2.0 everything worked.
How to get previous behavior?

Version 1.2.1 should contain fix for bug #105
But if you install latest version of @webdoc/template-library and look at LinkerPlugin.js - you will not see that fix there
Presumably it was published incorrectly