Improve api docs with descriptions\examples, add functions\aliases like lodash

[gothy]

Thanks for your work! Looks very promising :)

I'm talking about things like reduce -> foldl, every -> all, includes -> elem, etc.

[jdalton]

I'm actually removing those aliases in lodash v4 :D

[gothy]

@jdalton why would you do that? :)

[jdalton]

Simplify, focus, and reduce clutter and API confusion. There were ~20 or so aliases, way too much.

[scravy]

@gothy This issue names two things: (1) Improve API docs (2) Add more aliases.

(2) I will not add any more aliases than there already are, for pretty much the same reasons as for why @jdalton removes them from lodash. The existing aliases are pretty much there for only one reason: The names for most of the functions are literally taken from the Haskell Prelude. Some of these however do clash with names/keywords in JS (such as the null function which is called isEmpty or null_ in Nodash). The general rule I followed here is: Take the name from the Haskell Prelude, if clashes with any JS name append an underscore and introduce a better named alias (like the isEmpty case).

Also note that some of the aliases can not actually be expressed in JavaScript, e.g. plus is also available as +, but of course you can not have that symbol defined by a library in JS. It serves only as an alias since the Haskell Prelude defines +, so you can find it in the API doc in search or in your favorite REPL by examining the Nodash object.

(1) I am constantly trying to improve API docs but it takes time. Right now I am not adding any as I am doing a major rewrite of streams/lazy evaluation (see the pure-streams branch). Pretty much everything with regards to streams is changing, so it's fruitless to document it right now before it's ready.

The goal is to have every function mention a signature in the API docs, an example how to use, and at least a one-liner about it. I am happy to accept pull requests and some of the documentation can be derived from the Haskell Prelude, so if you have some spare time :-)

I will leave this issue open for now until the pure-streams branch is ready which will hopefully also contain a good chunk of examples in the API doc.

[gothy]

@jdalton Sorry, I was mistaken on what is an alias for what in foldl\reduce case :) But still I think removing popular aliases like extends\each\compose will bring developers(those who would like to be up to date with lodash) hours of pain while just cleaning up the docs. IMHO, that's not a good way to archive this goal.

@scravy I got it :) On the docs - it's just a friendly reminder to have them on the way to 1.0 Aliases are just nice to have once you're moving from underscore\lodash to nodash. You're free not to add them since nodash is not used that wildly like lodash. Having clean docs from the start is really a good thing :)

[jdalton]

@gothy

But still I think removing popular aliases like extends\each\compose will bring developers(those who would like to be up to date with lodash) hours of pain while just cleaning up the docs. IMHO, that's not a good way to archive this goal.

_.extend is its own method now. _.each and _.eachRight are the only aliases left. Major version bumps are great for house cleaning.