Clojure文檔工具的最新技術狀態

在過去一年左右，我在Clojure討論列表和其他關於記錄Clojure代碼的工具的其他地方看到了各種公告。這些範圍包括像Marginalia這樣全面的文字編程系統，以及用於創建「Clojure in Small Pieces」（甚至emacs org模式）一書的工具，以及更傳統的Javadoc風格解決方案，如Autodoc和Javadoc本身。據說可以和Clojure一起使用。谷歌搜索變成了其他各種各樣的，也許是值得更多關注的一些，並且肯定有些只是用於生成文檔的個人實用程序。我的問題是什麼是最好的文檔工具，根據你使用它們的經驗，他們的比較優勢和劣勢是什麼？迄今爲止我還沒有使用任何文檔工具，並且有興趣嘗試一個或多個。Clojure文檔工具的最新技術狀態

來源

2011-03-17 rplevy

作爲一個注意點，Marginalia不是一個全面的文字編程工具。它在許多方面有助於識字，但它並沒有以任何方式理解如何處理亂序代碼評論，例如「Clojure in Small Pieces」中使用的系統。 org-babel-clojure或者Knuth的CWEB。這只是一個方便閱讀代碼的好工具。 – fogus 2011-03-17 11:54:36

聽起來Autodoc和Marginalia都是doc-string驅動的，並且都與Leiningen有良好的整合，但主要區別在於Marginalia產生更豐富的輸出，而Autodoc更加基本。謝謝！ – rplevy 2011-03-17 13:42:44

如果你想採取類似識字的編程方法，我真的很喜歡Marginalia。 Marginalia遍歷你的源代碼，並生成一個HTML格式的版本，其代碼旁邊的註釋以非常明確的文本形式出現。評論可以用markdown格式化，製作一個非常可讀的最終文檔。在回顧我之前編寫的源代碼時，我發現Marginalia確實有幫助。 Here's an example made from the Marginalia source itself。

請注意，這不同於原來的文字編程工作流程，您將在其中編寫文件並從中生成源代碼。通過Marginalia，你可以編寫一個常規的源代碼文件，並且這些文檔都被取消了。輸出與文字編程所期望的類似，但這樣您仍然可以在編輯器中預期語法高亮，而無需任何特殊的文字編程支持。

它與Leiningen互操作，我相信蛋糕，但我沒有嘗試過自己。

來源

2011-03-17 04:09:44

我也喜歡邊緣。一個問題是它沒有提供很好的索引參考。再一次，這不是真正的目的。 – apg 2011-03-17 10:08:22

@Andrew計劃中有一些索引。 :-) – fogus 2011-03-17 11:53:54

@霧 - 哦整潔！這將非常有用。 – apg 2011-03-17 12:55:42

Autodoc是一個容易開始的地方，也是Clojure core和Clojure contrib生產的地方。

易於使用Maven。我不確定插件是否存在於Leiningen或Cake。

來源

2011-03-17 03:57:44

查看爲[Autodoc]（http://tomfaulhaber.github.com/autodoc/）提供的鏈接，有關autodoc的lein插件的一節：[使用Leiningen構建Autodoc]（http：//tomfaulhaber.github。 com/autodoc /＃building_with_leiningen） – 2011-03-17 05:36:55

我的項目沒有使用'clojure.main'主類，autodoc因此退出：'錯誤：無法找到或加載主類clojure.main'。我一直無法找到在Maven POM中指定我自己的主類的方法。 – 2013-12-27 20:53:21

如果你想完全識字，你應該看看org-babel-clojure。 org-bable是emacs org-mode的一個有識字的編程擴展。

如果你想nrepl以下使用應該被添加到您的.emacs：

(defun org-babel-execute:clojure (body params) 
    "Execute a block of Clojure code with Babel." 
    (let ((result-plist (nrepl-send-string-sync (org-babel-expand-body:clojure body params) nrepl-buffer-ns)) 
     (result-type (cdr (assoc :result-type params)))) 
    (org-babel-script-escape 
    (cond ((eq result-type 'value) (plist-get result-plist :value)) 
      ((eq result-type 'output) (plist-get result-plist :value)) 
      (t      (message "Unknown :results type!"))))))

來源

2011-03-17 06:19:49 mac

既然swank-clojure已經被棄用，並且有了org-babel-clojure的更新或者替代品嗎？我正在研究noweb for LP，但在寫作/開發期間有一個repl會很好。 – 2013-08-19 12:35:01

org-babel-clojure作品非常棒。我上面編輯了我的回覆，以反映我目前的使用情況。 – mac 2013-08-19 16:50:59

Codox是Clojure的一個較新的文檔生成。

來源

2012-08-10 20:44:26 cderoove

我會保證這是一個很好的選擇。 Marginalia爲代碼旁邊的文檔呈現令人印象深刻，但有點太多'個性'，我發現分心。據說Codox也支持解析內聯html和可能的降價，但具有諷刺意味的是，文檔對於我來說太稀疏了（甚至不是codox輸出！） – 2012-12-10 10:56:46

Clojure文檔工具的最新技術狀態

回答

相關問題