Split "get" into 2 distinct entries #275

Closed
wants to merge 3 commits into
from

Conversation

Projects
None yet
3 participants
Contributor

andyli commented Apr 2, 2013

The .get method was documented as .get( [index ] ) that returns Element, Array.
To be accurate, .get in fact has 2 signatures:

  1. .get( index ) returns an Element
  2. .get() returns an Array

What I did is simply split the entry into 2 with minimal modification.

gnarf commented on b4afb0d Apr 22, 2013

There is no such thing as an Integer in JavaScript, all numbers are Number

Owner

andyli replied Apr 22, 2013

Integer is properly documented in http://api.jquery.com/Types/#Integer
And it is used in the doc, eg. http://api.jquery.com/slice/ (start, end)

hrm, thats a tad odd, but i guess if we are already using it... I'll let @kswedberg decide :)

@gnarf37, I think the change is fine here. We use the term "type" loosely ( get the play on words? ;) ). We also document Deferred Object, Promise Object, Callbacks Object, selector, events, and htmlString as "types":

JavaScript provides several built-in datatypes. In addition to those, this page documents virtual types like Selectors, enhanced pseudo-types like Events and all and everything you wanted to know about Functions.

Contributor

andyli commented May 5, 2013

It is ready to be merged, no?
I would like to clean up more similar things and will submit pull requests.

Member

kswedberg commented May 5, 2013

I don't think it's ready to be merged. I fixed the problem with the return type, so it now lists Array and Elements separately. It probably deserves two separate signatures, but not two entries. We typically reserve the multiple-entry thing for methods such as .val() and .attr() that are both getters and setters.

Contributor

andyli commented May 5, 2013

But is that possible to declare individual signature's return type?
The reason of using two entries was only because I thought the return type is specified in entry.

Member

kswedberg commented May 8, 2013

No, it's not possible to declare individual signature's return type, but we can list them both and then provide clear enough explanation in the content. I just don't want to create multiple entries unless we really have to (like, if a method is a setter and a getter) because it involves too much duplication.

Take a look at http://stage.api.jquery.com/get/. I've updated the entry so it reads a bit better, and I think it's good enough. What do you think?

Contributor

andyli commented May 8, 2013

I do think that the doc is (and was) pretty clear. It is already somewhat splited into 2 parts already, which it first describe .get(index), then .get(). So I'm not sure why having individual entry for each signature does not make sense.

Referring to my change set, the only duplicated part is the short code sample:

Suppose we had a simple unordered list on the page:
<ul>
  <li id="foo">foo</li>
  <li id="bar">bar</li>
</ul>

I think the semantic different between the two signatures is clearly shown by their different return types. If they both returns an Array, they both mean retrieve the DOM elements. But since .get(index) return Element, it means retrieve the n-th DOM element.

Lastly, the precise type info given from the xml is needed, for IDEs to provide accurate code completion, or for generating Haxe extern / TypeScript definition.

Hope I have explained my concerns clearly :)

Member

kswedberg commented May 13, 2013

@andyli, ok, that makes sense. Can you update the pull request based on the current state of the entry? Also, can you please sign the CLA at http://contribute.jquery.org/CLA/? That needs to be signed before I can accept the PR.

Merge branch 'master' into get-split
Conflicts:
	entries/get.xml
Contributor

andyli commented May 13, 2013

I've just updated the pull request and also signed the CLA (with the name Li Wing Ho Andy).

Member

kswedberg commented May 16, 2013

Merged in fc8de53

Thanks, @andyli!

@kswedberg kswedberg closed this May 16, 2013

@andyli andyli deleted the andyli:get-split branch May 17, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment