Webdoc Issues

[bigtimebuddy]

On dev, there are some issues run npm run docs. It's unclear about where they are coming from. Some of the TransformFeedback tag issues should be easy to fix though.

[Indexer]: Parameter node couldn't be parsed, enable warning logs for more detail
[Indexer]: {
  "type": "ArrayPattern",
  "start": 1175,
  "end": 1180,
  "loc": {
    "start": {
      "line": 37,
      "column": 17,
      "index": 1175
    },
    "end": {
      "line": 37,
      "column": 22,
      "index": 1180
    }
  },
  "elements": [
    {
      "type": "Identifier",
      "start": 1176,
      "end": 1179,
      "loc": {
        "start": {
          "line": 37,
          "column": 18,
          "index": 1176
        },
        "end": {
          "line": 37,
          "column": 21,
          "index": 1179
        },
        "identifierName": "key"
      },
      "name": "key"
    }
  ]
}
[Indexer]: Parameter node couldn't be parsed, enable warning logs for more detail
[Indexer]: {
  "type": "ArrayPattern",
  "start": 1228,
  "end": 1239,
  "loc": {
    "start": {
      "line": 38,
      "column": 18,
      "index": 1228
    },
    "end": {
      "line": 38,
      "column": 29,
      "index": 1239
    }
  },
  "elements": [
    {
      "type": "Identifier",
      "start": 1229,
      "end": 1232,
      "loc": {
        "start": {
          "line": 38,
          "column": 19,
          "index": 1229
        },
        "end": {
          "line": 38,
          "column": 22,
          "index": 1232
        },
        "identifierName": "key"
      },
      "name": "key"
    },
    {
      "type": "Identifier",
      "start": 1234,
      "end": 1238,
      "loc": {
        "start": {
          "line": 38,
          "column": 24,
          "index": 1234
        },
        "end": {
          "line": 38,
          "column": 28,
          "index": 1238
        },
        "identifierName": "type"
      },
      "name": "type"
    }
  ]
}
[DocParser]: Failed to parse doc for (@Unnamed)(in /home/runner/work/pixijs/pixijs/packages/basis/src/Basis.ts at 113:0)
[DocParser]: Failed to parse doc for (@Unnamed)(in /home/runner/work/pixijs/pixijs/packages/basis/src/Basis.ts at 129:0)
[DocParser]: Failed to parse doc for (@Unnamed)(in /home/runner/work/pixijs/pixijs/packages/basis/src/Basis.ts at 138:0)
[DocParser]: Failed to parse doc for (@Unnamed)(in /home/runner/work/pixijs/pixijs/packages/core/src/index.ts at 13:0)
[DocParser]: Failed to parse doc for (@Unnamed)(in /home/runner/work/pixijs/pixijs/packages/events/src/EventBoundary.ts at 53:0)
Catharsis failed to parse: Object<string, string | ((mode: string) => void) | CSSStyleDeclaration>
[DocParser]: Failed to parse doc for (@Unnamed)(in /home/runner/work/pixijs/pixijs/packages/utils/src/url.ts at 1:0)
Catharsis failed to parse: [number, number] | null
[DocParser]: Failed to parse doc for (@Unnamed)(in /home/runner/work/pixijs/pixijs/packages/assets/src/resolver/types.ts at 44:0)
[DocParser]: Failed to parse doc for (@Unnamed)(in /home/runner/work/pixijs/pixijs/packages/compressed-textures/src/loaders/compressedTextureExtensions.ts at 2:0)
[DocParser]: Failed to parse doc for (@Unnamed)(in /home/runner/work/pixijs/pixijs/packages/compressed-textures/src/resources/CompressedTextureResource.ts at 7:0)
[TagParser]:{@TransformFeedback.bindBuffer} Parameter "index" does not have a "-" token preceeding description <index to bind>
[TagParser]:{@TransformFeedback.bindBuffer} Parameter "buffer" does not have a "-" token preceeding description <buffer to bind>
[TagParser]:{@TransformFeedbackSystem.bind} Parameter "transformFeedback" does not have a "-" token preceeding description <TransformFeedback to bind>
[TagParser]:{@TransformFeedbackSystem.beginTransformFeedback} Parameter "drawMode" does not have a "-" token preceeding description <DrawMode for TransformFeedback>
[TagParser]:{@TransformFeedbackSystem.beginTransformFeedback} Parameter "shader" does not have a "-" token preceeding description <A Shader used by TransformFeedback. Current bound shader will be used if not provided.>
[TagParser]:{@TransformFeedbackSystem.createGLTransformFeedback} Parameter "tf" does not have a "-" token preceeding description <TransformFeedback>

@ShukantPal any thoughts on the Indexer issues?

[SuperSodaSea]

