Async: README é muito longo para npm

Isso está tangencialmente relacionado a # 859. Queríamos reformular os documentos do Async por um tempo - criar um site mais semelhante aos documentos do Lodash.

Isso seria incrível, você precisa de ajuda com isso? Eu não sei o quão longe você está no # 859.

Ainda não finalizamos a estratégia de construção exata (esperando para ver como um impulso semelhante para os documentos de Lodash funcionará). No mínimo, queremos copiar os documentos de cada método em um bloco JSDoc em cada arquivo de origem (com tags completas e informações de tipo), com a intenção de analisá-los e construir um site de documentação a partir deles.

@hargasinski nós definitivamente precisamos de ajuda com isso. Se você ou qualquer outra pessoa estiver interessada em ajudar a portar nossos documentos para formatação compatível com jsdoc no código, será muito grato. Eu recomendo fazer esse método por método. Se você estiver interessado, posso criar um branch para trabalhar para que várias pessoas possam contribuir, se necessário

Dê uma olhada em https://github.com/lodash/lodash/blob/master/lodash.js#L8428 -L8470 se você estiver procurando por inspiração.

Se obtivermos o código em um estado onde está documentado no JSDoc, posso criar um site de documentos semelhante a ramdas, lazys ou lodashs

@megawac obrigado! Vou ver como o lodash faz isso. Tenho amanhã de folga, então provavelmente poderia passar uma boa quantidade de tempo trabalhando nisso. Vou postar um comentário sobre o quão longe eu chego.

Posso ter subestimado o tempo que isso vai levar, mas consegui terminar a documentação dos métodos de coleta. Devo conseguir terminar o resto amanhã, depois do trabalho. Criei uma solicitação pull para que você possa ver o que fiz até agora e se algo precisa ser alterado. Eu tenho algumas perguntas rápidas.

1. Como não existe um construtor async real, devo continuar incluindo a tag @memberOf ?
2. @megawac Para o site, como seria melhor documentar as funções iteratee e callback ? No leia-me, os parâmetros incluem o nome, como iteratee(item, callback) , mas não acho que isso funcionará com jsdoc. Tenho feito algo semelhante ao exemplo de lodash que você vinculou, e apenas incluindo a assinatura como a última linha na descrição de @param , como Invoked with (item, callback) . O site jsdoc recomenda 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
 */

Como não há um construtor assíncrono real, devo continuar incluindo a tag @memberOf ?

memberOf assíncrono é bom com certeza. Além disso, nit: observe que é memberOf e não memberof

Para o site, qual seria a melhor maneira de documentar as funções iteratee e callback? No readme, os parâmetros incluem o nome, como iteratee (item, callback), mas não acho que isso funcionará com jsdoc.

Na verdade, não tenho certeza absoluta, o que você acha, @jdalton? Eu sei que ramda o documenta com uma tag @sig

Também sem pressa, esta é definitivamente uma grande tarefa, e é por isso que continuamos apostando nela. Obrigado por dar uma olhada nisso!

Os analisadores de documentos geralmente lidam com essa parte. Caso contrário, eles devem fornecer a saída analisada para você reconstruir.

É possível vincular facilmente (por exemplo) mapLimit e mapSeries a map ? Tudo o que você tem a dizer é que são as versões limitadas por simultaneidade. Caso contrário, haverá muitos documentos e exemplos duplicados. (Mas acho que não há problema em manter a assinatura)

Ei, só uma atualização rápida, já que não consegui fazer nenhum commit para a solicitação pull nos últimos dias. Eu ainda vou continuar trabalhando nisso. Eu tenho um pouco de experiência na web, então também estive investigando o problema de manutenção do site Lodash. Vou carregar o repositório com o meu progresso assim que chegar muito longe nele. O objetivo é obter algo que o assíncrono também possa usar.

Brincando com a geração de documentação localmente com as mudanças de http://docstrap.github.io/docstrap/. Pensamentos @hargasinski & @aearly

Já usei o docstrap antes, gosto muito dele! É um modelo limpo. Alguma ideia sobre o tema? Minha preferência seria cerúleo ou lúmen . A ardósia também é boa se você quiser algo mais escuro.

Além disso, seria um bom momento para abordar o número 975? Seria bom ter um logotipo para o site

Docstrap parece muito bom. Acho que o recurso de pesquisa poderia funcionar melhor, no entanto. O tema não importa muito, pois parece que podemos mudá-lo facilmente. (E eles são todos iguais ao que parece, exceto por algumas diferenças de cor, mais ou menos.)

Ainda de olho em https://github.com/lodash/lodash.github.io/issues/8 e https://github.com/lodash/lodash.github.io/issues/15 - já que ambos os projetos são usando JSDoc, podemos reutilizar qualquer estratégia que eles adotem.

O logotipo pode esperar, podemos usar "Async" em um tipo de letra legal até que uma boa ideia de logotipo apareça. :língua para fora olhos fechados:

@megawac algum trabalho mais recente sobre a publicação de nossos JSDocs? Seria ótimo ter o site de documentos no local antes do lançamento 2.0.

Tive má sorte em conseguir que eles fossem compilados e tive vários problemas ao tentar compilar jsdocs corretamente na minha máquina

@aearly quando você está planejando fazer o lançamento 2.0? @megawac Atualmente, não posso assumir um compromisso de tempo, mas devo ter mais algum tempo nas próximas 2-3 semanas para ajudá-lo a trabalhar nisso. Se você pudesse me guiar na direção certa, ou apenas listar alguns dos problemas, eu poderia ajudar lentamente a eliminá-los.

Não temos data de lançamento - "quando estiver pronto". Os documentos não são um requisito difícil, apenas um requisito importante, já que alguns novos métodos são documentados apenas por meio do JSDoc.

@hargasinski é principalmente porque nunca usei @jsdoc anteriormente e tive problemas para typedef implementações ( queue e cargo ) aparecessem corretamente

Ok, obrigado, vou bifurcar o repo e brincar um pouco com ele, embora não consiga fazer muito até o final da próxima semana. Vou postar uma atualização se conseguir algo viável.