Automatically generated usage examples only cover the programmatic use-case

[Adrian Vasiliu]

Except for classes marked with the JSDoc tag @mixin, the current template generates automatically a programmatic usage example:

At least some projects need examples for both programmatic and declarative (markup) use-cases. Candidate solutions:

• Introduce support for a new JSDoc tag, say @CustomTag , to allow providing the name of the custom tag registered for the module, and generate automatically a declarative example.
  • Drawback: in some cases a proper declarative usage example cannot be generated automatically. It should be possible to override the automatic generation when necessary... (as in the next candidate solution).
• Allow the optional suppression of the generated example, such that the doc of the class can provide its own programmatic and declarative examples using the standard @example tags.
  • Drawback: the description of many classes includes already a number of examples, and all examples show up after the class description. This is quite different than JSDoc’s way to put the generic usage example on top of the class description, and we could only count on example’s caption to clarify what is the purpose of each. Still, might be the way to go, in particular if an automatic generic usage example doesn't fit all particular cases.