Многострочные комментарии в Clojure

Я заметил, что многострочные docstrings Clojure, похоже, вручную отформатированы в большинстве случаев, в том числе в clojure.ядро. Пример из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))))

это кажется странным, так как это означает, что разные docstrings будут иметь разные длины обертки линии и т. д. которые нужно вручную поддерживать.

есть ли лучший способ форматирования многострочных документов?

22
clojure docstring documentation

3 ответов

если вы используете Emacs, возьми clojure-mode.el С technomancy это на GitHub, который отличается от того, что в ELPA (я не знаю, почему, оба утверждают, что версия 1.11.5, может быть, кто-то может прокомментировать это?) но включает clojure-fill-docstring который будет форматировать docstrings с хорошим отступом и linewrapping, привязанный по умолчанию к C-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-q С вашей точкой внутри строкой документации.

13

есть ли лучший способ форматирования многострочных документов?

мое предложение использовать уценка форматирование в ваших документах. Вот некоторые причины, почему:

  • это то, что используется в github в README и project wikis (и многие пользователи Clojure используют и знакомы с github).

  • судя по of .MD файлы вы найти присутствует в различных проектах Clojure, это, по-видимому, предпочтительный формат разметки среди пользователей Clojure.

  • популярные заметки на полях doc tool отображает уценки в формате docstrings и комментарии (и я понимаю, что Автодок (инструмент, используемый для создания документов на clojure.org) в конечном итоге будет отображать уценку в docstrings).

  • он выглядит хорошо, как обычный текст, легко вводить, не требует специальной поддержки редактора, а разметка минимальна и легко запоминается.

кроме того, вы, вероятно, уже знакомы с ним, так как Stackoverflow использует его для вопросов / ответов / комментариев (и сайты, такие как reddit и различные системы комментирования блога, также используют Markdown).

12

Я согласен с @uvtc, что markdown-хороший выбор. В качестве дополнения я хотел бы отметить, что тривиально генерировать собственную функцию просмотра документа markdown для использования в REPL. Следующий код предполагает, что у вас есть пакет markdown-clj на вашем пути к классам (например, через зависимости dev) и используете REPL в OSX:

(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 для обработки особых случаев (например, этот предполагает, что вы передадите правильный символ для Вар.) Также было бы неплохо, чтобы имя файла отражало имя пространства имен / функции для "кэширования", а не просто повторно использовать одно и то же имя файла для каждого запроса...но я держу его простым для иллюстрации.

OSX open команда просто просит ОС открыть файл, обнаружив его тип. Таким образом:

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

заставит ваш браузер по умолчанию открыть HTMLified версию docstring вашей функции.

одно другое предостережение: Если вы отступаете многострочная строка (что обычно делают редакторы), тогда ваш MD может закончиться странностью (например, списки пуль могут гнездиться так, как вы не намерены). Один из способов решить эту проблему-сократить это. Например:

(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