API builder parses union types incorrectly, adds members and parameters for additional types

[mootari]

When a member or parameter declaration contains a union type, the parser detects additional types after | as a separate member/parameter.

This happens all over the place. A good example is VertexData:

[mootari]

It looks like both the parser that creates the AST as well as the docs pages are custom implementations. Was this done to reduce deployment complexity (dependencies, reliance on 3rd party tools), or because no viable alternatives existed at that time?

[deltakosh]

We did not find good stuff 3years ago but if you know something worth looking please let me know

[mootari]

http://typedoc.org/ might be worth a try. What are special features provided by the custom implementation that may not be available in a generic solution?

[mootari]

I expect that switching to typedoc would be a lot more involved than just tackling the issue in the current builder, as described in my comment in #713.

The current builder relies on the typescript-services package for the AST which in turn has been marked as obsolete and had its last update in 2014. I suspect that switching to the new node API for the TypeScript parser should get rid of the ghost members/parameters, although the rendered markdown might need some fixing as well.

[deltakosh]

Do you mind trying to move to the new API?

[mootari]

Sooo ... typescript-services essentially uses a compiled TypeScript 1.0.0 (April 2014) where union types didn't even exist (at least the tests for those where added late 2014). In early 2015 TypeScript moved its compiler API around, and since then the compiler related APIs are no longer exposed to NodeJS.

There may be ways to patch typescript to reexpose them, but I'd argue that the time is better spent moving to TypeDoc and making it work for BabylonJS, especially given how much custom code in the builder currently relies on that dated API.

[deltakosh]

whatever works :)

[deltakosh]

Fixed with typedoc