Sinon: Stildokumentation "API-Spezifikation"

Übrigens, ich arbeite nicht an der aktuellen Dokumentation, was wertvoll ist. Ich schlage lediglich eine zusätzliche, umfassende Sache vor.

Java verfügt über automatische Tools zum Generieren von JavaDocs ohne manuelle Arbeit. Um so etwas in einer JS-Bibliothek zu erreichen, ist eine Menge manueller Arbeit erforderlich. Ich würde gerne so etwas sehen, aber ich befürchte, es würde ziemlich schnell veraltet sein.

Wir könnten uns ein wenig mit Code-Annotationen und Werkzeugen beschäftigen. Vielleicht gibt es praktikable Optionen.

Ich weiß, dass es in anderen Threads erwähnt wurde, aber ich denke ganz einfach, dass die gesamte Bibliothek mit jsDoc dokumentiert werden sollte. Es ist so etwas wie ein Defacto-Standard für JavaScript (oder zumindest das stärkste Argument, das es für eines gibt). Wir könnten einfach die API veröffentlichen, beginnend mit der minimalen Dokumentation, und ein großes "in Bearbeitung" -Schild an die Wand hängen und von dort aus bauen.

@mantoni Es gibt viele Tools zum automatischen Generieren von JSDocs. Ich sehe keine Version 1 als Problem. Sie müssen nicht überall @typedef s erstellen. Einfach haben

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

würde ziemlich viel helfen.

Hallo @ 76784 , das ist ein großartiger Input! 😊

Ich muss jedoch einige Überlegungen anstellen.

Ich mag JSDoc sehr. Das ist auch das, was wir für Chai.js und es hat bisher ziemlich gut funktioniert, da es in der Lage ist, Dinge in Namespaces zu trennen und den Code immer mit den Dokumenten synchron zu halten, da sie direkt nebeneinander liegen.

Ich würde jedoch nicht zustimmen, dass Javas Dokumentation der "Goldstandard" ist. Ich finde Java-Dokumente sehr trocken. Es ist gut als Referenz, aber schlecht zum Lernen oder Groken größerer Teile davon. Ich mag die Tatsache, dass Dokumente für Sinon im freundlichen klassischen Klartextstil geschrieben sind. IMO, die die Adoption vorantreibt. Als API-Referenz sind sie auch ziemlich gut IMO.

Ich denke, es wäre natürlich gut, JSDocs zu haben, aber es ist wichtig zu beachten, dass dies einen äußerst erheblichen Aufwand erfordern würde.

Wenn @ 76784 einen Zweig gründen und einige Konzepte

@ Lucasfcosta

Ich finde Java-Dokumente sehr trocken. Es ist gut als Referenz, aber schlecht zum Lernen oder Groken größerer Teile davon.

Ich bin nicht anderer Meinung. Ich sage nur, dass die beiden Dinge - Dokumentation und Tutorial - getrennte Dinge sein sollten. Die Trockenheit von Javadocs ist ein Plus. Man kann dorthin gehen und durch diese Konvention in trockener Sprache herausfinden, was das "Ding" tut. Und natürlich ist es vor allem umfassend. Ich möchte keine wortreiche Satzstruktur in meiner Dokumentation - das möchte ich in meinem Tutorial.

Ich bin kein Experte für JSDoc, aber ich frage mich, ob es in den JSDoc-Kommentaren eine einfache Möglichkeit gibt, auf das Tutorial für den Eintrag zu verlinken.

Was das Einbringen von Proofs-of-Concept anbelangt ,

Dieses Problem wurde automatisch als veraltet markiert, da es in letzter Zeit keine Aktivitäten gab. Es wird geschlossen, wenn keine weitere Aktivität stattfindet. Vielen Dank für Ihre Beiträge.

Ich habe dieses Problem angeheftet, damit es nicht von Stale Bot geschlossen wird

Wenn wir uns dazu entschließen, diesen Weg zu gehen, sollten wir meiner Meinung nach so etwas wie https://github.com/gajus/eslint-plugin-jsdoc verwenden ... die Regeln sollten wahrscheinlich in eslint-config-sinon .

Es tut mir leid, dass ich hier ein- und aussteigen muss - es hängt wirklich von einigen Arbeitsprioritäten ab. Und ich weiß nicht, ob dies der richtige Thread ist, sondern nur, um mehr Feedback zur vorhandenen Dokumentation zu geben ...

Wenn ich mir so etwas wie Spione ansehe: https://sinonjs.org/releases/v7.4.1/spies/

Ich arbeite zufällig mit Mocha, das eine andere Syntax hat als das, was im ersten Block gezeigt wird.

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

    PubSub.publishSync("message");

    assertTrue(callback.called);
}

Die Tatsache, dass ich Mokka anstelle von dem verwende, was das ist (Jasmin?), Ist kein Problem . Sie sind offensichtlich ähnlich. Aber was macht das Beispiel schwer zu verstehen ist , dass Sie die Funktion nicht zeigen , die getestet wird.

Ich denke, das sollte getan werden, wenn Sie Beispiele nennen wollen. Zeigen Sie die minimale Arbeitsfunktionalität aller getesteten Objekte an. Gleiches Problem hier mit myLib : https://sinonjs.org/releases/v7.4.1/fake-xhr-and-server/

Ich verstehe - myLib würde ich schreiben. Aber Sie fordern viele Neulinge auf, dieses Zeug lernen zu müssen, ohne zu sehen, gegen was sie testen.

Eigentlich verwendet dieser Test Mochas Syntax, Sie verwenden nur den Standard-BDD-Stil (von beiden) :-) Er wird auch von einigen anderen Bibliotheken geteilt, wie z. B. Buster JS, den Sinons ursprünglicher Schöpfer ebenfalls (mit-) erstellt hat. Auf jeden Fall wäre es wahrscheinlich sinnvoll, wenn jemand alle Beispiele auf den gängigsten Stil aktualisiert :-)

Die anderen Punkte sind durchaus gültig und haben wir bereits besprochen. Tatsächlich haben wir darüber gesprochen, lauffähige, getestete und eingebettete Beispiele zu haben, um die Gültigkeit zu gewährleisten. Was implizit diese Probleme beheben würde. Aber ja, jemand muss sich setzen und es tun ...

Tatsächlich verwendet dieser Test die Mocha-Syntax

Was?? Jetzt muss ich mich über die Mokka-Dokumentation lustig machen. :-)

Ich habe versucht, diese Bemühungen unter https://github.com/sinonjs/samsam/pull/82 zu starten