改进 clojure.zip 文档

Question

clojure.zip 模块具有非常简略的文档字符串，这些文档字符串作为参考资料是有帮助的，但对于初次接触该模块的人来说则毫无帮助。扩展的文档字符串将使这段代码对可能发现它有帮助的用户更加可见。

Answer 1

评论由：brighidm

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

Answer 2

评论由：alexmiller

我更希望我们通过移除只添加句点、更改换行符、添加空白或做出其他非必需更改的差异来最小化更改的大小。这将有助我们将注意力集中在更改的要点上，比如 ns 文档字符串、zipper 等。另外，这个工单讨论文档字符串，但还更改了异常消息 - 我希望代码更改在单独的工单中。此外，请勿删除文件中的注释部分。

如果您想要将测试注释部分转换为实际的测试，那将是一个很好的单独工单（我感觉我可能曾经编写过一个补丁来做到这一点，但我不见有工单为此）！

将这个补丁完全集中在关键的文档字符串更改上，是确保其及时包含的最佳方式。

Answer 3

评论由：brighidm

Alex — 为了澄清，我听到的是“这个任务应包含两个补丁：一个包含主要的文本添加，另一个包含小的校对式改动”以及“这个任务中的补丁不应包含异常消息的更改或注释移位”吗？

补充问题：有没有关于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报告）