Initial documentation

[megawac]

Alright this took longer than expected. Mostly because I was working out nuances in our jsdoc configurations. I have a number of commits related to this over the past couple weeks on my personal fork :/. Anyway the main one that drove me nuts was namespaces vs modules.

Take a look at dc4cac3 for real changes

Could people take a look at the docs and share their thoughts?

Docs: http://rawgit.com/caolan/async/docs/docs/index.html

/cc @aearly @hargasinski @Kikobeats
Fixes #1083 #1135

[megawac]

note to self, remove unused theme

[megawac]

Known issues:

• (Fixed) Invoke documentation for our custom types (queue/cargo) look poor http://rawgit.com/caolan/async/docs/docs/typedef/index.html#static-typedef-CargoObject. We should think about how we want to doc the

invoke with ()

Perhaps

invoke like queue.pause()

See next commit.

• (Fixed) internals shouldn't be included on the main doc pages
• custom styling would be nice

[Kikobeats]

Insane work!

I always missed a doc page for async to make easy check specific function documentation, so I'm a very fan of this.

Could be interesting use a short CNAME. We can use async.js.org for free.

[Kikobeats]

Also original documentation are divided in 3 main sections: Collections, control flow and utils. What about that?

[megawac]

Yeah, I haven't able to make categories work so far. Also I just noticed all the none Limit versions of functions seem to be missing at the moment (each, map etc).

Also I bought http://www.asyncjs.xyz/ when there was a $0.30 sale on xyz domains

[hargasinski]

This is amazing progress! Good job! The search feature will be useful.

A couple of things I noticed. In addition to the limit functions, functions like map, and apply are also missing. It appears to be related to the same issue. Also, it would be nice to have async available on the page to be able to test out the functions using the console.

[hargasinski]

Btw, just a quick thought @megawac, esdocs looks like a promising tool, but it may take a while to get everything set up with it. Does you want me to prepare a quick jsdoc site in the meantime? I was able to prepare a quick sample site on my fork: http://hargasinski.github.io/async/. If you want to see the changes, look at the branch: docs-jsdocs. Let me know if I should keep working on it. Thanks!

[megawac]

@hargasinski go for it, there were a couple reasons I went with esdoc over jsdoc in my attempt:

• Really strong search functionality
• source file browsing
• Automatic es6 import path injection (currently the paths are wrong though as it would be async/each instead of async/lib/each
• I really like the theme (after a couple style tweaks) ^^

However, the issues with esdoc are clearly blocking so I'd be fine with going with jsdoc if we can get them in a good spot

[hargasinski]

@megawac awesome, I'll continue exploring the jsdoc option then. Just to add to the list, it would be good if the option we choose supported the categories tag, and had an repl, or at least injected async into the page.

[hargasinski]

@megawac, sorry for the spam, but I think I have something you'll like. You can see it at http://hargasinski.github.io/async/docs.html.

I should preface by saying that this definitely isn't a permanent solution, but it should work for the time being. Essentially, it's using JSDoc modules to fake categories and slightly modifying the output of the minami theme, in this file.

It includes

• all of the source code
• es6 paths are available (they are manually included at the top of each comment, for example)
• async is available in the console

In regards to the comment on #1083, it'll all on one page, including the typedefdefinitions, although, the definitions don't appear in the nav column. Some of the drawbacks are:

• no search functionality (it is all on one page, so would CTRL + F be enough? It's in similar state as the lodash docs right now)
• adds cheerio as a dev-dependancy
• it's not using the @category tags (the solution is a little bit of a hack)
• the theme is a little plain :(

Let me know what you think, thank you!

[megawac]

es6 paths are available (they are manually included at the top of each comment, for example)

Mind dropping this commit? I'd prefer to do this with a plugin. The plugin would be ridiculously straight forward. I'll send your branch a PR in a bit.

no search functionality (it is all on one page, so would CTRL + F be enough? It's in similar state as the lodash docs right now)

Fine for now. Going to continue watching esdocs though :)

async is available in the console

Cool that's a must. Have you looked into runnable snippets?

@megawac, sorry for the spam

Feel free to cc me on commits, I've been checking your branch quite frequently to see what you're up to. Also loving the progress

[hargasinski]

Mind dropping this commit? I'd prefer to do this with a plugin. The plugin would be ridiculously straight forward. I'll send your branch a PR in a bit.

merged the PR, thanks!

Fine for now. Going to continue watching esdocs though :)

I've been thinking about it some more, and I could probably recreate the search functionality of esdocs using typeahead.js and cheerio. I'll look into it the next couple of days.

Cool that's a must. Have you looked into runnable snippets?

No, not yet. I'll start looking into libraries for it.

Feel free to cc me on commits, I've been checking your branch quite frequently to see what you're up to.

Awesome, I'll start doing that. It'll help address issues more directly.

[aearly]

Nice, I like the direction things are going. How easy is it to tweak the minami theme? Do you have to fork the module?

I would say that runnable snippets are less important since most of our examples refer to fs functions (or other functions not actually included). Also, my experience with a page with 70+ runnable code snippets is that it freezes for several seconds when you load it.

[hargasinski]

@aearly currently tweaking the minami theme has been relatively easy as it's mainly been small changes. Its just taking a while to do. I'm reading in the outputted HTML, and adding our components using cheerio. The script is under 200 lines, you can see it here. I'll continue tweaking it, but I may have to fork it eventually for some of the bigger changes, like a REPL, or runnable scripts. We have a list of things that still need to be added on the issues page of my fork.