Improve clarity of some docstrings (#1800)

Co-authored-by: sogaiu <983021772@users.noreply.github.com>

src/boot/boot.janet

@@ -1646,14 +1646,18 @@
     (reverse! (seq [v :in t] v))))
 
 (defn invert
-  ``Given an associative data structure `ds`, returns a new table where the
-  keys of `ds` are the values, and the values are the keys. If multiple keys
-  in `ds` are mapped to the same value, only one of those values will
-  become a key in the returned table.``
-  [ds]
+  ``
+  Returns a table where the keys of `x` are the values, and the values
+  are the keys. If multiple keys in `x` are mapped to the same value,
+  only one of those values will become a key in the returned table.
+
+  `x` can be a bytes, indexed, dictionary, or abstract type with a
+  `suitable next` method.
+  ``
+  [x]
   (def ret @{})
-  (loop [k :keys ds]
-    (put ret (in ds k) k))
+  (loop [k :keys x]
+    (put ret (in x k) k))
   ret)
 
 (defn zipcoll
@@ -1756,7 +1760,12 @@
   container)
 
 (defn keys
-  "Get the keys of an associative data structure."
+  ``
+  Get the keys of `x` as an array.
+
+  `x` can be a bytes, indexed, dictionary, or abstract type with a
+  suitable `next` method.
+  ``
   [x]
   (if (lengthable? x)
     (do
@@ -1769,7 +1778,12 @@
     (seq [k :keys x] k)))
 
 (defn values
-  "Get the values of an associative data structure."
+  ``
+  Get the values of `x` as an array.
+
+  `x` can be a bytes, indexed, dictionary, fiber, or abstract type
+  with suitable `get` and `next` methods.
+  ``
   [x]
   (if (lengthable? x)
     (do
@@ -1782,7 +1796,13 @@
     (seq [v :in x] v)))
 
 (defn pairs
-  "Get the key-value pairs of an associative data structure."
+  ``
+  Return an array of tuples of the key-value pairs of `x`. For bytes
+  and indexed types, the integer indices are considered the keys.
+
+  `x` can be a bytes, indexed, dictionary, or abstract type with
+  suitable `get` and `in` methods.
+  ``
   [x]
   (if (lengthable? x)
     (do

src/core/corelib.c

@@ -1247,13 +1247,18 @@ JanetTable *janet_core_env(JanetTable *replacements) {
                          "abstract type with a suitable `get` method."));
     janet_quick_asm(env, JANET_FUN_PUT,
                     "put", 3, 3, 3, 3, put_asm, sizeof(put_asm),
-                    JDOC("(put ds key value)\n\n"
-                         "Associate a key with a value in any mutable associative data structure. Indexed data structures "
-                         "(arrays and buffers) only accept non-negative integer keys, and will expand if an out of bounds "
-                         "value is provided. In an array, extra space will be filled with nils, and in a buffer, extra "
-                         "space will be filled with 0 bytes. In a table, putting a key that is contained in the table prototype "
-                         "will hide the association defined by the prototype, but will not mutate the prototype table. Putting "
-                         "a value nil into a table will remove the key from the table. Returns the data structure ds."));
+                    JDOC("(put x key val)\n\n"
+                         "Associate `key` with `val` for mutable `x`. Arrays "
+                         "and buffers only accept non-negative integer keys, "
+                         "and will expand if an out of bounds value is "
+                         "provided. For an array, extra space will be filled "
+                         "with `nil`s, while for buffers, 0 bytes are used "
+                         "instead. For a table, putting a key that is in the "
+                         "table prototype will hide the association defined by "
+                         "the prototype, but will not mutate the prototype "
+                         "table. Putting a `nil` value into a table will "
+                         "remove the table's corresponding association. "
+                         "Returns `x`."));
     janet_quick_asm(env, JANET_FUN_LENGTH,
                     "length", 1, 1, 1, 1, length_asm, sizeof(length_asm),
                     JDOC("(length ds)\n\n"