Sinon: 「API仕様」スタイルのドキュメント

ちなみに、私は現在のドキュメントを強調していません。これは貴重です。 私は単に追加の包括的なことを提案しているだけです。

Javaには、手作業なしでJavaDocを生成するための自動ツールがあります。 JSライブラリでこのようなことを実現するには、大量の手作業が必要です。 私はそれのようなものを見たいのですが、それがかなり早く時代遅れになるのではないかと心配しています。

コードの注釈とツールについて少し気を紛らわせることができました。 たぶん実行可能なオプションがあります。

他のスレッドで取り上げられていることは知っていますが、非常に簡単に言えば、ライブラリ全体をjsDocで文書化する必要があると思います。 これはJavaScriptの事実上の標準のようなものです（または、少なくとも、JavaScriptの最も強力な議論です）。 最小限のドキュメントカバレッジから始めてAPIを公開し、壁に大きな「進行中」のサインを配置して、そこから構築することができます。

@mantoniJSDocを自動生成するためのツールはたくさんあります。 これのv1が問題になるとは思わない。 どこにでも@typedefを作成する必要はありません。 持っているだけ

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

かなり役に立ちます。

こんにちは@ 76784 、それは素晴らしい入力です！ 😊

ただし、考慮すべき点がいくつかあります。

私はJSDocがとても好きです。 これはChai.jsでも使用されており、名前空間に分割でき、コードが互いに隣接しているため、コードとドキュメントの同期を常に維持できるため、これまでのところかなりうまく機能しています。

ただし、Javaのドキュメントが「ゴールドスタンダード」であることに同意しません。 Javaドキュメントは非常に乾燥していると思います。 参照には適していますが、その大部分を学習したり、調べたりするのには適していません。 Sinonのドキュメントがわかりやすいプレーンテキストの古典的なスタイルで書かれているという事実が好きです。 採用を促進するのに役立つIMO。 また、APIリファレンスとしてはかなり良いIMOです。

もちろん、JSDocsがあればいいと思いますが、非常に多大な労力が必要になることに注意することが重要です。

@ 76784がブランチを開始し、いくつかの概念を

@lucasfcosta

Javaドキュメントは非常に乾燥していると思います。 参照には適していますが、その大部分を学習したり、調べたりするのには適していません。

私は同意しません。 ドキュメントとチュートリアルの2つは別々のものでなければならないと言っているだけです。 javadocsの乾燥はプラスです。 そこに行って、この乾いた言葉の慣習を通して、「もの」が何をするのかを知ることができます。 そしてもちろん、最も重要なことは、それは本質的に包括的です。 ドキュメントに文型の構造は必要ありません。チュートリアルに必要です。

私はJSDocの専門家ではありませんが、JSDocのコメントに、エントリのチュートリアルにリンクする簡単な方法があるのではないかと思います。

これに関するいくつかの概念実証、 @ fatso83を提供することに関しては、現時点では少し時間が足りません（私は知っています、誰がそうではありませんか？）が、今年の後半にはより良い立場にあるかもしれません。 シノンを徹底的に学ぶのに最適な方法です。

この問題は、最近のアクティビティがないため、自動的に古いものとしてマークされています。 それ以上のアクティビティが発生しない場合は閉じられます。 貢献していただきありがとうございます。

この問題を固定したので、Staleボットによって閉じられません

この道を進むことにした場合は、 https：//github.com/gajus/eslint-plugin-jsdocのようなものを使用する必要があると思いeslint-config-sinon入るはずです。

これに飛び込んだり出たりして申し訳ありません-それは本当にいくつかの仕事の優先順位によって駆動されます。 そして、これが正しいスレッドであるかどうかはわかりませんが、既存のドキュメントについてさらにフィードバックを提供するためです...

私がスパイのようなものを見ているとき： https ：

私はたまたま、最初のチャンクに示されているものとは異なる構文を持つMochaを使用しています。

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

    PubSub.publishSync("message");

    assertTrue(callback.called);
}

私が（ジャスミン？）の代わりにモカを使用しているという事実は大したことではありするかを理解するのは難しいの例では、テストされている機能を示していないということであること。

あなたが例を提供するつもりなら、それは私がすべきだと思うことです。 テストされているものの最小動作機能を表示します。 ここでも同じ問題がありますが、 myLib ： https ：

わかりました- myLibは私が書くものです。 しかし、あなたは多くの初心者に、彼らが何に対してテストしているのかを見ずに、このことを学ばなければならないことを求めています。

実際、そのテストはMochaの構文を使用しており、（2つのうち）より標準的なBDDスタイルを使用しているだけです:-) Sinonの元の作成者も（共同）作成したBusterJSなどの他のライブラリでも共有されています。 とにかく、誰かがすべての例を使用中の最も一般的なスタイルに更新することはおそらく理にかなっています:-)

他の点に関しては、これらは非常に有効であり、私たちが議論したことです。 実際、実行可能で、テストされ、埋め込まれた例を用意して、有効性を保証することについて話し合いました。 これは暗黙のうちにそれらの問題を修正します。 しかし、ええ、誰かが座ってそれをする必要があります...

実際、そのテストはMochaの構文を使用しています

何？？ 今度は、Mochaのドキュメントについて怒鳴る必要があります。 :-)

私はhttps://github.com/sinonjs/samsam/pull/82でこの取り組みを開始しようとしました