Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
hsablonniere opened this issue Nov 20, 2019 · 7 comments
Closed

Comments

@hsablonniere
Copy link

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
Copy link
Author

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
Copy link
Author

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
Copy link
Owner

runem commented Nov 20, 2019

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 👍

@hsablonniere
Copy link
Author

  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
Copy link
Owner

runem commented Nov 21, 2019

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 👍

@runem
Copy link
Owner

runem commented Nov 22, 2019

I created the issue here #125 :-)

This was referenced Nov 27, 2019
@runem
Copy link
Owner

runem commented Dec 12, 2019

Version 1.0.0 is live with the fix 🎉

@runem runem closed this as completed Dec 12, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants