Clojure文档工具的艺术状态 [英] State of the Art for Clojure Documentation Tools

问题描述

过去一年左右，我在Clojure讨论列表和其他地方看到了关于记录Clojure代码的工具的各种公告。这些范围从全面的文字编程系统，如Marginalia，以及用于创建Clojure in Small Pieces（甚至是emacs org-mode）的工具，以及更常规的Javadoc风格的解决方案，如Autodoc和Javadoc本身据报道可以与Clojure一起使用。 google搜索引起了各种其他人，也许一些值得更多的关注，而且肯定一些只是个人工具生成文档。我的问题是什么是最好的文档工具，他们的比较优势和弱点是什么，基于你的使用经验？我迄今没有使用任何文档工具，并且有兴趣尝试一个或多个。

Over the last year or so I've seen various announcements on the Clojure discussion list and other places about tools for documenting Clojure code. These range from full-on literate programming systems like Marginalia, and the tool being used to create the book "Clojure in Small Pieces" (or even emacs org-mode), to more conventional Javadoc-style solutions like Autodoc, and Javadoc itself which reportedly can be used with Clojure. A google search turns up various others, perhaps a few that deserve more attention, and for sure some that are just personal utilities for generating docs. My question is what are the best documentation tools, and what are their comparative strengths and weaknesses based on your experiences using them? I have not used any documentation tools to date, and am interested in experimenting with one or more.

推荐答案

href =https://github.com/fogus/marginalia> Marginalia ，如果你想采取类似于文字编程方法。 Marginalia遍历您的源代码，并生成一个html格式的版本，并在代码旁边设置注释，文本非常清晰。注释可以是markdown格式，使得一个非常可读的最终文档。在回顾我之前写过的源代码时，我发现Marginalia真的有帮助。 以下是来自Marginalia来源本身的示例。

I really like Marginalia if you want to take something like a literate programming approach. Marginalia traverses your source code, and produces an html formatted version with comments set beside code in a very clear text. Comments can be markdown formatted, making for a very readable final document. When reviewing source code that I've written some time ago, I find Marginalia really helps. Here's an example made from the Marginalia source itself.

请注意，这不同于原始的识字编程工作流，在那里你将编写一个文件，并从中生成源代码。使用Marginalia，你可以编写一个常规的源代码文件，这是从中提取的文档。输出类似于文字编程中所期望的输出，但是这种方式仍然可以在编辑器中预期语法高亮，而没有任何特殊的文字编程支持。

Note that this differs from the original literate programming workflow, where you would write a file and source code is generated from that. With Marginalia, you write a regular source code file, and it's the documentation that's pulled out of that. The output is similar to what one might expect from literate programming, but this way you can still expect syntax highlighting in an editor, without any special literate programming support.

它互操作与莱宁根，我相信蛋糕，虽然我没有自己尝试。

It interoperates with Leiningen, and I believe cake, though I haven't tried that myself.

这篇关于Clojure文档工具的艺术状态的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！