documentation

documentation copied to clipboard

I'm using documentation.build() method (NodeJS API) to generate "comments", which I use to build custom HTML. After the update from 10.0.0 -> 10.1.0 (which adds "TypeScript support & inference") documentation.build started to yield different structure of Comment entity for Typescript interface properties - properties field became empty while members.instance started to contain information about interface properties. (BTW, isn't it breaking change? Why major wasn't bumped? Here is doc that suggests to use returned object to build documentation of any kind: https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md#examples-1).

So now I'm trying to adapt to the new structure (switch from properties to members.instance). The problem is that after above-mentioned update there is no indication in the yielded Comment object about optional nature of property. Example of such interface:

/** Some interface */
interface SomeInterface {
  /** property description */
  a?: string;
}

Prior to the update Property entity provided type.type === 'OptionalType'. Same problem in latest version (12.0.3).

BTW, isn't it breaking change? Why major wasn't bumped?

TypeScript pre-10.1.0 was undefined behavior: we supported its small overlap with Flow, but not TS-as-such, and never documented the ability to use TypeScript in any way. So it was a minor change instead of a major change in that it added a feature.

BTW, isn't it breaking change? Why major wasn't bumped?

TypeScript pre-10.1.0 was undefined behavior: we supported its small overlap with Flow, but not TS-as-such, and never documented the ability to use TypeScript in any way. So it was a minor change instead of a major change in that it added a feature.

Right. But for those who used Flow and relied on certain Comments structure it was a breaking change, isn't it?

I suppose so, and if so, I'm sorry. semver is kind of impossible to do right all the time.