改进clojure.zip文档

Question

clojure.zip模块的docstrings非常简洁，作为参考资料很有帮助，但对于第一次接触此模块的人来说几乎没有任何帮助。扩展的docstrings将使这段代码更易于用户理解，并对其有所帮助。

Answer 1

由brighidm发表的评论

一个改进clojure.zip的docstrings的补丁。

Answer 2

由alexmiller发表的评论

我希望我们可以通过移除只是添加句号、更改换行符、添加空格或其他非重要更改的差异来最小化更改的大小。这将有助于集中注意力在ns docstring、zipper等变化上。此外，这张票不仅讨论了doc字符串，而且还改变了错误消息 - 我希望代码更改在单独的票中。另外，请不要从文件中删除评论部分。

如果您想将测试评论部分转换为实际测试，那将是一个非常不错的单独票（我感觉我在某个时候可能甚至写了一个补丁来做这件事情，但我没有看到相关的票项！）。

将此补丁完全集中在必要的docstring更改上，是确保其及时包含的最佳方式。

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报告）