[elpa] externals/dash 525ede2 265/316: Improve docstring Markdown formatting

[ELPA Syncer]

branch: externals/dash
commit 525ede2d24c8e6a6c45b2c90280998b336ea6ccc
Author: Basil L. Contovounesios <contovob@tcd.ie>
Commit: Basil L. Contovounesios <contovob@tcd.ie>

    Improve docstring Markdown formatting
    
    * dev/examples-to-docs.el (dash--describe): Improve docstring.
    (quote-and-downcase, unquote-and-link): Remove functions.
    (dash--quote-argnames, dash--quote-metavars, dash--quote-hyperlinks)
    (dash--indent-blocks): New formatting functions.
    (format-docstring): Rename...
    (dash--format-docstring): ...to this.  All callers changed.  Use new
    formatting functions on buffer contents for more sophisticated
    Markdown formatting.
    
    * README.md: Regenerate.
---
 README.md               | 16 ++++++------
 dev/examples-to-docs.el | 67 ++++++++++++++++++++++++++++++++++++-------------
 2 files changed, 57 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 1ac9000..4cb05dc 100644
--- a/README.md
+++ b/README.md
@@ -597,7 +597,7 @@ Return copy of `list`, starting from index `from` to index 
`to`.
 `from` or `to` may be negative.  These values are then interpreted
 modulo the length of the list.
 
-If `step` is a number, only each STEPth item in the resulting
+If `step` is a number, only each `step`th item in the resulting
 section is returned.  Defaults to 1.
 
 ```el
@@ -851,7 +851,7 @@ See also: [`-splice`](#-splice-pred-fun-list), 
[`-splice-list`](#-splice-list-pr
 
 #### -replace-at `(n x list)`
 
-Return a list with element at Nth position in `list` replaced with `x`.
+Return a list with element at `n`th position in `list` replaced with `x`.
 
 See also: [`-replace`](#-replace-old-new-list)
 
@@ -863,7 +863,7 @@ See also: [`-replace`](#-replace-old-new-list)
 
 #### -update-at `(n func list)`
 
-Return a list with element at Nth position in `list` replaced with `(func (nth 
n list))`.
+Return a list with element at `n`th position in `list` replaced with `(func 
(nth n list))`.
 
 See also: [`-map-when`](#-map-when-pred-rep-list)
 
@@ -875,7 +875,7 @@ See also: [`-map-when`](#-map-when-pred-rep-list)
 
 #### -remove-at `(n list)`
 
-Return a list with element at Nth position in `list` removed.
+Return a list with element at `n`th position in `list` removed.
 
 See also: [`-remove-at-indices`](#-remove-at-indices-indices-list), 
[`-remove`](#-remove-pred-list)
 
@@ -1337,7 +1337,7 @@ Alias: `-is-suffix-p`
 
 Return non-nil if `infix` is infix of `list`.
 
-This operation runs in `o`(n^2) time
+This operation runs in O(n^2) time
 
 Alias: `-is-infix-p`
 
@@ -1367,7 +1367,7 @@ Functions partitioning the input list into a list of 
lists.
 
 #### -split-at `(n list)`
 
-Split `list` into two sublists after the Nth element.
+Split `list` into two sublists after the `n`th element.
 The result is a list of two elements (`take` `drop`) where `take` is a
 new list of the first `n` elements of `list`, and `drop` is the
 remaining elements of `list` (not a copy).  `take` and `drop` are like
@@ -1727,7 +1727,7 @@ Other list functions not fit to be classified elsewhere.
 #### -rotate `(n list)`
 
 Rotate `list` `n` places to the right.  With `n` negative, rotate to the left.
-The time complexity is `o`(n).
+The time complexity is O(n).
 
 ```el
 (-rotate 3 '(1 2 3 4 5 6 7)) ;; => '(5 6 7 1 2 3 4)
@@ -2452,7 +2452,7 @@ Conses and lists:
 
     (a1 a2 a3 ...) - bind 0th car of list to `a1`, 1st to `a2`, 2nd to `a3`...
 
-    (a1 a2 a3 ... aN . rest) - as above, but bind the Nth cdr to `rest`.
+    (a1 a2 a3 ... aN . rest) - as above, but bind the `n`th cdr to `rest`.
 
 Vectors:
 
diff --git a/dev/examples-to-docs.el b/dev/examples-to-docs.el
index 0aa405d..c8e93fa 100644
--- a/dev/examples-to-docs.el
+++ b/dev/examples-to-docs.el
@@ -46,7 +46,8 @@
        it t t))))
 
 (defun dash--describe (fn)
-  "Return the (ARGLIST DOCSTRING) of FN symbol."
+  "Return the (ARGLIST DOCSTRING) of FN symbol.
+Based on `describe-function-1'."
   (with-temp-buffer
     (pcase-let* ((`(,real-fn ,def ,_alias ,real-def)
                   (help-fns--analyze-function fn))
