Async: README es demasiado largo para npm

Esto está relacionado tangencialmente con el # 859. Hemos querido renovar los documentos de Async durante un tiempo: crear un sitio más similar a los documentos de Lodash.

Eso sería genial, ¿necesitas ayuda con eso? No sé qué tan avanzado estás en el # 859.

No hemos finalizado la estrategia de construcción exacta (esperando ver cómo funciona un impulso similar para los documentos de Lodash). Como mínimo, queremos copiar los documentos para cada método en un bloque JSDoc en cada archivo fuente (con etiquetas completas e información de tipo), con la intención de analizarlos y construir un sitio de documentación a partir de ellos.

@hargasinski definitivamente nos vendría bien ayuda con esto. Si usted o cualquier otra persona está interesado en ayudar a portar nuestros documentos al formato compatible con jsdoc en el código, sería muy apreciado. Recomiendo hacer este método por método. Si está interesado, puedo crear una sucursal para trabajar para que varias personas puedan contribuir si es necesario

Eche un vistazo a https://github.com/lodash/lodash/blob/master/lodash.js#L8428 -L8470 si está buscando inspiración.

Si obtenemos el código en un estado en el que está documentado en JSDoc, puedo crear un sitio de documentos similar a ramdas, lazys o lodashs

@megawac ¡ gracias! Veré cómo lo hace Lodash. Tengo mañana libre, así que probablemente podría dedicar una buena cantidad de tiempo a trabajar en ello. Publicaré un comentario sobre lo lejos que llegué.

Es posible que haya subestimado la cantidad de tiempo que llevará esto, pero pude terminar la documentación de los métodos de recopilación. Debería poder terminar el resto mañana después del trabajo. Creé una solicitud de extracción para que pueda ver lo que he hecho hasta ahora y si es necesario cambiar algo. Tengo un par de preguntas rápidas.

1. Dado que no hay un constructor async real, ¿debería seguir incluyendo la etiqueta @memberOf ?
2. @megawac Para el sitio, ¿cómo sería mejor documentar las funciones iteratee y callback ? En el archivo Léame, los parámetros incluyen el nombre, como iteratee(item, callback) , pero no creo que esto funcione con jsdoc. He estado haciendo algo similar al ejemplo de lodash que vinculó, y solo @param , como Invoked with (item, callback) . El sitio jsdoc recomienda algo como:

/**
 * 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
 */

Dado que no hay un constructor asíncrono real, ¿debería seguir incluyendo la etiqueta @memberOf ?

memberOf async está bien seguro. Además, nit: tenga en cuenta que es memberOf y no memberof

Para el sitio, ¿cómo sería mejor documentar las funciones iteratee y callback? En el archivo Léame, los parámetros incluyen el nombre, como iteratee (elemento, devolución de llamada), pero no creo que esto funcione con jsdoc.

De hecho, no estoy del todo seguro, ¿tienes pensamientos @jdalton? Sé que ramda lo documenta con una etiqueta @sig

Además, no hay prisa en esto, definitivamente es una gran tarea y es por eso que hemos seguido adelante. ¡Gracias por investigarlo!

Los analizadores de documentos generalmente manejan ese bit. De lo contrario, deberían proporcionar la salida analizada para que la reconstruyas.

¿Es posible vincular fácilmente (por ejemplo) mapLimit y mapSeries a map ? Todo lo que tienes que decir es que son versiones limitadas por simultaneidad. De lo contrario, habrá muchos documentos y ejemplos duplicados. (Aunque creo que mantener la firma está bien)

Oye, solo una actualización rápida, ya que no he podido realizar ningún compromiso con la solicitud de extracción en los últimos días. Todavía voy a seguir trabajando en eso. Tengo un poco de experiencia en la red, por lo que también he estado buscando en el mantenimiento del sitio lodash tema . Subiré el repositorio con mi progreso una vez que llegue lo suficientemente lejos en él. El objetivo es obtener algo que async también pueda usar.

Jugando con la generación de documentación localmente con los cambios de @hargasinski (ahora en master). Creo que me gusta esta plantilla http://docstrap.github.io/docstrap/. Pensamientos @hargasinski & @aearly

He usado docstrap antes, ¡me gusta mucho! Es una plantilla limpia. ¿Alguna idea sobre el tema? Mi preferencia sería cerúleo o lumen . La pizarra también es buena si quieres optar por algo más oscuro.

Además, ¿sería este un buen momento para abordar el número 975? Sería bueno tener un logo para el sitio.

Docstrap se ve bastante bien. Sin embargo, creo que la función de búsqueda podría funcionar mejor. El tema no importa demasiado, ya que parece que podemos cambiarlo fácilmente. (Y parece que todos son iguales, salvo por algunas diferencias de color, más o menos).

Todavía vigilando https://github.com/lodash/lodash.github.io/issues/8 y https://github.com/lodash/lodash.github.io/issues/15 , ya que ambos proyectos son utilizando JSDoc, podemos reutilizar cualquier estrategia que adopten.

El logo puede esperar, podemos usar "Async" en un tipo de letra agradable hasta que surja una buena idea de logo. : ojos_cerrados_ lengua_atacada:

@megawac ¿Algún trabajo más reciente sobre la publicación de nuestros JSDocs? Sería genial tener el sitio de documentos en su lugar antes de la versión 2.0.

Tuve mala suerte al hacer que se compilaran y me encontré con varios problemas al intentar compilar jsdocs correctamente en mi máquina

@aearly, ¿ cuándo planea hacer la versión 2.0? @megawac Actualmente, no puedo comprometerme con el tiempo, pero debería tener más tiempo en las próximas 2-3 semanas para ayudarlo a trabajar en esto. Si pudiera guiarme en la dirección correcta, o simplemente enumerar algunos de los problemas, podría ayudar a resolverlos lentamente.

No tenemos fecha de lanzamiento, "cuando esté listo". Los documentos no son un requisito estricto, solo algo importante, ya que algunos métodos nuevos solo se documentan a través de JSDoc.

@hargasinski es principalmente que nunca he usado @jsdoc anteriormente y he tenido problemas para typedef ( queue y cargo ) aparecieran correctamente

Oh, está bien, gracias, bifurcaré el repositorio y jugaré un poco con él, aunque no podré hacer mucho hasta finales de la semana que viene. Publicaré una actualización si obtengo algo factible.