Documenting Vue 3 components / Pinia stores

[pkgw]

Search terms

Vue, Pinia, components

Question

I have a package that uses TypeScript and Vue 3. We define a component class using Vue.defineComponent(), which has a complex type signature but is basically returning a constructor for a class whose properties are defined by the function arguments.

Unfortunately, Typedoc interprets the resulting value as a variable with a type that, in my case, is unreadable:

https://docs.worldwidetelescope.org/webgl-reference/latest/apiref/engine-pinia/variables/WWTAwareComponent.html

Is there a way to get this to show up as a proper class instead? I wouldn't be surprised if a plugin was required, but I've searched around and nothing seems to be available. I'm willing to contemplate writing one, but if there's a different documentation system that would handle this case better, that might honestly be the better approach :-/

Would there perhaps be some way to define a type associated with typeof WWTAwareComponent that could express it as a documentable class? Or some other workaround?

Similarly we have a variable created via pinia.defineStore() that also fails badly:

https://docs.worldwidetelescope.org/webgl-reference/latest/apiref/engine-pinia/functions/engineStore.html

Here, there seems to be some type inference happening so that TypeDoc decides to categorize this variable as a function.

If it's useful, here's the source code: WWTAwareComponent, engineStore.

Thanks for any advice.

[Gerrit0]

export class WWTAwareComponent extends defineComponent({}) {}

May be better, though in general, highly dynamic code like this is nearly impossible to document in a reasonable way for all cases. A while ago I threw together a plugin which uses {@displayType} to tell TypeDoc what should be displayed as the type. #2273.

The @interface tag also exists, which tells TypeDoc to try to statically resolve all properties of a type, but it was intended for type aliases, not values, so won't work in this case... There's also @namespace, but the pinia store at least seems like it ought to actually be documented as a variable. I'm not opposed to adding a tag for this... @resolve? I'd prefer something more explicit...

[pkgw]

The class ... extends... approach seems to work shockingly well! If I could combine it with @interface, I think that would basically get me there, but I don't think I can because TypeScript cares about the difference between class methods and properties that are functions:

export interface WWTAwareComponent {
  startTour(): void; // just one sample function as a test
}

leads to

Class '[long unreadable stuff]' defines instance member property 'startTour', but extended class 'WWTAwareComponent' defines it as instance member function.

(And I don't think I can use an abstract class since I'd need multiple inheritance, I think ...)

edit: ah, startTour: () => void; kind of works, but it gets documented as a property and is annotated with Inherited from defineComponent([entire complex set of function args]), which is close to a dealbreaker.

[Gerrit0]

I got nerd sniped... https://github.com/Gerrit0/typedoc-plugin-vue should make your docs a lot nicer without needing the class extends defineComponent workaround

[pkgw]

Incredible, thank you! With a little bit of futzing I was able to use your new plugin to get our docs back in order.