Async: README est trop long pour npm

Ceci est tangentiellement lié à #859 . Nous voulions réorganiser les documents d'Async depuis un certain temps - créer un site plus similaire aux documents de Lodash.

Ce serait génial, avez-vous besoin d'aide? Je ne sais pas à quel point vous en êtes au #859.

Nous n'avons pas finalisé la stratégie de construction exacte (en attendant de voir comment une poussée similaire pour les documents de Lodash fonctionne). À tout le moins, nous voulons copier les documents de chaque méthode dans un bloc JSDoc dans chaque fichier source (avec des balises complètes et des informations de type), dans le but de les analyser et de créer un site de documentation à partir d'eux.

@hargasinski, nous pourrions certainement utiliser de l'aide pour cela. Si vous ou quelqu'un d'autre êtes intéressé à aider à porter nos documents vers jsdoc formatage compatible

Jetez un œil à https://github.com/lodash/lodash/blob/master/lodash.js#L8428 -L8470 si vous cherchez de l'inspiration.

Si nous obtenons le code dans un état où il est documenté dans JSDoc, je peux créer un site de documentation similaire à ramdas, lazys ou lodashs

@megawac merci ! Je vais voir comment lodash fait. J'ai congé demain, donc je pourrais probablement passer beaucoup de temps à travailler dessus. Je posterai un commentaire sur le chemin parcouru.

J'ai peut-être sous-estimé le temps que cela va prendre, mais j'ai pu terminer la documentation des méthodes de collecte. Je devrais pouvoir finir le reste demain après le travail. J'ai créé une pull request pour que vous puissiez voir ce que j'ai fait jusqu'à présent et si quelque chose doit être modifié. J'ai quelques questions rapides.

1. Puisqu'il n'y a pas de vrai constructeur async , dois-je continuer à inclure la balise @memberOf ?
2. @megawac Pour le site, comment serait-il préférable de documenter les fonctions iteratee et callback ? Dans le fichier readme, les paramètres sont inclus le nom, tels que iteratee(item, callback) , mais je ne pense pas que cela fonctionnera avec jsdoc. J'ai fait quelque chose de similaire à l'exemple lodash que vous avez lié, et @param , comme Invoked with (item, callback) . Le site jsdoc recommande quelque chose comme :

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

/**
 * This callback is displayed as a global member.
 * <strong i="20">@callback</strong> requestCallback
 * <strong i="21">@param</strong> {number} responseCode
 * <strong i="22">@param</strong> {string} responseMessage
 */

Puisqu'il n'y a pas de véritable constructeur asynchrone, dois-je continuer à inclure la balise @memberOf ?

memberOf async est bien sûr. Aussi, nit : notez qu'il s'agit de memberOf et non de memberof

Pour le site, comment serait-il préférable de documenter les fonctions d'itération et de rappel ? Dans le fichier readme, les paramètres sont inclus le nom, tels que iteratee(item, callback), mais je ne pense pas que cela fonctionnera avec jsdoc.

En fait, je ne suis pas tout à fait sûr, avez-vous des idées @jdalton? Je sais que ramda le documente avec une balise @sig

Pas de précipitation non plus, c'est définitivement une grosse tâche, c'est pourquoi nous avons continué à nous y atteler. Merci de t'y intéresser quand même !

Les parseurs Doc gèrent généralement ce bit. Sinon, ils devraient fournir la sortie analysée pour que vous puissiez la reconstruire.

Est-il possible de lier facilement (par exemple) mapLimit et mapSeries à map ? Tout ce que vous avez à dire, c'est qu'il s'agit de versions à accès limité. Sinon, il y aura beaucoup de documents et d'exemples dupliqués. (Je pense que garder la signature est correct, cependant)

Hé, juste une mise à jour rapide car je n'ai pas pu faire de commit sur la pull request ces derniers jours. Je vais continuer à travailler dessus. J'ai un peu d' expérience web, donc je l' ai aussi été à la recherche dans le site d' entretien lodash question . Je téléchargerai le référentiel avec mes progrès une fois que je serai suffisamment avancé. L'objectif est d'obtenir quelque chose que l'async pourrait également utiliser.

S'amuser avec la génération de documentation localement avec les modifications de http://docstrap.github.io/docstrap/. Pensées @hargasinski & @aearly

J'ai déjà utilisé docstrap, j'aime vraiment ça ! C'est un modèle propre. Une idée sur le thème ? Ma préférence serait céruléen ou lumen . L'ardoise est bien aussi si vous voulez opter pour quelque chose de plus sombre.

Aussi, serait-ce le bon moment pour aborder le #975 ? Ce serait bien d'avoir un logo pour le site

Docstrap a l'air plutôt bien. Je pense que la fonction de recherche pourrait fonctionner mieux, cependant. Le thème n'a pas trop d'importance car il semble que nous puissions facilement le changer. (Et ils sont tous les mêmes, semble-t-il, à l'exception de quelques différences de couleur, plus ou moins.)

Toujours en gardant un œil sur https://github.com/lodash/lodash.github.io/issues/8 et https://github.com/lodash/lodash.github.io/issues/15 -- puisque les deux projets sont en utilisant JSDoc, nous pouvons réutiliser n'importe quelle stratégie qu'ils adoptent.

Le logo peut attendre, nous pouvons utiliser "Async" dans une belle police jusqu'à ce qu'une bonne idée de logo se présente. :Ouvre la bouche et ferme les yeux:

@megawac des travaux plus récents sur la publication de nos JSDocs ? Ce serait formidable d'avoir le site de documentation en place avant la version 2.0.

J'ai eu de la malchance à les faire construire et j'ai rencontré plusieurs problèmes en essayant de compiler correctement jsdocs sur ma machine

@aearly quand prévoyez-vous de faire la version 2.0 ? @megawac Actuellement, je ne peux pas m'engager dans le temps, mais je devrais avoir plus de temps dans les 2-3 prochaines semaines pour vous aider à travailler là-dessus. Si vous pouviez me guider dans la bonne direction, ou simplement énumérer certains des problèmes, je pourrais aider à les éliminer lentement.

Nous n'avons pas de date de sortie -- "quand ce sera prêt". Les docs ne sont pas une exigence stricte, juste un atout majeur, car certaines nouvelles méthodes ne sont documentées que via JSDoc.

@hargasinski c'est principalement que je n'ai jamais utilisé @jsdoc auparavant et j'ai eu du typedef ( queue et cargo ) s'affichent correctement

Oh d'accord, merci, je vais débourser le repo et jouer un peu avec, même si je ne pourrai pas faire grand chose avant la fin de la semaine prochaine. Je posterai une mise à jour si j'obtiens quelque chose de faisable.