No longer rely on JSDoc types alone

[tmcw]

Right now documentation.js transforms Flow types to JSDoc types, so that it can run them both through format_type, which is derived from doctrine's formatter. We shouldn't do this anymore: JSDoc types can't cover everything that Flow can.

Possibly we should reverse this process and instead convert JSDoc types to Flow types. We will need to survey what the overlap and intersection of the two are in order to make an informed decision.

	JSDoc	Flow	notes
union	yes, string|number	yes, string|number	https://flow.org/en/docs/types/unions/
intersection	no	yes	https://flow.org/en/docs/types/intersections/ eslint/doctrine#183
nullable	yes, ?string	yes, ?string	https://flow.org/en/docs/types/maybe/
arrays of types	yes, Array<string> or string[] or Array.<string>	yes, Array<string> or string[]	https://flow.org/en/docs/types/arrays/
non-nullable	yes, !string	no?
intersection	no	yes, type & type	https://flow.org/en/docs/types/intersections/
tuple	no	yes, [string, number]	https://flow.org/en/docs/types/tuples/ google/closure-compiler#379
literal types	no	yes, 2	https://flow.org/en/docs/types/literals/

[tmcw]

Another JSDoc lacking: indexers.

http://usejsdoc.org/tags-type.html

versus

https://flow.org/en/docs/types/objects/#object-type-syntax-a-classtoc-idtoc-object-type-syntax-hreftoc-object-type-syntaxa

There is no way to express

{
  size: number,
  [id: number]: string
}

In JSDoc - you can have a type application or a record type, but not both.

[faassen]

non-nullable in flow seems to be simply the variable without ? in front of it. So with flow you mark nullability: ?string

[tmcw]

Punting, moving conversation to dx-spec tmcw/dx-spec#2