From fd9ceef1ae818f8ac78c4424804bf8aedc4cb87c Mon Sep 17 00:00:00 2001
From: Veit Heller <veit@veitheller.de>
Date: Tue, 30 Mar 2021 10:22:18 +0200
Subject: [PATCH] docs: add docstrings to some dynamic functions (#1191)

---
 core/Dynamic.carp | 11 ++++++++++-
 core/List.carp    | 12 ++++++++++++
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/core/Dynamic.carp b/core/Dynamic.carp
index 14cbfaa8..ccce54fe 100644
--- a/core/Dynamic.carp
+++ b/core/Dynamic.carp
@@ -10,15 +10,20 @@
   (defndynamic nil? [value]
     (= value nil))
 
+  (doc inc "increments a number.")
   (defndynamic inc [x]
     (+ x 1))
 
+  (doc dec "decrements a number.")
   (defndynamic dec [x]
     (- x 1))
 
+  (doc neg "negates a number.")
   (defndynamic neg [x]
     (* -1 x))
 
+  (doc mod "implements modulo, is slower than modulo specialized on
+integers [`imod`](#imod).")
   (defndynamic mod [x y]
     (let-do [a (if (< x 0) (neg x) x)
              b (if (< y 0) (neg y) y)
@@ -27,7 +32,7 @@
         (set! m (- m b)))
       (if (< a 0) (neg m) m)))
 
-  (doc imod "implements the modulo on integers, and is much faster than
+  (doc imod "implements modulo on integers, and is much faster than
 [`mod](#mod).")
   (defndynamic imod [x y]
     (- x (* y (/ x y))))
@@ -46,15 +51,19 @@
         (Project.config "echo-compiler-cmd" false))))
 
   (defmodule String
+    (doc prefix "takes the prefix of the string `s` up to the index `to`.")
     (defndynamic prefix [s to]
       (String.slice s 0 to))
 
+    (doc suffix "takes the suffix of the string `s` from the index `from`.")
     (defndynamic suffix [s from]
       (String.slice s from (String.length s)))
 
+    (doc head "takes the head of the string `s` as a one-character string.")
     (defndynamic head [s]
       (String.prefix s 1))
 
+    (doc tail "takes the tail of the string `s`.")
     (defndynamic tail [s]
       (String.suffix s 1))
   )
diff --git a/core/List.carp b/core/List.carp
index 85281616..9671251b 100644
--- a/core/List.carp
+++ b/core/List.carp
@@ -1,5 +1,14 @@
 (defmodule Dynamic
 
+  (doc cxr "takes a specification of a traversal in `a` (head) and `d` (tail)
+symbols and a list `pair` to traverse.
+
+Example:
+```
+(cxr '(1 a 1 d) '(1 2 3)) ; => 2
+
+(cxr '(1 a 1 d 1 a 4 d) '(1 2 3 4 (5 6 7))) ; => 6
+```")
   (defndynamic cxr [x pair]
     (cond
       (= (length x) 0) pair
@@ -12,12 +21,15 @@
           (cxr (cddr x) pair)
           (cxr (cons (- (car x) 1) (cdr x)) pair)))))
 
+  (doc nthcdr "takes the `n`th tail or `cdr` of the list `pair`.")
   (defndynamic nthcdr [n pair]
     (cxr (list (+ n 1) 'd) pair))
 
+  (doc nthcar "takes the `n`th head or `car` of the list `pair`.")
   (defndynamic nthcar [n pair]
     (cxr (list 1 'a n 'd) pair))
 
+  (hidden collect-into-internal)
   (defndynamic collect-into-internal [xs acc f]
     (if (= 0 (length xs))
         acc