问题标签 [marginalia]

在 Clojure 中开始评论;和开始评论有什么区别？;;我看到我的文本编辑器为它们着色不同，所以我假设在理论上存在一些差异。

我还看到Marginalia以不同的方式对待它们：

在过去一年左右的时间里，我在 Clojure 讨论列表和其他地方看到了关于记录 Clojure 代码的工具的各种公告。这些范围从像 Marginalia 这样的全面读写编程系统，以及用于创建“Clojure in Small Pieces”（甚至是 emacs org-mode）一书的工具，到更传统的 Javadoc 风格的解决方案，如 Autodoc，以及 Javadoc 本身据报道可以与 Clojure 一起使用。谷歌搜索会出现其他各种情况，也许有一些值得更多关注，当然还有一些只是用于生成文档的个人实用程序。我的问题是什么是最好的文档工具，根据您使用它们的经验，它们的比较优势和劣势是什么？到目前为止，我还没有使用过任何文档工具，并且有兴趣尝试一种或多种工具。

Python doctest 将简单测试与源代码相关联（在 Python 中，它们位于函数文档中）。 更多信息和示例在这里。

Clojure有类似的东西吗？

我知道clojure.test使用defn.

环顾四周，我发现了这个，但它似乎很不简洁（测试是在实际文本中，比如 Python - 当然扩展的宏defn会更可取？）。

或者也许还有其他方法可以解决一般问题，那就是我有一些测试（通常是简单的东西，展示了函数的基本属性），这些测试最好包含在文档中（我使用的是marginia）而不是单独的单元测试文件。

更新 这是一个例子：我有一个函数可以计算从像素矩形到图像中心的（曼哈顿）距离（以像素为单位）。这听起来很简单，但是由于侧面具有奇数或偶数像素的图像的“中心”含义的差异，或者您从块的哪个部分测量，这使得事情变得复杂。所以我不得不写一些测试来把代码弄明白。现在我查看文档，如果文档包含这些测试，那将是最好的，因为它们比文字更好地解释了函数的作用......

问题

生成单个文件 docs/uberdoc.html

我希望它在 docs/* 中生成许多文件，每个 *.clj 文件一个

动机：

我真的很喜欢边缘化。我最近开始使用它，这让我想写文档，这听起来很不可能。

但是，我遇到的问题是，每当我编写文档、刷新和重新加载 uberdoc.html 时，我都会丢失之前查看的文档部分。因此，我更喜欢一个系统，其中每个 *.clj 文件都位于 *.html 文件中以供文档使用。这可能与边缘 0.7.0 吗？

谢谢！

是否可以在使用 Maven 的 Java（多模块）项目上运行Marginalia ？

或者有没有其他类似于 Marginalia 或Docco的替代方案可以做到这一点？

对我来说重要的是能够将它作为一些公共 Maven 存储库的依赖项添加并立即使用它，而无需为 Docco 安装任何其他东西，例如 Node.js - 这是合理的，因为它是一个 Java 项目。