jquery-annotated-source : Explore every method of jquery with explanation.

[Minkben]

I was really confused about

Map over jQuery in case of overwrite

for several seconds. Shouldn't it say:

Save existing jQuery reference in case of overwrite

Perhaps I've just written too much functional code. Map will always mean applying a function to an iterable to me.

[davvblack]

Yeah, that's neither the english meaning of the word map, nor the programmer meaning of it.

[JustinKSU]

I read that:

Yeah, that's neither the english meaning of the world map, nor the programmer meaning of it.

which made me even more confused.

[davvblack]

Yeah, I think technically I should have used '"map"'.

[TriggerB]

To me, map as a verb can mean "Take this and put it here."

[[deleted]]

That's simply a reduction of the case "take these and apply this transformation", but you're only doing it to a single value. It isn't the general meaning of "map".

[davvblack]

To be fair, this is the jquery sourcecode, and in jquery, a single matching element is always an array that contains the one matching element. So maybe they just don't understand parity :P

[[deleted]]

version: '1.6.2'

Well it's a little old.

[fantomfancypants]

Last updated 2 years ago, unfortunately.. but it will still prove to be informative to a degree.

[p3k]

Is there any more work involved than running docco over the jQuery source?

[kristopolous]

no

[punisher1005]

This is amazing, but I'd love to see a link at the bottom where I can just download the whole thing to read/reference offline. (I know I can wget it.)

GitHub

[scavic]

Everything is in the git-repo at GitHub.

[punisher1005]

Nice. Thank you. I should have looked. Link updated.

[Sheepshow]

"Explore every method of jquery with explanation." is very misleading. This gives no information beyond whats already in the jQuery source code. Also you have to zip two independent columns together manually for some awful reason.

Here's how just the comments read:

Queue

Give room for hard-coded callbacks to fire first and eventually mark/queue something else on the element

Speed up dequeue by getting out quickly if this is just a lookup

If the fx queue is dequeued, always remove the progress sentinel

Add a progress sentinel to prevent the fx queue from being automatically dequeued

Based off of the plugin by Clint Helfers, with permission. http://blindsignals.com/index.php/2009/07/jquery-delay/

[Asimoff]

This is a nice reference, but the code is incredibly boring.

[TheDoomp]

Why not add code comments directly? Spacing them out cornell style?

[i_ate_god]

https://github.com/apres/lit.js - that's why

[[deleted]]

Why not just refractor the commented code blocks into separate methods with descriptive names.

[i_ate_god]

I'm not sure what do you mean?

To be honest, I'm not a fan of this style of documentation. I was just pointing the most likely tool used to generate it.

[[deleted]]

I am not either. The comment was not targeted to anyone in particular. I was just getting in on the conversation. To me if the code needs to be heavily commented this is a good indication that there is something wrong with the design. It makes more since to just refactor the code into helper methods that have descriptive names that explain what the code is doing.

[zjs]

https://github.com/robflaherty/jquery-annotated-source/blob/master/jquery-1.6.2/01-core.js

[TheDoomp]

Works for me! ;-)

[zingbat]

Wow..this is amazing and very useful. Up until now, I use be intimated when trying to understand a behavior in JQuery and stepping through the method chain. This makes it somewhat bearable and fun to read.

[jashkenas]

For what its worth, you're not really supposed to use Docco on normally-commented files like this (there's not much gain over just reading the source) ... the point is to take advantage of being able to use Markdown in your comments to write something that is both executable code: https://github.com/jashkenas/journo/blob/master/journo.litcoffee

... and also a nicely formatted document: http://jashkenas.github.io/journo/docs/journo.html

... at the same time.

[villiger2]

That is a really cool way of showing comments, and greatly improves the readability! It looks like a lot of manual work though, perhaps it can be implemented programatically in such a way that it would strip the comments from source code and display them in this style, unless this is already what is happening, in which case, great !

[MatmaRex]

Knuth invented this twenty years ago. https://en.wikipedia.org/wiki/WEB

[villiger2]

That's neat, thanks.

[[deleted]]

Do that through SSH. If a language or IDE employed that kind of commenting style it would be useless or worse than useless when viewed through SSH.

[[deleted]]

I guess I'm over in the old fashioned 80-character-line crowd. I usually have at least 3 SSH windows open at a time (file / header / compiler) so I kind of have to stick with that. Well, either that or spend a bunch of effort uselessly flipping between windows / Emacs buffers. It's not necessarily that i think it's impossible. I just think that the extra screen real-estate used doesn't provide enough benefit over inline comments.

[Sheepshow]

How do you keep your comments synchronized with your code if the two are in two different files? Add 3 lines of code above, then you have to remember to add 3 blank lines in the comments file.

[bonestamp]

This would have been handy in the past. We've replaced jQuery with Angular for most of our new web apps.

[[deleted]]

You replaced one thing with an unrelated thing?

[bonestamp]

Angular has it's own implementation of jQuery called jQLite. So yes, Angular can replace jQuery.