runem / web-component-analyzer

CLI that analyzes web components and emits documentation
https://runem.github.io/web-component-analyzer
MIT License
504 stars 64 forks source link

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

Closed hsablonniere closed 4 years ago

hsablonniere commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago
  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 commented 4 years ago

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 commented 4 years ago

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

runem commented 4 years ago

Version 1.0.0 is live with the fix :tada: