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