[Indexer]: Parameter node couldn't be parsed, enable warning logs for more detail
[Indexer]: {
  "type": "ArrayPattern",
...

Is caused by:

pixijs/packages/assets/src/AssetExtension.ts

Lines 37 to 38 in 834af94

	.filter(([key]) => !!ref[key as AssetType])
	.forEach(([key, type]) => extensions.add(Object.assign(

I think this is a @webdoc/cli bug.

https://github.com/webdoc-labs/webdoc/blob/49345485f4ed6df758980173ee74bd40691fa21d/language/language-babel/src/extract-metadata.js#L280-L285

    } else {
      ((params: any)).flawed = true;
      log.error(tag.Indexer, "Parameter node couldn't be parsed, " +
          "enable warning logs for more detail");
      log.warn(tag.Indexer, JSON.stringify(paramNode, null, 2));
    }

@webdoc/cli didn't take care or isArrayPattern here, causing the error.

[ShukantPal]

@SuperSodaSea That's correct. I'll have to implement array pattern parameters. @bigtimebuddy I'll find time over the weekend to get this one done.

[SuperSodaSea]

Catharsis failed to parse: Object<string, string | ((mode: string) => void) | CSSStyleDeclaration>
Catharsis failed to parse: [number, number] | null

These two errors caused by:

pixijs/packages/events/src/EventSystem.ts

Lines 75 to 77 in cbfb473

	* @member {Object<string, string | ((mode: string) => void) | CSSStyleDeclaration>}
	*/
	public cursorStyles: Record<string, string | ((mode: string) => void) | CSSStyleDeclaration>;

pixijs/packages/canvas-graphics/src/utils/PolygonUtils.ts

Lines 92 to 97 in cbfb473

	* @returns {[number, number] | null} - [x, y] coordinates of intersection
	*/
	static findIntersection(
	x1: number, y1: number, x2: number, y2: number,
	x3: number, y3: number, x4: number, y4: number
	): [number, number] | null

Seems that these types are invalid in JSDoc. I tried to remove the invalid type in the doc, and find out that webdoc can automatically get the type from the TypeScript code, with no lint error (PloygonUtils is @private, so I removed @private temporarily to get the screenshot):

So I think we can just remove the invalid types. Will make a PR later.

[SuperSodaSea]

Deprecated as of 10.7.0. highlight(lang, code, ...args) has been deprecated.
Deprecated as of 10.7.0. Please use highlight(code, options) instead.
https://github.com/highlightjs/highlight.js/issues/2277

This warning is caused by an old version 3.4.0 of markdown-it-highlightjs used in @pixi/webdoc-template. markdown-it-highlightjs fix this problem in 3.5.0 (valeriangalliat/markdown-it-highlightjs#20), so we just need to bump the version of markdown-it-highlightjs in the dependency of @pixi/webdoc-template.

Will fix in pixijs/webdoc-template#22.

[SuperSodaSea]

[DocParser]: Failed to parse doc for (@Unnamed)(in /home/runner/work/pixijs/pixijs/packages/core/src/index.ts at 13:0)
[DocParser]: Failed to parse doc for (@Unnamed)(in /home/runner/work/pixijs/pixijs/packages/utils/src/url.ts at 1:0)

These two are caused by useless /**:

pixijs/packages/core/src/index.ts

Lines 13 to 15 in cbfb473

	/** Export dependencies */
	export * from '@pixi/constants';
	export * from '@pixi/extensions';

pixijs/packages/utils/src/url.ts

Lines 1 to 6 in cbfb473

	/**
	* This file contains redeclared types for Node `url` and `querystring` modules. These modules
	* don't provide their own typings but instead are a part of the full Node typings. The purpose of
	* this file is to redeclare the required types to avoid having the whole Node types as a
	* dependency.
	*/

They can be fix by simply replacing /** with /* or /*.

---

All other [DocParser]: Failed to parse doc for (@Unnamed) are caused by code like this:

/** ... */
type Foo = ...;

For example:

pixijs/packages/basis/src/Basis.ts

Lines 113 to 118 in cbfb473

	/**
	* Compressed texture extensions relevant to the formats into which Basis can decompress into.
	* @ignore
	*/
	/* eslint-disable camelcase */
	export type BasisTextureExtensions = {

Seems that @webdoc/cli can't deal with the type declaration. More investigation is needed.

[bigtimebuddy]

I bumped @pixi/webdoc-template @SuperSodaSea. Also, I'm in favor of the quick fix in some of these to change /** to /* to silence some of these warnings.

[SuperSodaSea]

@bigtimebuddy Thanks, I tried @pixi/webdoc-template version 1.5.4 and the highlight.js warnings are gone.
I will make a PR later including the fixes I mentioned above (and bump @pixi/webdoc-template).

[SuperSodaSea]

Gotcha! Implementing a isTSTypeAliasDeclaration branch in the extractSymbol function in @webdoc/language-babel can probably solve the remaining [DocParser]: Failed to parse doc for (@Unnamed) caused by /** ... */ type Foo = {}:

https://github.com/webdoc-labs/webdoc/blob/a52570c22fc3161e1f19f4997eb96081d1ea9d34/language/language-babel/src/extract-symbol.js#L66-L367

@ShukantPal Can you confirm this?

[ShukantPal]

@SuperSodaSea Yep, you've got it