Sinon: Documentation de style "Spécification API"

Au fait, je ne m'appelle pas sur la documentation actuelle, qui est précieuse. Je suggère simplement une chose supplémentaire et complète.

Java dispose d'outils automatiques pour générer des JavaDocs sans travail manuel. Pour réaliser quelque chose comme ça dans une bibliothèque JS, il faut une tonne de travail manuel. J'adorerais voir quelque chose comme ça, mais je crains qu'il ne soit dépassé assez rapidement.

Nous pourrions faire un peu de vélo sur les annotations de code et les outils. Il existe peut-être des options viables.

Je sais que cela a été évoqué sur d'autres threads, mais je pense, très simplement, que toute la bibliothèque devrait être documentée avec jsDoc. C'est en quelque sorte un standard de facto pour JavaScript (ou, du moins, l'argument le plus fort qui soit). Nous pourrions simplement publier l'API en commençant par une couverture de documentation minimale, et mettre un grand signe "en cours" sur le mur, et construire à partir de là.

@mantoni Il existe de nombreux outils pour générer automatiquement des JSDocs. Je ne vois pas une v1 de ceci être un problème. Vous n'avez pas besoin de créer des @typedef partout. Juste avoir

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

aiderait un peu.

Salut @ 76784 , c'est une excellente contribution! 😊

J'ai cependant quelques considérations à faire.

J'aime assez JSDoc. C'est aussi ce que nous utilisons sur Chai.js et cela a plutôt bien fonctionné jusqu'à présent car il est possible de séparer les choses en espaces de noms et de toujours synchroniser le code avec les documents puisqu'ils sont juste à côté de l'autre.

Cependant, je ne suis pas d'accord pour dire que la documentation de Java est la "norme d'or". Je trouve que les documents Java sont très secs. C'est bon pour référence, mais mauvais pour apprendre ou en faire de plus grandes parties. J'aime le fait que les documents pour Sinon soient écrits dans un style classique convivial en texte brut. IMO qui aide à favoriser l'adoption. En outre, en tant que référence API, ils sont plutôt bons pour l'OMI.

Je pense que ce serait bien, bien sûr, d'avoir JSDocs, mais il est important de noter que cela demanderait un effort extrêmement important.

Si @ 76784 commençait une branche et

@lucasfcosta

Je trouve que les documents Java sont très secs. C'est bon pour référence, mais mauvais pour apprendre ou en faire de plus grandes parties.

Je ne suis pas en désaccord. Je dis simplement que les deux choses - la documentation et le didacticiel - devraient être des choses distinctes. La sécheresse des javadocs est un plus. On peut y aller et découvrir, grâce à cette convention en langage sec, ce que fait la «chose». Et bien sûr, surtout, il est de nature globale. Je ne veux pas de structure de phrase verbeuse dans ma documentation - je veux cela dans mon tutoriel.

Je ne suis pas un expert en JSDoc, mais je me demande si dans les commentaires JSDoc il y aurait un moyen facile de créer un lien vers le tutoriel pour l'entrée.

En ce qui concerne la contribution de quelques preuves de concept à ce sujet, @ fatso83 , je

Ce problème a été automatiquement marqué comme obsolète car il n'a pas eu d'activité récente. Il sera fermé si aucune autre activité ne se produit. Merci pour vos contributions.

J'ai épinglé ce problème, donc il n'est pas fermé par le bot obsolète

Si nous décidons de suivre cette voie, alors je pense que nous devrions utiliser quelque chose comme https://github.com/gajus/eslint-plugin-jsdoc ... les règles devraient probablement aller dans eslint-config-sinon .

Désolé de plonger dans et hors de cela - il est vraiment motivé par certaines priorités de travail. Et je ne sais pas si c'est le bon fil, mais juste pour offrir un peu plus de commentaires sur la documentation existante ...

En regardant quelque chose comme des espions: https://sinonjs.org/releases/v7.4.1/spies/

Il se trouve que je travaille avec Mocha, qui a une syntaxe différente de ce qui est montré dans le premier morceau.

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

    PubSub.publishSync("message");

    assertTrue(callback.called);
}

Le fait que j'utilise Mocha au lieu de tout ce qui est (Jasmine?) N'est pas grave . Ils sont évidemment similaires. Mais ce qui rend cet exemple difficile à comprendre, c'est que vous ne montrez pas la fonction testée.

Je pense que c'est quelque chose qui devrait être fait si vous voulez donner des exemples. Montrez la fonctionnalité de travail minimale de tout ce qui est testé. Même problème ici, avec myLib : https://sinonjs.org/releases/v7.4.1/fake-xhr-and-server/

Je comprends - myLib est quelque chose que j'écrirais. Mais vous demandez à beaucoup de débutants d'apprendre ce genre de choses sans voir quoi que ce soit contre quoi ils testent.

En fait, ce test utilise la syntaxe de Mocha, vous utilisez simplement le style BDD plus standard (des deux) :-) Il est également partagé par d'autres bibliothèques, telles que Buster JS, que le créateur original de Sinon a également (co-) créé. Quoi qu'il en soit, il serait probablement logique que quelqu'un mette à jour tous les exemples avec le style le plus courant :-)

Quant aux autres points, ils sont tout à fait valables et nous en avons discuté. En fait, nous avons discuté d'avoir des exemples exécutables, testés et intégrés, garantissant la validité. Ce qui résoudrait implicitement ces problèmes. Mais oui, quelqu'un doit s'asseoir et le faire ...

En fait, ce test est en utilisant la syntaxe de Mocha

Quoi?? Maintenant, je vais devoir me plaindre de la documentation de Mocha. :-)

J'ai essayé de démarrer cet effort sur https://github.com/sinonjs/samsam/pull/82. Vos commentaires sont les bienvenus, veuillez les poster sur ce PR.