Async: README ist zu lang für npm

Dies hängt tangential mit #859 zusammen. Wir wollten schon seit einiger Zeit die Dokumente von Async überarbeiten – eine Site erstellen, die den Dokumenten von Lodash ähnlicher ist.

Das wäre super, brauchst du dabei Hilfe? Ich weiß nicht, wie weit du mit # 859 bist.

Wir haben die genaue Baustrategie noch nicht abgeschlossen (abwarten, wie ein ähnlicher Schub für Lodashs Dokumente funktioniert). Zumindest möchten wir die Dokumentation für jede Methode in einen JSDoc-Block in jeder Quelldatei kopieren (mit vollständigen Tags und Typinformationen), um sie zu analysieren und daraus eine Dokumentationsseite zu erstellen.

@hargasinski wir könnten dabei definitiv Hilfe gebrauchen. Wenn Sie oder jemand anderes daran interessiert ist, unsere Dokumente auf eine jsdoc kompatible Formatierung im Code zu portieren, wäre dies sehr willkommen. Ich empfehle, diese Methode nach Methode durchzuführen. Wenn Sie interessiert sind, kann ich einen Zweig erstellen, um abzuarbeiten, damit mehrere Personen bei Bedarf beitragen können

Werfen Sie einen Blick auf https://github.com/lodash/lodash/blob/master/lodash.js#L8428 -L8470, wenn Sie nach Inspiration suchen.

Wenn wir den Code in einem Zustand erhalten, in dem er in JSDoc dokumentiert ist, kann ich eine Docs-Site ähnlich wie Ramdas, Lazys oder Lodashs erstellen

@megawac danke! Ich werde mir ansehen, wie Lodash das macht. Ich habe morgen frei, also könnte ich wahrscheinlich viel Zeit damit verbringen, daran zu arbeiten. Ich werde einen Kommentar schreiben, wie weit ich komme.

Ich habe vielleicht den Zeitaufwand dafür unterschätzt, aber ich konnte die Dokumentation für die Erfassungsmethoden fertigstellen. Den Rest sollte ich morgen nach der Arbeit erledigen können. Ich habe eine Pull-Anfrage erstellt, damit Sie sehen können, was ich bisher getan habe und ob etwas geändert werden muss. Ich habe ein paar kurze Fragen.

1. Da es keinen echten async Konstruktor gibt, sollte ich das @memberOf- Tag weiterhin
2. @megawac Wie wäre es für die Site am besten, die Funktionen iteratee und callback zu dokumentieren? In der Readme sind die Parameter mit dem Namen enthalten, z. B. iteratee(item, callback) , aber ich glaube nicht, dass dies mit jsdoc funktioniert. Ich habe etwas Ähnliches wie das von Ihnen verlinkte @param- Beschreibung Invoked with (item, callback) . Die jsdoc- Site empfiehlt etwa:

/**
 * 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
 */

Da es keinen echten asynchronen Konstruktor gibt, sollte ich das @memberOf- Tag

memberOf async ist sicher in Ordnung. Übrigens: Beachten Sie, dass es memberOf und nicht memberof

Wie wäre es für die Site am besten, die Iteratee- und Callback-Funktionen zu dokumentieren? In der Readme sind die Parameter mit dem Namen enthalten, z. B. iteratee(item, callback), aber ich glaube nicht, dass dies mit jsdoc funktioniert.

Ich bin mir eigentlich nicht ganz sicher, hast du Gedanken @jdalton? Ich weiß, dass Ramda es mit einem benutzerdefinierten @sig Tag dokumentiert

Auch keine Eile, dies ist definitiv eine große Aufgabe, weshalb wir uns immer wieder daran gemacht haben. Danke, dass du es dir angeschaut hast!

Doc-Parser verarbeiten normalerweise dieses Bit. Wenn nicht, sollten sie die geparste Ausgabe bereitstellen, damit Sie sie rekonstruieren können.

Ist es möglich, einfach (zum Beispiel) mapLimit und mapSeries mit map zu verknüpfen? Alles, was Sie sagen müssen, ist, dass es sich um die Versionen mit eingeschränkter Parallelität handelt. Andernfalls wird es viele duplizierte Dokumente und Beispiele geben. (Ich denke aber, die Unterschrift zu behalten ist in Ordnung)

Hey, nur ein kurzes Update, da ich in den letzten Tagen keine Commits zum Pull-Request machen konnte. Ich werde noch weiter daran arbeiten. Ich habe eine kleine Web - Erfahrung, so habe ich auch in die lodash Wartung vor Ort gesucht Problem . Ich werde das Repository mit meinem Fortschritt hochladen, sobald ich darin weit genug gekommen bin. Das Ziel ist es, etwas zu erhalten, das auch async verwenden könnte.

Herumspielen mit der @hargasinski (jetzt auf Master). Ich glaube, ich mag diese Vorlage http://docstrap.github.io/docstrap/. Gedanken @hargasinski & @aearly

Ich habe docstrap schon einmal benutzt, ich mag es wirklich! Es ist eine saubere Vorlage. Irgendeine Idee zum Thema? Meine Vorliebe wäre himmelblau oder lumen . Schiefer ist auch schön, wenn Sie etwas Dunkleres bevorzugen.

Wäre dies auch ein guter Zeitpunkt, um # 975 anzusprechen? Es wäre gut, ein Logo für die Seite zu haben

Docstrap sieht ziemlich gut aus. Ich denke aber, die Suchfunktion könnte besser funktionieren. Das Thema spielt keine allzu große Rolle, da es so aussieht, als könnten wir es leicht ändern. (Und sie scheinen alle gleich zu sein, abgesehen von einigen Farbunterschieden, mehr oder weniger.)

Behalte immer noch https://github.com/lodash/lodash.github.io/issues/8 und https://github.com/lodash/lodash.github.io/issues/15 im Auge -- da beide Projekte sind Mit JSDoc können wir jede Strategie, die sie verfolgen, wiederverwenden.

Das Logo kann warten, wir können "Async" in einer schönen Schriftart verwenden, bis eine gute Logo-Idee auftaucht. :stuck_out_tongue_closed_eyes:

@megawac irgendwelche neueren Arbeiten zur Veröffentlichung unserer JSDocs? Es wäre großartig, die Docs-Site vor der Version 2.0 zu haben.

Ich hatte Pech, sie zum Erstellen zu bringen, und bin auf mehrere Probleme gestoßen, als ich versuchte, jsdocs richtig auf meinem Computer zu kompilieren

@aearly wann planen Sie die Version 2.0? @megawac Derzeit kann ich keine

Wir haben kein Veröffentlichungsdatum - "wenn es fertig ist". Die Dokumentation ist keine zwingende Voraussetzung, sondern nur ein großes Nice-to-have, da einige neue Methoden nur über JSDoc dokumentiert werden.

@hargasinski hauptsächlich habe ich Probleme, es aus mehreren Dateien zu typedef ( queue und cargo ) richtig angezeigt wurden

Oh okay, danke, ich werde das Repo abspalten und ein bisschen damit herumspielen, obwohl ich erst Ende nächster Woche viel schaffen werde. Ich werde ein Update posten, wenn ich etwas Machbares bekomme.