問題タブ [marginalia]

Clojureでコメントを開始するとき;と開始するときの違いは何ですか？;;私のテキストエディタはそれらの色が異なっているので、概念的には多少の違いがあると思います。

また、 Marginaliaはそれらを異なる方法で処理していることもわかります。

昨年かそこらで、Clojureディスカッションリストやその他の場所で、Clojureコードを文書化するためのツールに関するさまざまな発表を見てきました。これらは、Marginaliaのような完全な文芸的プログラミングシステムや、本「Clojure in SmallPieces」（またはemacs org-mode）の作成に使用されるツールから、Autodocのような従来のJavadocスタイルのソリューションやJavadoc自体にまで及びます。伝えられるところによると、Clojureで使用できます。グーグル検索は他の様々なものを見つけます、おそらくもっと注目に値するいくつか、そして確かにいくつかはドキュメントを生成するための単なる個人的なユーティリティです。私の質問は、最高のドキュメンテーションツールは何ですか、そしてそれらを使用した経験に基づいたそれらの比較の長所と短所は何ですか？私はこれまでドキュメントツールを使用したことがなく、1つ以上のツールを試すことに興味があります。

Python doctestsは、単純なテストをソースコードに関連付けます（Pythonでは、関数のドキュメントにあります）。 詳細と例はこちら。

Clojureに似たものはありますか？

私はを使用した単体テストを知ってclojure.testいますが、ソースとより緊密に統合されたものを探しています（通常、単体テストは異なるファイルにあります。ここでは、テストを「内部」に配置したいと思いますdefn）。

周りを検索すると、これが見つかりましたが、非常にわかりにくいようです（テストは、Pythonのように実際のテキストで行われます。確かに、拡張するマクロdefnが望ましいでしょうか？）。

または、一般的な問題を解決する他の方法があります。それは、別のユニットよりもドキュメント（傍注を使用）に含めるほうがよいテスト（通常、関数の基本的なプロパティを示す単純なもの）があることです。テストファイル。

更新 例を次に示します。ピクセルの長方形から画像の中心までの（マンハッタン）距離（ピクセル単位）を計算する関数があります。それは単純に聞こえますが、辺に奇数または偶数のピクセルがある画像の「​​中心」の意味の違いや、ブロックのどの部分から測定するかなどによって複雑になります。そのため、コードをまっすぐにするためだけにいくつかのテストを作成する必要がありました。そして今、私はドキュメントを見て、実際には、関数が何をするかを言葉よりもよく説明しているので、ドキュメントにそれらのテストが含まれているとよいでしょう...

質問

単一のファイル docs/uberdoc.html を生成します

*.clj ファイルごとに 1 つずつ、docs/* に多くのファイルを生成することをお勧めします

動機：

マーガリア大好きです。私は最近それを使い始めましたが、ドキュメントを書きたいと思っています。それは不可能に思えます。

ただし、ドキュメントを作成し、uberdoc.html を更新してリロードすると、以前に見ていたドキュメントの一部が失われるという問題があります。したがって、各 *.clj ファイルがドキュメント用の *.html ファイルにあるシステムを好みます。これはmarginalia 0.7.0で可能ですか?

ありがとう！

Maven を使用する Java (マルチモジュール) プロジェクトでMarginaliaを実行することは可能ですか?

または、これを行うことができる Marginalia やDoccoに似た他の代替手段はありますか?

私にとって重要なことは、それをいくつかのパブリック Maven リポジトリから依存関係として追加し、たとえば Docco の Node.js などの追加のものをインストールせずにすぐに使用できることです。これは Java プロジェクトであるため妥当です。