Support multiple types in JSDoc typing

[p-bakker]

In JSDoc you can type for example a parameter to allow multiple types, like this:
@PARAM {String|Number} myParamName description

Same thing goes for @type

Tern doesn't seem to recognize this.

[paulvi]

similar to #426

[marijnh]

Rather, this is similar to #405, which I'm open to (I outlined a solution in the PR) but not willing to work on myself right now.

[p-bakker]

I had a look at this, think I could pull off a pull request to at least implement this on the JSDoc level (so not the condensed file level #405 talks about). Would you accept a PR that implements this just for JSDoc?

[p-bakker]

I took a stab at it and got a rough version working: Code Completion shows results for both types in a union like string|number.

However, Tern returns questionmarks for the type in queries that are used to display hover information. Any pointers where to look/how to fix this?

While at it, is there support for the "*" type, also called the Any type? This is a type that doesn't need to ba a JavaScript Object, could be a host object

[p-bakker]

Answered part of the first question I had on my own: inside infer.js there's a function called canonicalType which returns null in my case, due to which I get the questionmark, instead of a UnionType notation ("?" vs. "string|number" for example)

I can go a look how to fix this, but I cannot oversee the consequences of replacing questionmarks with actual UnionTypes in the Tern server responses. Would that break stuff, in which case the question is: should this behavior be exposed through a property? Or would it just be an improvement?

Any thoughts appreciated

Paul

[p-bakker]

Did look into this a bit more and the more I think about it, the more I think that the initial approach taken by @MetaMemoryT in #405 might be the correct one.

Yes, Tern already supports storing multiple types against variables/properties, but these are the results of infer and when such a variable/property is asked for its type (AVal.getType()) it returns null if there are multiple types. How/where to implement a toString function that returns something like "string|number" is unclear to me.

When JSDoc specifies a UnionType (when the option to make JSDoc leading is enabled) or when the defs files would specify a UnionType, those are not the result of infering, but something the developer deliberately specified that way.

Altering Tern to support UnionTypes without introducing a UnionType Type would break existing behavior imho. The UnionType should extend AVal and at least implement the toString() function to return something like "string|number" and the UnionType type is most likely only instantiated as a result of parsing JSDoc or def files.

I've reached the end of my investigation on this case, would need some input to be able to continue.

Paul

[marijnh]

We'd have to change the way toString works, yes. It currently skips AVals, and to get union types we'd need to call through those AVals. Basically, add a toString method to AVal.prototype and ANull.prototype, and change the places that call toString on .getType to call it on the AVal if appropriate.

AVal.prototype.toString would then need to be outfitted with some heuristic of whether to report a union type or to just give up and spit out ?. Getting this right probably involves some tricky decisions (which object/function types count as the same type, how many types do we want to report as a maximum, etc).

[p-bakker]

So you prefer to outfit AVal.prototype.toString with some heuristics involving tricky decisions when to do what over adding a UnionType type?

To me, adding the latter to be used when encountering a uniontype in definition files and when a uniontype is provided through JSDoc would be a lot cleaner: then no tricky logic is needed to determine whether to report a uniontype or not.

Also take into account UnionTypes in the upcoming TypeScript 1.4 version (http://blogs.msdn.com/b/typescript/archive/2014/11/18/what-s-new-in-the-typescript-type-system.aspx)

If this is not the road you'd want to take and instead prefer to implement the desired behavior using the existing AVal, would this be a viable approach: If the AVal has multiple types with the same weight, report them as a UnionType?
The only other alternative approach I can think of is setting a flag on the AVal when adding multiple types to it that are known to come from a UnionType (so from the definition files or from JSDoc).

Please advise

[marijnh]

An AVal can only have multiple types if they have the same weight (the ones with less-than-max-weight will be discarded). I do think that it is also useful to report number|string when someone writes something like x = foo() ? 10 : "ten". The heuristic I'm talking about is that if an AVal has a lot of different types, it's probably simply polymorphic, and shouldn't result in a long string of |'s. But, when a bunch of those types can be considered similar (functions with similar signatures, or objects with similar properties), they should probably be reduced to a single type in the string output (similar to what getType does, but extended to not give up when a single dissenting type is found).

[p-bakker]

ok, tnx for the input, will take a stab at it

[RReverser]

Any updates on this?

[p-bakker]

I started on it, got stuck and then got completely sidetracked, so unfortunately no progress.

And no idea when I might get around to it now

[marijnh]

Please take a look at patches 4604a1e...29bcf0a and see whether they reflect what you had in mind.

[RReverser]

Yes, looks so, thanks! (if that question was addressed to me)