Sinon: Documentación de estilo "Especificación API"

Por cierto, no estoy insistiendo en la documentación actual, que es valiosa. Simplemente sugiero algo adicional y completo.

Java tiene herramientas automáticas para generar JavaDocs sin trabajo manual. Para lograr algo como esto en una biblioteca JS se requiere mucho trabajo manual. Me encantaría ver algo así, pero me temo que quedará obsoleto con bastante rapidez.

Podríamos hablar un poco sobre las anotaciones de código y las herramientas. Quizás haya opciones viables.

Sé que se ha mencionado en otros subprocesos, pero creo que, de manera muy simple, toda la biblioteca debería estar documentada con jsDoc. Es una especie de estándar de facto para JavaScript (o, al menos, el argumento más fuerte que existe para uno). Podríamos simplemente publicar la API comenzando con una cobertura de documentación mínima, y ​​poner un gran letrero de "en progreso" en la pared, y construir a partir de ahí.

@mantoni Hay muchas herramientas para generar JSDocs automáticamente. No veo que una v1 de esto sea un problema. No es necesario crear @typedef s en todas partes. Solo teniendo

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

ayudaría bastante.

Hola @ 76784 , ¡qué gran aporte! 😊

Sin embargo, tengo algunas consideraciones que hacer.

Me gusta bastante JSDoc. Eso es también lo que usamos en Chai.js y ha funcionado bastante bien hasta ahora debido a que podemos separar las cosas en espacios de nombres y mantener siempre el código sincronizado con los documentos, ya que están uno al lado del otro.

Sin embargo, no estoy de acuerdo con que la documentación de Java sea el "estándar de oro". Encuentro que los documentos de Java son muy secos. Es bueno como referencia, pero malo para aprender o asimilar partes más importantes. Me gusta el hecho de que los documentos de Sinon están escritos en un estilo clásico de texto plano amigable. En mi opinión, eso ayuda a impulsar la adopción. Además, como referencia de API, son bastante buenos en mi opinión.

Creo que sería bueno, por supuesto, tener JSDocs, pero es importante notar que requeriría un esfuerzo extremadamente significativo.

Si @ 76784 iniciara una rama y desarrollara algunos conceptos, creo que algunas personas atraídas por la idea podrían aferrarse rápidamente a ella y ayudar. La superficie de la API no es _ tan_ grande.

@lucasfcosta

Encuentro que los documentos de Java son muy secos. Es bueno como referencia, pero malo para aprender o asimilar partes más importantes.

No estoy en desacuerdo. Simplemente digo que las dos cosas, la documentación y el tutorial, deberían ser cosas separadas. La sequedad de los javadocs es una ventaja. Uno puede ir allí y descubrir, a través de esta convención de lenguaje seco, _qué_ hace la "cosa". Y, por supuesto, lo más importante es que es de naturaleza integral. No quiero una estructura de oración prolija en mi documentación, quiero eso en mi tutorial.

No soy un experto en JSDoc, pero me pregunto si en los comentarios de JSDoc habría una manera fácil de vincular al tutorial para la entrada.

En cuanto a contribuir con algunas pruebas de concepto sobre esto, @ fatso83 , tengo poco tiempo en este momento (lo sé, ¿quién no?), Pero podría estar en una mejor posición para más adelante en el año. . Sería una excelente manera de aprender a Sinon a fondo.

Este problema se ha marcado automáticamente como obsoleto porque no ha tenido actividad reciente. Se cerrará si no se produce más actividad. Gracias por sus aportaciones.

He anclado este problema, por lo que el bot Stale no lo cierra

Si decidimos seguir este camino, creo que deberíamos usar algo como https://github.com/gajus/eslint-plugin-jsdoc ... las reglas probablemente deberían ir en eslint-config-sinon .

Lamento sumergirme en esto, realmente está impulsado por algunas prioridades laborales. Y no sé si este es el hilo correcto, pero solo para ofrecer más comentarios sobre la documentación existente ...

Mientras miro algo como espías: https://sinonjs.org/releases/v7.4.1/spies/

Resulta que estoy trabajando con Mocha, que tiene una sintaxis diferente a la que se muestra en el primer fragmento.

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

    PubSub.publishSync("message");

    assertTrue(callback.called);
}

El hecho de que esté usando Mocha en lugar de lo que sea (¿Jasmine?) No es gran cosa . Obviamente son similares. Pero lo que hace que ese ejemplo sea difícil de entender es que no muestra la función que se está probando.

Eso es algo que creo que debería hacerse si va a proporcionar ejemplos. Muestre la funcionalidad mínima de trabajo de cualquier cosa que se esté probando. El mismo problema aquí, con myLib : https://sinonjs.org/releases/v7.4.1/fake-xhr-and-server/

Lo entiendo - myLib es algo que escribiría. Pero le estás pidiendo a muchos novatos que aprendan estas cosas sin ver nada de lo que están probando.

En realidad, esa prueba ES usando la sintaxis de Mocha, solo estás usando el estilo BDD más estándar (de los dos) :-) También es compartido por algunas otras bibliotecas, como Buster JS, que el creador original de Sinon también (co-) creó. De todos modos, probablemente tendría sentido que alguien actualice todos los ejemplos al estilo más común en uso :-)

En cuanto a los otros puntos, estos son bastante válidos, y algo que hemos discutido. En realidad, hablamos de tener ejemplos integrados, probados y ejecutables, lo que garantiza la validez. Lo que implícitamente solucionaría esos problemas. Pero sí, alguien necesita sentarse y hacerlo ...

En realidad, esa prueba está usando la sintaxis de Mocha.

¿¿Qué?? Ahora voy a tener que despotricar sobre la documentación de Mocha. :-)

Intenté comenzar este esfuerzo en https://github.com/sinonjs/samsam/pull/82. Sus comentarios son bienvenidos, publíquelos en ese PR.