改进clojure.zip文档

Question

clojure.zip模块的文档字符串非常简洁，便于作为参考资料，但对初次接触该模块的人来说没有帮助。增加文档字符串可以使这块代码更加直观，让可能觉得有用的用户更容易理解。

Answer 1

评论由：brighidm发表的

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

Answer 2

评论由：alexmiller发表的

我宁愿尽可能减小更改的范围，例如删除仅添加句号、更改换行符、添加空白或进行其他非必要更改的差异。这将有助于将重点放在诸如ns文档字符串、zipper等更改上。此外，这个工单讨论了文档字符串，但还更改了异常消息 - 我希望将代码更改放在单独的工单中。另外，请不要删除文件中的注释部分。

如果您想将测试注释部分转换为实际测试，将是一个非常不错的单独工单（我感觉我在某个时刻可能已经编写了一个补丁来做这件事，但我没有看到为它创建的工单）！

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

Answer 3

评论由：brighidm发表的

亚历克斯——为了澄清，我听到的说法是“这个任务应包含两个补丁：一个包含主要文本增加，另一个包含小的校对风格变动”以及“这个任务中的补丁不应包含对异常信息的更改以及注释移动”？

补充问题：是否有Clojure核心代码和文档风格的样式指南？我在clojure.org和JIRA上寻找了这方面的指南，但没有找到，也许我忽视了它。我正在寻找关于注释部分的指南。关于“请勿触碰这些内容”，如果能有一点提示就很好，因为据我所知，它们本身并没有传达这一点。

Answer 4

评论由：alexmiller发表的

实际上，我更喜欢只有一个补丁具有主要文本增加。我认为次要的改变不值得做，并且可能会使重点文本的修改分心。

不幸的是，Clojure核心没有样式指南，实际上它是由多年多人编写的，因此代码中通常没有一致的风格。一般而言，Rich更喜欢保持调试代码或跟踪到他的注释完整（可以使用git blame来帮助那里）。更 generally来说，一个补丁越容易审核，它就越容易保持良好并被轻松审核。

谢谢！

Answer 5

评论由：brighidm发表的

实际上，我更喜欢只有一个补丁具有主要文本增加。
好的，我将产生这个补丁并将它附加到这个任务上。

我认为次要的改变不值得做，并且可能会使重点文本的修改分心。不幸的是，Clojure核心没有样式指南，实际上它是由多年多人编写的，因此代码中通常没有一致的风格。
我认为你刚刚阐述了一个为什么值得进行次要变更的理由：一致性通常会使事物更易于访问。然而，现在显然不是争论这个问题的时机，所以我会只带着这个补丁的ns/docstring版本回来。:)

Answer 6

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