Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Don't use api.jquery.com as source for definition typings #1499
I noticed that jquery definition is adding lots of documentation to the d.ts which is good, but it is also using type information from the documentation which is terrible.
api.jquery.com is full of type errors, and is just not reliable. Lots of places (like the documentation for .html()) will say it accepts a string when it actually accepts anything that jquery constructor accepts, like elements, other jquery objects, etc.
Although api.jquery.com is official, it was not created to give accurate typing information, so using that is just breaking a lot of existing and correct code.
If that is going to be used, it needs to be checked, as the most accurate type for most parameters will be actually "any".
Hope you had a good Christmas and New Year! I wanted to respond to this issue and #1500 as well.
I've looked at the code behind
But perhaps more to the point - what's happening with
If there isn't a better source of API documentation available I think it's probably best to stick with what's listed on http://api.jquery.com . I don't know if there is a better source of documentation available that you know of? Certainly from reading the jQuery source it's not always obvious what all the available overloads are. I had to hunt high and low for the function overload of
By the way, if you think that the jQuery API is invalid is it straightforward to submit a pull request to change the documentation? I seem to recall that the jQuery validation documentation is on GitHub so it's possible that jQuery will also be....
api.jquery.com was not created to give correct typing information. To follow api.jquery.com blindly for typing information will just produce incorrect definition that will be useless.
I won't start submitting PRs for jquery api because that will be an endless job syncing the types. Type information required by typescript is exclusive to typescript, not to jquery. Their documentation is not even prepared to map things the way TS requires.
The implementation detail is actually not important as you said, but the fact that .html() accepts other jquery objects, or dom elements is. That is existing behavior that won't change, and people depend on it.
I'm not saying to ignore api.jquery.com completely, just don't use their type information as absolute truth because their documentation just doesn't care that much for its correctness.
For reference we are talking about this section of code : https://github.com/jquery/jquery/blob/1.9-stable/src/manipulation.js#L217-L257
Yes. But unlikely as it would cause other people's code to break.
Possible suggestion use the same signature for
It does. But we as programmers abuse the underlying implementation which is a fair conscious choice to make. Following the docs would be recommended but since you (and possibly others) have code that depends on this signature of