Sinon: Documentação de estilo de "Especificação de API"

A propósito, não estou insistindo na documentação atual, que é valiosa. Estou apenas sugerindo algo adicional e abrangente.

Java possui ferramentas automáticas para gerar JavaDocs sem trabalho manual. Para conseguir algo assim em uma biblioteca JS, é necessário muito trabalho manual. Adoraria ver algo assim, mas temo que desatualize muito rapidamente.

Poderíamos pedalar um pouco sobre anotações de código e ferramentas. Talvez existam opções viáveis.

Eu sei que foi criado em outros threads, mas acho que, de forma muito simples, toda a biblioteca deve ser documentada com jsDoc. É uma espécie de padrão de fato para JavaScript (ou, pelo menos, o argumento mais forte que existe para tal). Poderíamos apenas publicar a API começando com a cobertura de documentação mínima e colocar uma grande placa de "em andamento" na parede e construir a partir daí.

@mantoni Existem várias ferramentas para geração automática de JSDocs. Não vejo um v1 disso ser um problema. Você não precisa criar @typedef s em todos os lugares. Apenas tendo

/**
  <strong i="8">@param</strong> {String} [foo] optional string
  <strong i="9">@example</strong> Create foo instance
       var foo = dooFoo('somestring') 
*/ 

ajudaria um pouco.

Olá @ 76784 , essa é uma ótima contribuição! 😊

Tenho, no entanto, algumas considerações a fazer.

Eu gosto bastante do JSDoc. Isso também é o que usamos em Chai.js e funcionou muito bem até agora devido à capacidade de separar as coisas em namespaces e sempre manter o código em sincronia com os documentos, já que eles estão próximos um do outro.

No entanto, eu discordo que a documentação do Java é o "padrão ouro". Acho que os documentos Java são muito secos. É bom para referência, mas ruim para aprender ou grocar partes maiores dele. Gosto do fato de que os documentos para Sinon são escritos em um estilo clássico de texto simples e amigável. IMO que ajuda a impulsionar a adoção. Além disso, como uma referência de API, eles são muito bons em IMO.

Acho que seria bom, claro, ter JSDocs, mas é importante notar que isso exigiria um esforço extremamente significativo.

Se @ 76784 abrisse uma ramificação e desenvolvesse alguns conceitos, acho que algumas pessoas atraídas pela ideia poderiam rapidamente se agarrar a ela e ajudar. A superfície da API não é _tão_ grande.

@lucasfcosta

Acho que os documentos Java são muito secos. É bom para referência, mas ruim para aprender ou grocar partes maiores dele.

Eu não discordo. Estou apenas dizendo que as duas coisas - documentação e tutorial - devem ser coisas separadas. A secura dos javadocs é uma vantagem. Alguém pode ir lá e descobrir, por meio dessa convenção de linguagem seca, _o_ que a "coisa" faz. E, claro, o mais importante, é abrangente por natureza. Não quero estrutura de frase prolixo em minha documentação - quero isso em meu tutorial.

Não sou um especialista em JSDoc, mas gostaria de saber se nos comentários JSDoc haveria uma maneira fácil de vincular ao tutorial para a entrada.

Quanto a contribuir com algumas provas de conceito sobre isso, @ fatso83 , estou com um pouco de falta de tempo no momento (eu sei, quem não é?), Mas posso estar em uma posição melhor no final do ano . Seria uma ótima maneira de aprender completamente sobre Sinon.

Este problema foi marcado automaticamente como obsoleto porque não teve atividades recentes. Ele será fechado se nenhuma outra atividade ocorrer. Obrigado por suas contribuições.

Eu marquei esse problema para que ele não seja fechado pelo bot desatualizado

Se decidirmos seguir por esse caminho, acho que devemos usar algo como https://github.com/gajus/eslint-plugin-jsdoc ... as regras provavelmente devem ir para eslint-config-sinon .

Desculpe entrar e sair disso - é realmente impulsionado por algumas prioridades de trabalho. E não sei se este é o tópico certo, mas apenas para oferecer mais feedback sobre a documentação existente ...

Quando vejo algo como espiões: https://sinonjs.org/releases/v7.4.1/spies/

Acontece que estou trabalhando com o Mocha, que tem uma sintaxe diferente da mostrada na primeira parte.

"test should call subscribers on publish": function () {
    var callback = sinon.spy();
    PubSub.subscribe("message", callback);

    PubSub.publishSync("message");

    assertTrue(callback.called);
}

O fato de eu estar usando o Mocha em vez do que quer que seja (Jasmine?) Não é nada demais . Eles são obviamente semelhantes. Mas o que torna esse exemplo difícil de entender é que você não mostra a função que está sendo testada.

Acho que isso deve ser feito se você for fornecer exemplos. Mostre a funcionalidade mínima de trabalho de tudo o que está sendo testado. Mesmo problema aqui, com myLib : https://sinonjs.org/releases/v7.4.1/fake-xhr-and-server/

Eu entendi - myLib é algo que eu escreveria. Mas você está pedindo muito ao novato para aprender essas coisas sem ver nada contra o que está testando.

Na verdade, esse teste ESTÁ usando a sintaxe do Mocha, você está apenas usando o estilo BDD mais padrão (dos dois) :-) Ele também é compartilhado por algumas outras bibliotecas, como Buster JS, que o criador original do Sinon também (co-) criou. De qualquer forma, provavelmente faria sentido que alguém atualizasse todos os exemplos para o estilo mais comum em uso :-)

Quanto aos outros pontos, são bastante válidos e já discutidos. Na verdade, discutimos ter exemplos executáveis, testados e incorporados, garantindo a validade. O que implicitamente resolveria esses problemas. Mas sim, alguém precisa se sentar e fazer isso ...

Na verdade, esse teste ESTÁ usando a sintaxe do Mocha

O que?? Agora vou ter que fazer um discurso retórico sobre a documentação do Mocha. :-)

Tentei iniciar esse esforço em https://github.com/sinonjs/samsam/pull/82. Seus comentários são bem-vindos, por favor, poste-os nesse PR.