@@ -73,12 +74,6 @@
        (push ,desc functions))
      ,@examples))
 
-(defun quote-and-downcase (string)
-  (format "`%s`" (downcase string)))
-
-(defun unquote-and-link (string)
-  (format-link (substring string 1 -1)))
-
 (defun format-link (string-name)
   (-let* ((name (intern string-name))
           ((_ signature _ _) (assoc name functions)))
@@ -86,15 +81,51 @@
         (format "[`%s`](#%s)" name (github-id name signature))
       (format "`%s`" name))))
 
-(defun format-docstring (docstring)
-  (let ((case-fold-search nil))
-    (--> docstring
-      (replace-regexp-in-string
-       (rx bow (in upper) (* (in upper ?-)) (* num) eow)
-       #'quote-and-downcase it t t)
-      (replace-regexp-in-string (rx ?` (+? (not (in " `"))) ?\')
-                                #'unquote-and-link it t t)
-      (replace-regexp-in-string (rx bol "  ") "    " it t t))))
+(defun dash--quote-argnames ()
+  "Downcase and quote arg names in current buffer for Markdown."
+  (let ((beg (point-min)))
+    (while (setq beg (text-property-any beg (point-max)
+                                        'face 'help-argument-name))
+      (goto-char beg)
+      (insert ?`)
+      (goto-char (or (next-single-property-change (point) 'face)
+                     (point-max)))
+      (downcase-region (1+ beg) (point))
+      (insert ?`)
+      (setq beg (point)))))
+
+(defun dash--quote-metavars ()
+  "Downcase and quote metavariables in current buffer for Markdown."
+  (goto-char (point-min))
+  (while (re-search-forward (rx bow (group (in upper) (* (in upper ?-)) (* 
num))
+                                (| (group ?\() (: (group (? "th")) eow)))
+                            nil t)
+    (unless (match-beginning 2)
+      (let* ((suf (match-string 3))
+             (var (format "`%s`%s" (downcase (match-string 1)) suf)))
+        (replace-match var t t)))))
+
+(defun dash--quote-hyperlinks ()
+  "Convert hyperlinks in current buffer from Elisp to Markdown."
+  (goto-char (point-min))
+  (while (re-search-forward (rx ?` (+? (not (in " `"))) ?\') nil t)
+    (replace-match (format-link (substring (match-string 0) 1 -1)) t t)))
+
+(defun dash--indent-blocks ()
+  "Indent example blocks in current buffer for Markdown."
+  (goto-char (point-min))
+  (while (re-search-forward (rx bol "  ") nil t)
+    (replace-match "    " t t)))
+
+(defun dash--format-docstring (docstring)
+  (with-temp-buffer
+    (let ((case-fold-search nil))
+      (insert docstring)
+      (dash--quote-argnames)
+      (dash--quote-metavars)
+      (dash--quote-hyperlinks)
+      (dash--indent-blocks)
+      (buffer-string))))
 
 (defun function-to-md (function)
   (if (stringp function)
@@ -103,8 +134,8 @@
       (format "#### %s `%s`\n\n%s\n\n```el\n%s\n```\n"
               command-name
               signature
-              (format-docstring docstring)
-              (mapconcat 'identity (-take 3 examples) "\n")))))
+              (dash--format-docstring docstring)
+              (mapconcat #'identity (-take 3 examples) "\n")))))
 
 (defun docs--chop-prefix (prefix s)
   "Remove PREFIX if it is at the start of S."