jQuery.parseJSON: Function has multiple return types, not just Object.

[usmonster]

The return type is currently documented as Object, with the description "...returns the resulting JavaScript object."

As this function is roughly equivalent to JSON.parse, it technically produces an ECMAScript value, which, in addition to Object (or, really, PlainObject), can also include String, Number, Array, Boolean, or null. These multiple return types should be explicitly mentioned on the return type.

Shall I attach a PR to make this change and update the description? To further clarify, perhaps another example could be added? (Related, minor issue: There's a rogue line break towards the end of the current example...)

[scottgonzalez]

The return type is currently documented as Object

...it technically produces an ECMAScript value, which includes ... Object...

I'm not sure what you're proposing to change it to. Object is correct.

[scottgonzalez]

I fixed the stray line break in the example. It's being deployed right now.

[usmonster]

@scottgonzalez I'm suggesting that Object is in fact not strictly correct, since the function has multiple possible return types (Object being only one of them). Updated issue description--please reopen.

(Also, thanks for the quick fix to the other minor issue--seems you are in lightning deploy mode. :)

[scottgonzalez]

Sorry about that; your original wording was extremely confusing about what you were trying to change. Your edit makes it much more obvious. A PR to list the multiple types would be great.

[usmonster]

@scottgonzalez Yeah, sorry if it was confusing before. I was just a little taken aback by the close-first-ask-questions-later reaction. Though I guess it keeps the queue clear. :]

Speaking of questions, I have a few before I attach a pull request:

1. In addition to including the other possible return types, what would be your opinion on also replacing Object with PlainObject as a more precise/accurate alternative? I hesitate to do that, though, because $.isPlainObject(null) === false, and null is still a valid return value. Would it be enough to just include an explicit note for the null case if we switched to PlainObject, or should I just leave Object since it covers both the "plain" and null cases?
2. Can/should I add one or two other examples to make it more explicitly clear that there is more than one possible return type? And maybe add another malformed JSON string example in the bullet list (e.g. "undefined")?
3. Probably a little beyond the scope of this issue, but at least somewhat related: the signature for the success callback of jQuery.ajax is misleading in that it denotes that the function will be passed a PlainObject as its first argument, even though it is later (and more accurately) noted that the passed argument is "formatted according to the dataType parameter." Indeed, the data can even potentially be of any type if one uses custom converters. (The same issue exists for the dataFilter setting's function signature.) Would it be useful or even worth it to change these signatures? Maybe in these cases use Anything in place of [Plain]Object? (Probably in a separate pull request, if at all?) Thoughts?

Thanks!

[scottgonzalez]

Yeah, the quick close is to keep the list clean. As you've seen, we're just as quick to reopen upon clarification :-)

1. I think in most places we just use Object instead of PlainObject. Perhaps @dmethvin or @kswedberg can provide more detail as to when we use which one (api.jqueryui.com only uses PlainObject for documenting $.widget() and api.jquerymobile.com never uses it).
2. I think adding another example or two would be fine. Showing how to handle invalid JSON seems like a good idea.
3. Using Anything seems like the right direction, but let's open a separate issue for that.

[usmonster]

Re: 1., I see PlainObject being used all over the place on api.jquery.com, and it's the only kind of Object that could be returned by the function, though the null case is really what concerns me here. Instead of listing PlainObject with a note for the null case, maybe we should keep Object and add a note explaining that it's either a PlainObject or null (i.e., you'll never get back a native/host JS object)? @dmethvin, @kswedberg, thoughts?

Re: 2., Ok, I'll add "undefined" and a couple others to the list of anti-examples and maybe one more valid example that returns something other than Object.

Re: 3, Done.

[usmonster]

Preliminary work at usmonster/api.jquery.com@77b81d0.

Haven't yet added any new examples, nor any note on the fact that any returned Object is actually a PlainObject (unless input is the string "null"), as opposed to any native/host JS object or anything that will have a built-in prototype property. But maybe this is enough? If so I'll just attach a pull request.

[dmethvin]

Just FYI if you're looking for consistent type signatures for jQuery APIs the TypeScript at https://github.com/borisyankov/DefinitelyTyped/tree/master/jquery might be handy.

[usmonster]

Cool, thanks for the link. It looks like it could be useful if we wanted to find and fix all the inconsistencies between the documented and actual API, though "virtual types" used in the docs would still need to be checked. Also, I suppose we'd often want to document "intended use" even/especially when the code itself doesn't check or otherwise enforce some of the input types (e.g. jquery/api.jqueryui.com#202).

For now, I'm happy just filling in gaps as I come across them. :] My current internal conflict over PlainObject vs Object in this case stems mostly from the fact that the docs have a couple minor issues:

1. The Object definition in the docs implies that all objects have a prototype property. This is either poorly worded or inaccurate, depending on the writer's intention, but it's definitely not true for object literals. As long as that section of the docs remains as-is, it's misleading at best to use it as one of return types for $.parseJSON, since the only kind of Object it can return is either a plain object (no prototype) or null.
2. There is no Null type listed in the API docs (even though, strictly speaking, it's part of the actual JS spec). If we added one, it would be easy enough to list PlainObject and Null as return types, in place of Object, though I'm not sure there would be very many other instances where we'd gain anything by explicitly listing Null as a type.

Though in the end, I know it's extremely pedantic, and I'm not sure many people will actually care about the distinction.. :] In any case, I'm going to attach my pull request in its current state, and someone else can make an executive decision as to what else to do, if anything.

[dmethvin]

Though in the end, I know it's extremely pedantic, and I'm not sure many people will actually care about the distinction.

Well, you care, and we care about you. 👪

But seriously, the folks who run the DefinitelyTyped repo have paged me for a few questions and often it relates to some ambiguity with the args. I'd like to be able to point to the docs and say "that's not valid input" when people try passing junk. OTOH I don't want to get so pedantic about the return types that we end up with dozens of them with minor differences. So for now I'd pass on PlainObject and Null.

I'm okay with this PR as-is, the extra examples are nice. I was a bit concerned about having so many return values, the closest we have is http://api.jquery.com/val/ , but it seems the design doesn't explode on small screens when there are that many.

[usmonster]

Well, you care, and we care about you. 👪

Aw shucks. You guys. :]

I'm okay with this PR as-is, the extra examples are nice.

Good to merge as-is, then? Bit confused about the help wanted tag.

[gnarf]

Object literals most definitely do have a prototype!

It's Object.prototype

[kswedberg]

Should be either "a number" or "numbers"

[usmonster]

Good catch, updated PR.

[usmonster]

Object literals most definitely do have a prototype!

@gnarf, my point was more that the documentation implies that the prototype property would be on every object (see where it says "All objects have a prototype property."), which isn't the case. Also Object.getPrototypeOf(null) gives an error, although null is also an "object"... Still, I'm fine leaving that part of the doc as-is, at least for now.

[usmonster]

@kswedberg, just a ping to let you know that I think all concerns about this PR have been addressed, so feel free to merge if you agree or to comment if you don't.

[usmonster]

Anything left to do on this? @scottgonzalez @dmethvin

[dmethvin]

LGTM

[kswedberg]

thanks, @usmonster! Sorry it took so long to merge this in.