documentation

documentation copied to clipboard

/**
  */
class Foo {..}

will generate doc with a code block:

new Foo()

Similarly, functions will generate an automatic block.

I have 2 usecases where I want to disable this behavior... I also don't understand the idea behind this. Why is it not disabled when you provide a @example ?

2 usecases are:

• React class component. You never want to say new MyComponent() for a react component, because it's not how you will ever instanciate it.
• string template. They are functions, but they aren't used as functions! foo`...`

True, for the React class component that shouldn't be the signature. But to answer the core question: this isn't very obvious in the new Foo() because Foo doesn't have any arguments, but that part of the documentation is a type signature, not an example. So it would display, for instance:

bar(name: string, show: boolean): Object

Which isn't an example, and it isn't just vanilla JavaScript: it's a compact way of showing the types and names of the function's parameters as well as the type of its return value.

I understand the compact idea to see the signature. But I should be able to override this. what about something like @signature or @usage ?

In class case, the constructor parameters does not seem to appear in the signature so it's pretty useless at the moment.

@gre, in my limited testing, by adding @function to the constructor you won't get the new in the output, just the constructor signature. This doesn’t work in JSDoc3’s default templates.

I've made my custom renderer version (that is "react aware"), so feel free to close this if you want.

( https://gl-react-cookbook.surge.sh/api#surface )

Wow. That looks pretty cool. I might borrow. I find myself bumping up against limits of documentation’s default rendering as I dig in deeper. Thanks for sharing.

sure but be aware it might not be very generic. feel free to grab that and adapt ;)

Is this still being worked on?

I would love to have Vue components show their correct signature instead of just the object's name.

For example currently AppConsole is the signature showing for one of my components, I would have expected something like <app-console/>.