Question: how do I document a object property "interface" in pure JSDoc?

[hsablonniere]

Hey ;-)

I would really like to document all my LitElement components without using any TypeScript. I was wondering how I could document the type of an object property?

Let's consider this example:

export class TestComponent extends LitElement {

  static get properties () {
    return {
      foo: { type: Object, attribute: false },
    };
  }

}

A scan gives me this:

{
  "version": 2,
  "tags": [
    {
      "name": "test-component",
      "properties": [
        {
          "name": "foo",
          "type": "{}"
        }
      ]
    }
  ]
}

I would like wca to output "type": "MyType" and also expose the definition of MyType so it could end up in the documentation.

I tried many combinations with @type, @prop and @typedef in the JSDoc on top of the class and on top of the foo: { ...} but nothing really successful.

1. Am I the only one to be interested in this use case?
2. How can I output "type": "MyType"?
3. How can I expose the definition of MyType?
4. Can I help? ;-)

[hsablonniere]

Maybe it's a different issue but here's what I tried:

Example 1:

/**
 * @prop {MyType} foo - foo header docs
 */
export class TestComponent extends LitElement {
  static get properties () {
    return {
      foo: { type: Object, attribute: false },
    };
  }
}

Output 1:

{
  "version": 2,
  "tags": [
    {
      "name": "test-component",
      "jsDoc": "/**\n * @prop {MyType} foo - foo header docs\n */",
      "properties": [
        {
          "name": "foo",
          "type": "{}"
        }
      ]
    }
  ]
}

The documentation is missing and the type is {}.

Example 2:

/**
 * @prop {MyType} foo - foo header docs
 */
export class TestComponent extends LitElement {
  static get properties () {
    return {
      /** @type {MyType} */
      foo: { type: Object, attribute: false },
    };
  }
}

The documentation is missing and the type is any.

Example 3:

/**
 * @prop {MyType} foo - foo header docs
 */
export class TestComponent extends LitElement {
  static get properties () {
    return {
      /** foo line above docs */
      foo: { type: Object, attribute: false },
    };
  }
}

Output 3:

{
  "version": 2,
  "tags": [
    {
      "name": "test-component",
      "jsDoc": "/**\n * @prop {MyType} foo - foo header docs\n */",
      "properties": [
        {
          "name": "foo",
          "description": "foo line above docs",
          "jsDoc": "/** foo line above docs */",
          "type": "{}"
        }
      ]
    }
  ]
}

Document is picked up from line above JSDoc.

[hsablonniere]

Looking at https://github.com/runem/web-component-analyzer/blob/master/src/analyze/util/js-doc-util.ts#L83 I guess I understand why I cannot (yet) do what I want.

[runem]

Thanks for opening this issue :-)

I see two issues in what you are mentioning: (1) incorrect merging of members and (2) problems with parsing JSDoc type expressions.

1. I'm aware of this limitation, and in fact, I'm working on a local branch that among other things refactors of how merging is done. At the moment I'm spending all of my spare time on refactoring parts of WCA :-)
2. I agree that there is room for improvement in the JSDoc type expression parser. It seems, however, like the "type" field of the custom-elements.json is going to be a 'type hint' (just a string), so in the end I would be able to return just the raw string of the JSDoc type expression with no need for parsing it :+1:

[hsablonniere]

1. Great news, thanks for the effort ;-)
2. Awesome. I'll be able to manually describe what is MyType in markdown prose (and maybe find a way to extract and automate that later).

I'm available to review any local branch or something if it can help.

[runem]

I'll be committing my work to the refactor branch very soon. At the same time I'll create an issue that describes the changes to the member-merging logic with examples. It would be great to have your feedback on that! :-) I'll remember to tag you when I create the issue :+1:

[runem]

I created the issue here https://github.com/runem/web-component-analyzer/issues/125 :-)

[runem]

Version 1.0.0 is live with the fix :tada: