README is too long to npm

[hargasinski]

The last four functions (log, dir, noConflict, and timeout) in the README are not shown on npm website.

https://www.npmjs.com/package/async

[aearly]

This is tangentially related to #859 . We've wanted to re-vamp Async's docs for a while -- create a site more similar to Lodash's docs.

[hargasinski]

That would be awesome, do you need any help with it? I don't know how far along #859 you are.

[aearly]

We haven't finalized the exact building strategy (waiting to see how a similar push for Lodash's docs works out). At the very least, we want to copy the docs for each method into a JSDoc block in each source file (with full tags and type information), with the intention of parsing them and building a documentation site from them.

[megawac]

@hargasinski we could definitely use help with this. If you or anyone else is interested in helping port our docs to jsdoc compatible formatting in the code it would be greatly appreciated. I recommend doing this method by method. If you're interested I can create a branch for to work off so multiple people can contribute if necessary

Take a look at https://github.com/lodash/lodash/blob/master/lodash.js#L8428-L8470 if you are looking for inspiration.

[megawac]

If we get the code in a state where it's documented in JSDoc I can create a docs site similar to ramdas, lazys, or lodashs

[hargasinski]

@megawac thank you! I'll look into how lodash does it. I have tomorrow off, so I could probably spend a good amount of time working on it. I'll post a comment on how far I get.

[hargasinski]

I may have underestimated the amount of time this is going to take, but I was able to finish the documentation for the collection methods. I should be able to finish the rest tomorrow after work. I created a pull request so you can see what I've done so far, and if anything needs to be changed. I have a couple of quick questions.

1. Since there isn't a real async constructor, should I keep including the @memberof tag?
2. @megawac For the site, how would it be best to document the iteratee and callback functions? In the readme, the parameters are included the name, such as iteratee(item, callback), but I don't think this will work with jsdoc. I've been doing something similar to the lodash example you linked, and just including the signature as the last line in the @param description, like Invoked with (item, callback). The jsdoc site recommends to something like:

/**
 * Send a request.
 * @param {requestCallback} cb - The callback that handles the response.
 */
Requester.prototype.send = function(cb) {
    // code
};

/**
 * This callback is displayed as a global member.
 * @callback requestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */

[megawac]

Since there isn't a real async constructor, should I keep including the @memberof tag?

memberOf async is fine for sure. Also, nit: note that it is memberOf and not memberof

For the site, how would it be best to document the iteratee and callback functions? In the readme, the parameters are included the name, such as iteratee(item, callback), but I don't think this will work with jsdoc.

I'm actually not entirely sure, have thoughts @jdalton? I know ramda documents it with a custom @sig tag

Also no rush on this at all, this is definitely a big task which is why we've kept punting on it. Thanks for looking into it though!

[jdalton]

Doc parsers usually handle that bit. If not they should provide the parsed output for you to reconstruct.

[aearly]

Is it possible to easily link (for example) mapLimit and mapSeries to map? All you have to say is that they're the concurrency-limited versions. Otherwise there's going to be lots of duplicated docs and examples. (I think keeping the signature is okay, though)

[hargasinski]

Hey, just a quick update since I haven't been able to make any commits to the pull request in the last few days. I'm still going to continue working on it. I have a little web experience, so I've also been looking into the lodash site maintenance issue. I'll upload repository with my progress once I get significantly far enough in it. The goal is to get something that async could use too.

[megawac]

Messing around with generating documentation locally with @hargasinski's changes (now on master). I think I like this template http://docstrap.github.io/docstrap/. Thoughts @hargasinski & @aearly

[hargasinski]

I've used docstrap before, I really like it! It's a clean template. Any idea on the theme? My preference would cerulean or lumen. Slate is nice too if you want to go for something darker.

[hargasinski]

Also, would this be a good time to address #975? It would be good to have a logo for the site

[aearly]

Docstrap looks pretty good. I feel the search feature could work better, though. The theme doesn't matter too much since it looks like we can easily change it. (And they're all the same it seems, save for some color differences, more or less.)

Still keeping an eye on lodash/lodash.com#8 and lodash/lodash.com#15 -- since both projects are using JSDoc, we can re-use any strategy they adopt.

The logo can wait, we can use "Async" in a nice typeface until a good logo idea comes along. 😝

[aearly]

@megawac any more recent work on publishing our JSDocs? It would be great to have the docs site in place before the 2.0 release.

[megawac]

I've had bad luck with getting them to build and have run into several issues trying to compile jsdocs properly on my machine

[hargasinski]

@aearly when are planning on doing the 2.0 release? @megawac Currently, I can't make a time commitment, but I should have some more time in the next 2-3 weeks to help you work on this. If you would be able to guide me in the right direction, or just list of some the issues, I could help slowly chip away at them.

[aearly]

We have no release date -- "when it's ready". The docs are not a hard requirement, just a major nice-to-have, since some new methods are only documented through JSDoc.

[megawac]

@hargasinski its mainly I've just never used @jsdoc previously and have been issue sourcing it from multiple files. I couldn't figure out how to make the docs live on one page. The other issue I found was getting typedef implementations (queue and cargo) to appear properly

[hargasinski]

Oh okay, thank you, I'll fork the repo and play around with it a little, although I won't be able to get much done until late next week. I'll post an update if I get anything feasible.