Documentating Code

[sebilasse]

Just a question - the TypeDoc approach feels like much double typing. Instead of e.g.

/**
 * @type CheckboxProperties
 *
 * Properties that can be set on a Checkbox component
 *
 * @property checked        Checked/unchecked property of the radio
 * @property describedBy    ID of an element that provides more descriptive text
*/
export interface CheckboxProperties extends ThemeableProperties {
  checked?: boolean;
  describedBy?: string;
}

we could simply write

/** Properties that can be set on a Checkbox component */
export interface CheckboxProperties extends ThemeableProperties {
  /** Checked/unchecked property of the radio */
  checked?: boolean;
  /** ID of an element that provides more descriptive text */
  describedBy?: string;
}

with e.g. Typson http://lbovet.github.io/typson-demo/

How do you think ?

[dylans]

This is roughly the same argument from Dojo 1.x of DojoDoc vs. JSDoc. TypeDoc is at least not as repetitive as JSDoc with needing to provide the types again like JSDoc would.

Our main mindset here with documentation is to not battle against the standard, because in Dojo 1.x this cost us in the form of IDE integrations.

We're happy to keep an eye on Typson and alternatives, but our preference is going to be for whatever format(s) are understood by development tools.

[sebilasse]

@dylans Totally changed my mind today. It is impossible with the second syntax to document extended interfaces differently from those they extend. I have a Container and a Grid and both extend from each other. But the one way (Grid as child of Container) I would like to name it "A Container with a Grid can ..." in the properties and the other way (Grid w. Container-class) I would name it "A Grid container".

Because it totally makes sense to doc. each interface independently I am closing this ...

However : What I like, well love, about Typson is the ability to generate JSON Schema from interfaces (in theory, currently does not work >TS2.2). This would directly give me a component to "demo" each dojo2 widget because the JSON Schema generates you a nice form for all the properties of a widget ...