改进clojure.zip文档

Question

clojure.zip模块的文档字符串非常简洁，作为参考资料很有帮助，但对于初学者来说完全没有帮助。扩展文档字符串将使这段代码更能为可能认为它有价值的用户所看到。

Answer 1

评论由：brighidm发表

一个改进clojure.zip文档字符串的补丁。

Answer 2

评论由：alexmiller发表

我宁愿通过删除只添加句号、改变换行符、添加空白或其他非基本更改的差异来尽量减少更改的大小。这有助于集中精力解决像ns文档字符串、zipper等变化等问题。此外，这张票讨论了文档字符串，但也对异常消息进行了更改 - 我希望代码更改单独 într-un birou。Also, please don't remove the comment sections in the files.

如果您想将测试评论部分转换为实际测试，这将是一项很好的独立票据（我觉得我可能在某个时候甚至编写了一个补丁来完成此操作，但我看不到关于它的票据！）。

确保其及时纳入的最佳方式是保持此补丁完全专注于必要的文档字符串更改。

Answer 3

评论由：brighidm发表

亚历克斯 —— 为了澄清，我听到“这个工单应该包含两个补丁：一个包含主要文本添加，另一个包含一些小型的校对式更改”以及“这个工单的补丁不应包括异常消息的更改和注释移动”吗？

补充问题：有没有关于 Clojure 核心中的代码和文档风格的风格指南？我在 clojure.org 和 JIRA 上搜索了这样的指南，但没有找到。也许我疏忽了。我正在寻找关于注释部分的指南。如果能有一个提示“请勿更改这些”，那就更好了，因为据我所知，它们本身并没有传达这一点。

Answer 4

评论由：alexmiller发表

实际上，我更希望只有一个补丁包含主要的文本添加。我不认为这些小的更改值得做，并且会分散对更重要的文本的注意力。

不幸的是，Clojure 核心没有风格指南，实际上它是由很多人在多年的时间里编写的，所以整个代码通常没有一致的样式。Rich 通常更喜欢保持调试代码或追踪到他的注释完整无误（可以使用git blame在这里帮忙）。更普遍的是，越易于审查的补丁，越容易保持良好状态并轻松地进行审查。

谢谢！

Answer 5

评论由：brighidm发表

实际上，我更希望只有一个补丁包含主要的文本添加。
好的，我会生成这个补丁并将其附加到这个工单上。

我不认为这些小的更改值得做，并且会分散对更重要的文本的注意力。不幸的是，Clojure 核心没有风格指南，实际上它是由很多人在多年的时间里编写的，所以整个代码通常没有一致的样式。
我认为你刚刚为为什么要做小的更改提出了论据：一致性通常使事物更加易于访问。然而，现在显然不是争论这个问题的时机，所以我会只带着这个补丁的ns/docstring版本返回。 :)

Answer 6

参考资料： https://clojure.atlassian.net/browse/CLJ-2049 (由 brighidm 报告)