Sinon: “ API规范”样式文档

顺便说一句，我并没有对当前的文档有所帮助，这很有价值。 我只是在建议其他全面的内容。

Java具有无需人工即可生成JavaDocs的自动工具。 要在JS库中实现类似的功能，需要大量的手工工作。 我很想看到类似的东西，但我担心它会很快过时。

我们可以稍微讨论一下代码注释和工具。 也许有可行的选择。

我知道它是在其他线程上提出来的，但是我认为，很简单，应该使用jsDoc记录整个库。 这是JavaScript的事实上的标准（或者至少是最强大的参数之一）。 我们可以只从最小的文档覆盖范围开始发布api，然后在墙上贴上一个大的“进行中”标志，然后从那里开始构建。

@mantoni有很多自动生成JSDocs的工具。 我认为这不是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文档非常干燥。 这对参考很有用，但对学习或占用较大部分不利。

我不同意。 我只是说两件事-文档和教程-应该是分开的。 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);
}

我使用Mocha而不是茉莉花（Jasmine？）并不是一个大问题。 它们显然是相似的。 但是，使该示例难以理解的是，您没有显示正在测试的功能。

如果您要提供示例，我认为应该这样做。 显示正在测试的任何事物的最低工作功能。 同样的问题， myLib ： https :

我明白了- myLib是我会写的东西。 但是，您要让很多新手学习这些东西，而不必看他们正在测试的内容。

实际上，该测试IS使用Mocha的语法，只是使用了更为标准的BDD风格（两者）：-)它也与其他一些库共享，例如Sinon的原始创建者（共同创建）的Buster JS。 无论如何，将所有示例更新为使用中最常见的样式可能很有意义：-)

至于其他观点，这些都是很有效的，我们已经讨论过了。 实际上，我们讨论了具有可运行，经过测试的嵌入式示例，以确保有效性。 这将暗中解决这些问题。 但是，是的，有人需要坐下来做...

实际上，该测试是使用Mocha的语法进行的

什么？？ 现在，我将不得不对Mocha文档大加赞赏。 :-)

我已经尝试在https://github.com/sinonjs/samsam/pull/82中开始这项工作