Docstrings Clojure multilínea

documentation

Question

Me he dado cuenta de que las cadenas de documentos multilínea de Clojure parecen tener formato manual en la mayoría de los casos, incluidos los de clojure.core. Ejemplo de 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))))

Esto parece extraño, ya que significa que diferentes cadenas de documentos tendrán diferentes longitudes de ajuste de línea, etc. que deben mantenerse manualmente.

¿Hay una mejor manera de formatear docstrings multilínea?

Answer 1

¿Hay una mejor manera de formatear docstrings multilínea?

Mi sugerencia es utilizar el formato Markdown en sus documentos. Aquí hay algunas razones de por qué:

• es lo que se usa en github en los wikis de README y proyectos (y muchos usuarios de Clojure usan y están familiarizados con github).

• A juzgar por la number of archivos .md que you find presentes en varios proyectos de Clojure, parece ser un formato de marcado preferido entre los usuarios de Clojure.

• la popular herramienta Marginalia doc presenta docstrings y comentarios con formato de reducción de marca (y, según tengo entendido, Autodoc (la herramienta utilizada para generar los documentos en clojure.org) eventualmente también aplicará markdown en docstrings).

• Se ve bien como texto simple, es fácil de escribir, no requiere ningún soporte especial del editor y el marcado es mínimo y fácil de recordar.

Además, es probable que ya esté familiarizado con él, ya que lo usa para preguntas / respuestas / comentarios (y los sitios como reddit y varios sistemas de comentarios de blogs también usan Markdown).

Answer 2

Estoy de acuerdo con @uvtc en que markdown es una buena opción. Como apéndice, me gustaría señalar que es trivial generar su propia función de visualización de documentos de reducción para usar en el REPL. El siguiente código asume que tiene el paquete markdown-clj en su ruta de clase (por ejemplo, a través de las dependencias de desarrollo) y está utilizando un REPL en 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")
    )
  )

Es posible que desee consultar la fuente de clojure.repl / doc para manejar casos especiales (p. Ej., En este caso se supone que pasará un símbolo adecuado para una var). También podría ser bueno que el nombre del archivo refleje el espacio de nombres / nombre de la función para el "almacenamiento en caché", en lugar de simplemente reutilizar el mismo nombre de archivo para cada solicitud ... pero lo mantengo simple con fines ilustrativos.

El comando de open OSX simplemente le pide al sistema operativo que abra un archivo al detectar su tipo. Así:

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

hará que su navegador predeterminado abra la versión HTMLificada de la cadena de documentos de su función.

Otra advertencia: si sangra su cadena multilínea (lo que comúnmente hacen los editores), entonces su MD puede terminar con una rareza (por ejemplo, las listas de viñetas pueden anidar de una manera que no pretende). Una forma de resolver esto es recortarlo. Por ejemplo:

(defn boo
  "
  # Title
  My thing

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

y luego modifique la función opendoc para aplicar primero un recorte izquierdo:

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

Answer 3

Si está usando Emacs, tome clojure-mode.el de Github de technomancy , que difiere del de ELPA (no sé por qué, ambos afirman ser la versión 1.11.5, ¿tal vez alguien pueda comentar sobre eso?) Pero incluye clojure-fill-docstring que formateará cadenas de documentos con sangría agradable y alineación de líneas, unida por defecto a Cc Mq .

Tomará esto:

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

y convertirlo en esto:

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

después de hacer Cc Mq con su punto dentro de la cadena de documentación.