27

Clojure の複数行のドキュメント文字列は、ほとんどの場合、手動でフォーマットされているように見えることに気付きました。これには、clojure.core のものも含まれます。https://github.com/clojure/clojure/blob/master/src/clj/clojure/core.cljの例:

(defn flatten
  "Takes any nested combination of sequential things (lists, vectors,
  etc.) and returns their contents as a single, flat sequence.
  (flatten nil) returns an empty sequence."
  {:added "1.2"
   :static true}
  [x]
  (filter (complement sequential?)
          (rest (tree-seq sequential? seq x))))

これは奇妙に思えます。異なる docstring は、手動で維持する必要がある異なる行折り返しの長さなどを持つことを意味するからです。

複数行のdocstringをフォーマットするより良い方法はありますか?

4

3 に答える 3

14

Emacsを使用している場合は、ELPAのものとは異なるtechnomancyのGithubclojure-mode.elから入手してください（理由はわかりませんが、どちらもバージョン1.11.5であると主張していますが、誰かがコメントできるかもしれません）が、どちらがdocstringをフォーマットするかを示しています素敵なインデントと行の折り返しがあり、デフォルトでは。にバインドされています。clojure-fill-docstringC-c M-q

これがかかります：

(defn flatten
  "Takes any nested combination of sequential things (lists, vectors, etc.) and returns their contents as a single, flat sequence. (flatten nil) returns an empty sequence."
  {:added "1.2"
   :static true}
  [x]
  (filter (complement sequential?)
          (rest (tree-seq sequential? seq x))))

そしてそれをこれに変えてください：

(defn flatten
  "Takes any nested combination of sequential things (lists, vectors,
  etc.) and returns their contents as a single, flat sequence.
  (flatten nil) returns an empty sequence."
  {:added "1.2"
   :static true}
  [x]
  (filter (complement sequential?)
          (rest (tree-seq sequential? seq x))))

C-c M-qdocstring内でポイントを処理した後。

于 2012-05-23T16:03:24.103 に答える
14

複数行のdocstringをフォーマットするより良い方法はありますか?

私の提案は、docstrings でMarkdownフォーマットを使用することです。いくつかの理由を次に示します。

  • これは、README やプロジェクト wiki の github で使用されているものです (そして、多くの Clojure ユーザーが使用し、github に精通しています)。

  • さまざまなClojure プロジェクトに存在する.md ファイルの数 から 判断すると、Clojure ユーザーの間で好まれるマークアップ形式のようです。

  • 人気のあるMarginalia doc ツールは、マークダウン形式のドキュメント文字列とコメントをレンダリングします (私の理解では、Autodoc (clojure.org でドキュメントを生成するために使用されるツール) は最終的にドキュメント文字列でもマークダウンをレンダリングします)。

  • プレーン テキストのように見え、入力しやすく、特別なエディター サポートは必要なく、マークアップは最小限で覚えやすいものです。

また、Stackoverflow では質問/回答/コメントに使用されているため (また、reddit などのサイトやさまざまなブログ コメント システムでも Markdown が使用されているため)、おそらく既に使い慣れているでしょう。

于 2012-05-23T05:04:14.850 に答える
2

マークダウンが良い選択であるという@uvtcに同意します。補足として、REPL で使用する独自のマークダウン ドキュメント表示関数を生成するのは簡単なことです。次のコードは、クラスパスに markdown-clj パッケージがあり (たとえば、dev の依存関係を介して)、OSX で REPL を使用していることを前提としています。

(ns docs
  (:require [clojure.java.shell :as s]
            [markdown.core :as md]))

(defmacro opendoc [name]
   `(do
        (md/md-to-html (java.io.StringReader. (:doc (meta (var ~name)))) "/tmp/doc.html")
        (s/sh "open" "/tmp/doc.html")
    )
  )

特殊なケースを処理するために clojure.repl/doc のソースを確認することをお勧めします (たとえば、これは var に適切なシンボルを渡すことを前提としています)。リクエストごとに同じファイル名を再利用するのではなく、「キャッシュ」の名前空間/関数名をファイル名に反映させることも良いかもしれませんが、説明のために単純にしています。

OSXopenコマンドは、ファイルの種類を検出してファイルを開くよう OS に要求するだけです。したがって：

REPL=> (docs/opendoc my.ns/f)

デフォルトのブラウザは、関数のドキュメント文字列の HTML 化されたバージョンを開きます。

もう 1 つの注意点: 複数行の文字列をインデントすると (編集者がよく行うことです)、MD が奇妙なものになる可能性があります (たとえば、箇条書きリストが意図しない方法で入れ子になる可能性があります)。これを解決する 1 つの方法は、それを元に戻すことです。例えば：

(defn boo
  "
  # Title
  My thing

  * Item one
  * Item two
  "
  [args] ...)

次に opendoc 関数を変更して、最初に左トリムを適用します。

(defn ltrim [str] (clojure.string/replace str #"(?m)^ {0,3}" ""))

(defmacro opendoc [name]
  `(do
    (md/md-to-html (java.io.StringReader. (ltrim (:doc (meta (var ~name))))) "/tmp/doc.html")
    (s/sh "open" "/tmp/doc.html")
   )
  )
于 2015-06-04T19:24:33.793 に答える