改进 clojure.zip 文档

Question

clojure.zip 模块的 docstrings 非常简略，虽然有参考价值，但对初学者来说毫无帮助。扩展的 docstrings 将会让这段代码对可能需要帮助的用户更加透明。

Answer 1

评论者：brighidm

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

Answer 2

评论者：alexmiller

我希望我们可以通过删除只是添加句号，更改换行符，添加空白或进行其他非基本更改的差异来最小化更改的大小。这将有助于集中关注像 ns docstring、zipper 等方面的变更。此外，这个工单讨论了 docstring，但还改变了异常消息 - 我更希望代码更改在单独的工单中。另外，请在文件中不要删除注释部分。

如果您想将测试注释部分转换为实际测试，将非常理想，因为这将是一个单独的工单（我觉得我可能曾经写过一个用于此的补丁，但我看不到相关的工单）!

将此补丁完全集中在基本 docstring 变更是确保其及时包含的最佳方式。

Answer 3

评论者：brighidm

亚历克斯 —— 为了澄清，我听到“这个技术票应该包含两个补丁：一个是带有主要文本添加的补丁，另一个是带有小量校对式更改的补丁”，以及“这个技术票的补丁不应包括异常信息更改和注释移动”?

补充问题：有没有一个风格指南用于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报告）