search

runem / web-component-analyzer

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

Improve output for union type aliases #140

Closed telpalbrox closed 4 years ago

telpalbrox commented 4 years ago

Hello, we are using web-component-analyzer to generate the documentation for our design system built with lit-element. Right now we have a lot of type aliases to define that an attribute/property can have only a fixed set of values like this one:

type ButtonSize = "normal" | "small" | "large" | "none" | "extra-small";

The thing is that the output of web-component-analyzer for this case is that the attribute/property is type ButtonSize which is not really helpful for people who is reading the documentation online without reading the source.
I saw also in some repositories that maybe this is not the best behavior when the type has a lot of different options, maybe this can be enabled or disabled somehow? Any thoughts on that?

I think that maybe it would be really handy that, in the case we have an alias that is a union type composed only of strings literals, to print the value of those strings literals like: "normal" | "small" | "large" | "none" | "extra-small". This is exactly what is already happening when a union type is used but is not aliased, like in this case:

@property() size:  "normal" | "small" | "large" | "none" | "extra-small" = "normal";

What do you think about this change? Do you think it makes sense?

I know that how the value is printed is handled by ts-simple-type but for this case I think it doesn't make sense to do it there. I was already taking a look about how to implement it and I would be willing to provide a pull request 😄

justinfagnani commented 4 years ago

I would really like to see the type still be named as ButtonSize and output a reference to a definition of the ButtonSize type. This is especially useful when the type is used in multiple places. A documentation viewer can dereference / inline the member types if desired.

runem commented 4 years ago

@justinfagnani I can definitely see the need for both options. When outputting the markdown-format, some people might want to document their types separately and other people might want to expand and inline all types. Personally, I only see this as valuable when outputting the markdown-format, and perhaps inlining types shouldn't even be an option when outputting the json-format.

I'll introduce this functionality through a CLI option called --inline-types. This also avoid introducing a breaking change to WCA :-)