改进clojure.zip文档

Question

clojure.zip模块的文档字符串极其简短，虽然有助于作为参考资料，但对于初次接触该模块的人来说却无助于理解。扩展文档字符串将使用户更清晰地看到这段代码，使其更有助于用户。

Answer 1

评论者：brighidm

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

Answer 2

评论者：alezmiller

我希望能尽量减少更改的大小，比如移除仅添加句号、更改换行符、添加空白或进行其他非必要更改的差异。这将有助于关注像ns文档字符串、zipper等的更改。此外，这个工单讨论了文档字符串，但也更改了异常消息 - 我希望代码更改在单独的工单中。另外，请不要删除文件中的注释部分。

如果您想将测试评论部分转换为实际的测试，那将是一个伟大的单独工单（我觉得我可能曾经写过一个补丁来做这件事，但我没有看到为它的工单！）。

将此补丁完全集中在必要的文档字符串更改上，是将补丁及时包括的最佳方式。

Answer 3

评论者：brighidm

亚历克斯 — 为了澄清，我听到的是“这个工单应包括两个补丁：一个带有主要文字增加的补丁，另一个带有微小的校对式改变”以及“这个工单的补丁不应包括异常消息的更改以及注释移动”吗？

附加问题：有没有关于Clojure核心代码和文档风格的风格指南？我在clojure.org和JIRA上寻找了这样的指南：我没有找到，但也许我忽略了它。我正在寻找有关注释部分的指南。有一个关于“请勿触碰这些”的提示会很好，因为据我所知，它们本身并没有传达这一点。

Answer 4

评论者：alezmiller

实际上，我只想有一个包含主要文字增加的补丁。我认为这些小的更改不值得做，会分散人们对更重要文字的注意力。

不幸的是，Clojure核心没有风格指南，实际上它是由许多人多年来编写的，因此代码中没有一致的风格。一般来说，Rich更喜欢保留调试代码或追踪到他的注释（使用git blame可以帮助那里）。更普遍的是，补丁越简单，就越容易保持良好并易于审查。

谢谢！

Answer 5

评论者：brighidm

实际上，我只想有一个包含主要文字增加的补丁。
好吧，我会制作那个补丁并将其附加到此工单上。

我认为这些小的更改不值得做，会分散人们对更重要文字的注意力。不幸的是，Clojure核心没有风格指南，实际上它是由许多人多年来编写的，因此代码中没有一致的风格。
我认为你刚刚提出了为什么应该做小的改变的论据：一致性通常使事物更易于访问。然而，显然现在并不是争论那个问题的时机，所以我只会提供这个补丁的ns/docstring版本。：）

Answer 6

参考：[https://clojure.atlassian.net/browse/CLJ-2049](https://clojure.atlassian.net/browse/CLJ-2049)（由brighidm报告）