web-dev-qa-db-ja.com

複数行のClojuredocstring

Clojure.coreにあるものを含め、ほとんどの場合、Clojureの複数行のdocstringは手動でフォーマットされているように見えることに気づきました。 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をフォーマットするためのより良い方法はありますか？

clojuredocumentationdocstring
26
mikera

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

これがかかります：

(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))))

docstring内のポイントでC-c M-qを実行した後。

13
michiakig

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

私の提案は、docstringで Markdown フォーマットを使用することです。理由は次のとおりです。

  • これは、READMEおよびプロジェクトウィキのgithubで使用されているものです（そして、多くのClojureユーザーがgithubを使用し、慣れています）。

  • numberof。md filesyofind さまざまなClojureプロジェクトに存在する、Clojureユーザーの間で推奨されるマークアップ形式のようです。

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

  • プレーンテキストとして見栄えがよく、入力が簡単で、特別なエディターサポートを必要とせず、マークアップは最小限で覚えやすいです。

また、質問/回答/コメントには Stackoverflowが使用 （redditやさまざまなブログコメントシステムなどのサイトもMarkdownを使用している）ので、おそらくすでにご存知でしょう。

12
uvtc

私は@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に適切なシンボルを渡すことを前提としています）。すべてのリクエストに同じファイル名を再利用するのではなく、ファイル名に「キャッシュ」の名前空間/関数名を反映させるのも良いかもしれません...しかし、説明のために単純にしています。

OSX openコマンドは、ファイルのタイプを検出することにより、OSにファイルを開くように要求するだけです。したがって：

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

デフォルトのブラウザで、関数のdocstringの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")
   )
  )
2
Tony K.