From e8d812510613d94130441a94a737dbef94a81780 Mon Sep 17 00:00:00 2001
From: sogaiu <983021772@users.noreply.github.com>
Date: Wed, 27 Dec 2023 16:28:43 +0900
Subject: [PATCH] Mostly tweak some docstrings

---
 spork/cc.janet      | 16 ++++++++--------
 spork/cjanet.janet  |  2 +-
 spork/cron.janet    |  6 +++---
 spork/getline.janet | 14 +++++++-------
 spork/http.janet    |  4 ++--
 spork/httpf.janet   |  2 +-
 spork/math.janet    | 12 ++++++------
 spork/mdz.janet     |  2 +-
 spork/misc.janet    | 46 ++++++++++++++++++++++-----------------------
 spork/pgp.janet     |  2 +-
 spork/randgen.janet |  6 +++---
 spork/regex.janet   | 12 ++++++------
 spork/schema.janet  |  2 +-
 spork/sh.janet      |  2 +-
 spork/tasker.janet  |  6 +++---
 spork/test.janet    | 12 ++++++------
 16 files changed, 73 insertions(+), 73 deletions(-)

diff --git a/spork/cc.janet b/spork/cc.janet
index 2043665..df65bb7 100644
--- a/spork/cc.janet
+++ b/spork/cc.janet
@@ -47,7 +47,7 @@
 (defdyn *pkg-config-flags* "Extra flags to pass to pkg-config")
 (defdyn *smart-libs*
   ``Try to resolve circular or out-of-order dependencies between libraries by using --start-group and --end-group.
-  Some linkers support this by default, but  not at all. Defaults to true on linux and macos.``)
+  Some linkers support this by default, but not at all. Defaults to true on linux and macos.``)
 (defdyn *c-std* "C standard to use as a 2 digit number, defaults to 99 on GCC-like compilers, 11 on msvc.")
 (defdyn *c++-std* "C++ standard to use as a 2 digit number, defaults to 11 on GCC-like compilers, 14 on msvc.")
 
@@ -78,7 +78,7 @@
     (path/abspath (string sp "/.."))))
 
 (defn- include-path []
-  "Guess a library path based on the current system path"
+  "Guess a header path based on the current system path"
   (def lp (lib-path))
   (if lp
     (path/join lp "../include")))
@@ -211,7 +211,7 @@
         objects [to] (string "linking " to "...")))
 
 (defn link-executable-c++
-  "Link a C program to make an executable. Return the command arguments."
+  "Link a C++ program to make an executable. Return the command arguments."
   [objects to]
   (exec [(c++) (c++std) ;(opt) ;(extra-paths) ;(c++flags) "-o" to ;objects ;(rdynamic) "-pthread" ;(libs)]
         objects [to] (string "linking " to "...")))
@@ -258,7 +258,7 @@
   [has-cpp objects])
 
 (defn compile-and-link-shared
-  "Compile and link a shared C/C++ program. Return an array of commands."
+  "Compile and link a shared C/C++ library. Return an array of commands."
   [to & sources]
   (def res @[])
   (def [has-cpp objects] (compile-many sources res))
@@ -343,7 +343,7 @@
         [from] [to] (string "compiling " from "...")))
 
 (defn msvc-compile-c++
-  "Compile a C program with MSVC. Return the command arguments."
+  "Compile a C++ program with MSVC. Return the command arguments."
   [from to]
   (exec [(cl.exe) "/c" (msvc-c++std) "/utf-8" "/nologo" "/EHsc" ;(c++flags) ;(msvc-compile-paths) ;(msvc-opt) ;(msvc-defines)
          "/I" (dyn *syspath* ".") from (string "/Fo" to)]
@@ -392,7 +392,7 @@
   objects)
 
 (defn msvc-compile-and-link-shared
-  "Compile and link a shared C/C++ program. Return an array of commands."
+  "Compile and link a shared C/C++ library. Return an array of commands."
   [to & sources]
   (def res @[])
   (def objects (msvc-compile-many sources res))
@@ -510,14 +510,14 @@
   notfound)
 
 (defn search-libraries
-  "Search for static libraries on the current POSIX system and configure `(dyn *static-libraries*)`.
+  "Search for libraries on the current POSIX system and configure `(dyn *libs*)`.
   This is done by checking for the existence of libraries with
   `check-library-exists`. Returns an array of libraries that were not found."
   [& libs]
   (search-libs-impl *libs* libs))
 
 (defn search-static-libraries
-  "Search for static libraries on the current POSIX system and configure `(dyn *static-libraries*)`.
+  "Search for static libraries on the current POSIX system and configure `(dyn *static-libs*)`.
   This is done by checking for the existence of libraries with
   `check-library-exists`. Returns an array of libraries that were not found."
   [& libs]
diff --git a/spork/cjanet.janet b/spork/cjanet.janet
index 7247552..e37d23f 100644
--- a/spork/cjanet.janet
+++ b/spork/cjanet.janet
@@ -53,7 +53,7 @@
   (peg/compile '(* '(to ":") ":" '(to "=") "=" '(any 1))))
 
 (defn- type-split-dflt
-  "Same as type split, but require a name, type, and default. Support (name type dflt), as well
+  "Same as type split, but require a name, type, and default. Supports (name type dflt), as well
   as name:type=dflt."
   [x]
   (case (type x)
diff --git a/spork/cron.janet b/spork/cron.janet
index 4b68407..e563a25 100644
--- a/spork/cron.janet
+++ b/spork/cron.janet
@@ -4,9 +4,9 @@
 ### Timer library for interfacing with the UNIX crontab format.
 ###
 ### The cron format support is based on the unix cron syntax, with an optional
-### seconds field. Each field can be a comma separated  list of individual values
-### or a range of values. A range is specified by two values with a "-" between them, optional
-### followed by a "/" and a step value. An asterix ("*") can be used to denote all possible values.
+### seconds field. Each field can be a comma separated list of individual values
+### or a range of values. A range is specified by two values with a "-" between them, optionally
+### followed by a "/" and a step value. An asterisk ("*") can be used to denote all possible values.
 ###
 ### The fields:
 ###  * minutes: 0-59
diff --git a/spork/getline.janet b/spork/getline.janet
index 0378bdf..21e7c33 100644
--- a/spork/getline.janet
+++ b/spork/getline.janet
@@ -60,7 +60,7 @@
 
 (defn make-getline
   "Reads a line of input into a buffer, like `getline`. However, allow looking up entries with a general
-  lookup function rather than a environment table."
+  lookup function rather than an environment table."
   [&opt autocomplete-context autocomplete-options doc-fetch]
 
   (default autocomplete-context default-autocomplete-context)
@@ -68,12 +68,12 @@
   (default doc-fetch default-doc-fetch)
 
   # state
-  (var w "last measured terminal width (columns)" 0)
-  (var h "last measured height (rows)" 0)
-  (var buf "line buffer" @"")
-  (var prpt "prompt string (line prefix)" "")
-  (var prpt-width "prompt string character width" 0)
-  (def history "history stack. Top item is current placeholder." @[])
+  (var w "Last measured terminal width (columns)" 0)
+  (var h "Last measured height (rows)" 0)
+  (var buf "Line buffer" @"")
+  (var prpt "Prompt string (line prefix)" "")
+  (var prpt-width "Prompt string character width" 0)
+  (def history "History stack. Top item is current placeholder." @[])
   (def tmp-buf "Buffer to group writes to stderr for terminal rendering." @"")
   (var pos "Cursor byte position in buf. Must be on valid utf-8 start byte at all times." 0)
   (var lines-below "Number of dirty lines below input line for drawing cleanup." 0)
diff --git a/spork/http.janet b/spork/http.janet
index 7caca5a..cd489ca 100644
--- a/spork/http.janet
+++ b/spork/http.janet
@@ -109,7 +109,7 @@
      for every string key, and any query parameters that aren't given a value are mapped to true.
 
   Note that data is read in chunks and any data after the header terminator is
-  stored in `:buffer.`"
+  stored in `:buffer`."
   [conn buf &opt no-query]
   (def head (read-header conn buf request-peg :method :path))
   (if (= :error head) (break head))
@@ -138,7 +138,7 @@
   * `:message` - the HTTP status message.
 
   Note that data is read in chunks and any data after the header terminator is
-  stored in `:buffer.`"
+  stored in `:buffer`."
   [conn buf]
   (read-header conn buf response-peg :status :message))
 
diff --git a/spork/httpf.janet b/spork/httpf.janet
index c2c87f0..1f4ac05 100644
--- a/spork/httpf.janet
+++ b/spork/httpf.janet
@@ -99,7 +99,7 @@
     (describe x)))
 
 (defn add-route
-  "Add a single manually route to a server. Prefer using `httpf/add-bindings-as-routes` for the usual case."
+  "Add a single route manually to a server. Prefer using `httpf/add-bindings-as-routes` for the usual case."
   [server path docstring schema handler &opt read-mime render-mime]
   (def routes (get server :routes))
   (def docs (get server :route-docs))
diff --git a/spork/math.janet b/spork/math.janet
index ecb5815..0757bfd 100644
--- a/spork/math.janet
+++ b/spork/math.janet
@@ -369,12 +369,12 @@
     (+ b (* m x))))
 
 (defn check-probability
-  "Asserts that probability in in the [0 1] range."
+  "Asserts that probability is in the [0 1] range."
   [p]
   (assert (<= 0 p 1) "probability must be between 0 and 1"))
 
 (defn bernoulli-distribution
-  "Creates Bernoulli distribution from popability `p` in the tuple."
+  "Creates Bernoulli distribution from probability `p` in the tuple."
   [p]
   (check-probability p)
   [(- 1 p) p])
@@ -496,7 +496,7 @@
   ```
   Conducts a permutation test to determine if two data sets
   `xs` and `ys` are *significantly* different from each other.
-  You can use alternative hypotesis `a`, which defaults to `:two-side`,
+  You can use alternative hypothesis `a`, which defaults to `:two-side`,
   with `:greater` and `:lesser` being the other two options.
   The last optional argument is `k` number of values
   in permutation distribution
@@ -959,7 +959,7 @@
 
 (defn binominal-coeficient
   ```
-  Computes binominal coeficient from set of size `n`
+  Computes binominal coefficient from set of size `n`
   and sample size `k`.
   ```
   [n k]
@@ -1004,12 +1004,12 @@
   ~(in (in ,m 0) 0))
 
 (defn rows
-  "Returns numbers of rows of matrix `m`."
+  "Returns number of rows of matrix `m`."
   [m]
   (length m))
 
 (defn cols
-  "Returns numbers of columns of matrix `m`."
+  "Returns number of columns of matrix `m`."
   [m]
   (length (m 0)))
 
diff --git a/spork/mdz.janet b/spork/mdz.janet
index bcc5256..a0572a9 100644
--- a/spork/mdz.janet
+++ b/spork/mdz.janet
@@ -4,7 +4,7 @@
 
 (import ./htmlgen)
 
-(defdyn *front-matter* "Dynamic binding to front matter after parsing, compilation, and evaluation, of markup completes.")
+(defdyn *front-matter* "Dynamic binding to front matter of markup after parsing, compilation, and evaluation completes.")
 (defdyn *markup-dom* "The htmlgen source that can be used to generate a document with htmlgen/html.")
 
 (defn- capture-front
diff --git a/spork/misc.janet b/spork/misc.janet
index fdac1ac..c34f707 100644
--- a/spork/misc.janet
+++ b/spork/misc.janet
@@ -11,7 +11,7 @@
 (defn dedent
   ```
   Remove indentation after concatenating the arguments. Works by removing
-  leading whitespace, and then removing that same pattern of whitepsace after
+  leading whitespace, and then removing that same pattern of whitespace after
   new lines.
   ```
   [& xs]
@@ -137,7 +137,7 @@
   ```
   Iterate through the rows of a data structure and print a table in a human
   readable way, with padding and heading information. Can optionally provide
-  a function use to print a row, as well as optionally select column keys
+  a function used to print a row, as well as optionally select column keys
   for each row. Lastly, a `header-mapping` dictionary can be provided that
   changes the printed header names by mapping column keys to the desired
   header name. If no mapping is found, then the column key will be used as
@@ -164,7 +164,7 @@
   Also allow for callbacks before and after visiting the children
   of a node. Also allow for a custom `get-children` function to
   change traversal as needed. Will detect cycles if an empty table
-  is passed as the `seen` parameter, which is used to cached values
+  is passed as the `seen` parameter, which is used to cache values
   that have been visited.
   ```
   [data visit-leaf &opt node-before node-after get-children seen]
@@ -262,8 +262,8 @@
 (defmacro cond->
   ```
   Threading conditional macro. It takes `val` to mutate,
-  and `clauses` pairs with condition and operation to which the `val`,
-  is put as first argument. All conditions are tried and
+  and `clauses` pairs with condition and operation to which `val`,
+  is passed as first argument. All conditions are tried and
   for truthy conditions the operation is executed.
   Returns the value mutated if any condition is truthy.
   ```
@@ -285,9 +285,9 @@
 (defmacro cond->>
   ```
   Threading conditional macro. It takes `val` to mutate,
-  and `clauses` pairs of condition and operation to which the `val`,
-  is put as last argument. All conditions are tried and
-  for truthy the operation is ran.
+  and `clauses` pairs of condition and operation to which `val`,
+  is passed as last argument. All conditions are tried and
+  for truthy conditions the operation is executed.
   Returns mutated value if any condition is truthy.
   ```
   [val & clauses]
@@ -305,7 +305,7 @@
 
 (defmacro make
   ```
-  Convenience macro for creating new table from even number of kvs pairs in a variadic `table-or-pairs`
+  Convenience macro for creating new table from even number of kvs pairs in variadic `pairs`
   arguments and setting its prototype to `prototype`.
   Factory function for creating new objects from prototypes.
   ```
@@ -314,7 +314,7 @@
 
 (defmacro do-var
   ```
-  Convenience macro for defining varible named `v` with value `d` before `body`
+  Convenience macro for defining variable named `v` with value `d` before `body`
   and returning it after evaluating `body`, that presumably modifies `v`.
   ```
   [v d & body]
@@ -324,7 +324,7 @@
   ```
   Convenience macro for defining constant named `c` with value `d` before `body`
   and returning it after evaluating `body`, that presumably modifies
-  the `c` refered content. For example buffer, table or array.
+  the content referred to by `c`. For example, a buffer, table or array.
   ```
   [c d & body]
   ~(do (def ,c ,d) ,;body ,c))
@@ -337,7 +337,7 @@
 
 (defmacro capout
   ```
-  Captures the standart output of the variadic `body` and returns it as
+  Captures the standard output of the variadic `body` and returns it as
   a buffer.
   ```
   [& body]
@@ -345,20 +345,20 @@
 
 (defmacro caperr
   ```
-  Captures the standart error output of the variadic `body` and returns it
+  Captures the standard error output of the variadic `body` and returns it
   as a buffer.
   ```
   [& body]
   ~(as-macro ,cap* :err ,;body))
 
 (defmacro vars
-  "Defines many variables as in let `bindings`, but without creating new scope."
+  "Defines many variables as in let `bindings`, but without creating a new scope."
   [& bindings]
   ~(upscope
      ,;(seq [[n v] :in (partition 2 bindings)] (tuple 'var n v))))
 
 (defmacro defs
-  "Defines many constants as in let `bindings`, but without creating new scope."
+  "Defines many constants as in let `bindings`, but without creating a new scope."
   [& bindings]
   ~(upscope
      ,;(seq [[n v] :in (partition 2 bindings)] (tuple 'def n v))))
@@ -394,9 +394,9 @@
   (math/trunc (/ ;xs)))
 
 (defmacro gett
-  "Recursive macro (get). Similar to get-in, but keys are variadic argument."
-  [ds & keys]
-  (reduce (fn [t key] (tuple get t key)) ds keys))
+  "Recursive macro (get). Similar to get-in, but `keyz` is variadic."
+  [ds & keyz]
+  (reduce (fn [t key] (tuple get t key)) ds keyz))
 
 (defmacro until
   ```
@@ -408,8 +408,8 @@
 
 (defn table-filter
   ```
-  Filter a key-value structure info a table. Semantics are the same as for
-  built-in `filter`, except that `pred` takes two arguments (key and value.)
+  Filter a key-value structure into a table. Semantics are the same as for
+  built-in `filter`, except that `pred` takes two arguments (key and value).
   Does not consider prototypes.
   ```
   [pred dict]
@@ -456,14 +456,14 @@
         (math/ceil (/ (math/log (math/abs int)) (math/log base)))
         (if (< int 0) 1 0))))
   (var int int)
-  (def neg? (< int 0))
-  (if neg?
+  (def ngtv? (< int 0))
+  (if ngtv?
     (set int (- int)))
   (while (not= int 0)
     (def digit (mod int base))
     (buffer/push buf (int-alphabet digit))
     (set int (int/ int base)))
-  (if neg?
+  (if ngtv?
     (buffer/push buf "-"))
   (string/reverse buf))
 
diff --git a/spork/pgp.janet b/spork/pgp.janet
index 32292a8..ecdce25 100644
--- a/spork/pgp.janet
+++ b/spork/pgp.janet
@@ -143,7 +143,7 @@
 (defn hexs->words
   ```
   Returns an array of pgp words for arbitrary long string of hexs.
-  Sanitizes out the white space from hex-string.
+  Sanitizes out the whitespace from `hex-string`.
   ```
   [hex-string]
   (def hexs
diff --git a/spork/randgen.janet b/spork/randgen.janet
index 0c02130..509f061 100644
--- a/spork/randgen.janet
+++ b/spork/randgen.janet
@@ -49,7 +49,7 @@
     (* cumsum inv-total-weight)))
 
 (defn rand-cdf
-  "Pick a random index, weighted by a discrete cummulative distribution function."
+  "Pick a random index, weighted by a discrete cumulative distribution function."
   [cdf]
   (def p (rand-uniform))
   (def l (length cdf))
@@ -75,13 +75,13 @@
      ,;(array/concat @[] ;(map tuple (range (length paths)) paths))))
 
 (defmacro rand-cdf-path
-  "Execute on of the paths randomly given a discrete distribution as a CDF"
+  "Execute one of the paths randomly given a discrete distribution as a CDF"
   [cdf & paths]
   ~(case (,rand-cdf ,cdf)
      ,;(array/concat @[] ;(map tuple (range (length paths)) paths))))
 
 (defmacro rand-weights-path
-  "Execute on of the paths randomly given a discrete distribution as a set of weights"
+  "Execute one of the paths randomly given a discrete distribution as a set of weights"
   [weights & paths]
   ~(case (,rand-weights ,weights)
      ,;(array/concat @[] ;(map tuple (range (length paths)) paths))))
diff --git a/spork/regex.janet b/spork/regex.janet
index f141551..196dd03 100644
--- a/spork/regex.janet
+++ b/spork/regex.janet
@@ -3,7 +3,7 @@
 ###
 ### A module for compiling a subset of regexes to Janet PEGs.
 ### All regex are considered to be anchored, and performance is
-### is not going to be competitive with a native regex engine.
+### not going to be competitive with a native regex engine.
 ###
 ###
 ### Supported regex features:
@@ -13,9 +13,9 @@
 ###   - Repetitions, e.g. a{1}, a{1,3}. Repetitions are eagerly evaluated.
 ###   - Ranges, e.g. [A-Za-z]
 ###   - Character classes, inverted character classes, e.g. [abc], [^abc]
-###   - Alteration (choice), except alteration is ordered, as in pegs - e.g a|b|c
-###   - Captures using parentheses, .e.g (abc)
-###   - Non-capture groups, e.v. (?:abc)
+###   - Alternation (choice), except alternation is ordered, as in pegs - e.g. a|b|c
+###   - Captures using parentheses, e.g. (abc)
+###   - Non-capture groups, e.g. (?:abc)
 ###
 ###
 ### Features found in other regex may never be added - for more complex usage,
@@ -54,7 +54,7 @@
 
 (defn- make-choice
   "Combine multiple patterns with the choice combinator, or
-  return a the first argument if there is only one argument.
+  return the first argument if there is only one argument.
   Will also reduce multiple choices into a single choice operator."
   [l &opt r]
   (if r
@@ -116,7 +116,7 @@
       # Character modifiers
       :cc-with-mod (/ (* :cc :postfix) ,postfix-modify)
 
-      # Single alteration is a sequence of character classes.
+      # Single alternation is a sequence of character classes.
       :span (/ (some :cc-with-mod) ,make-sequence)
 
       # Captures and groupings
diff --git a/spork/schema.janet b/spork/schema.janet
index 54eb4bc..5ee7936 100644
--- a/spork/schema.janet
+++ b/spork/schema.janet
@@ -26,7 +26,7 @@
 ###    - (props & k v) - Takes a sequence of keys and values (alternating in order). Only matches
 ###      the data if, for a key, the corresponding schema `v` matches.
 ###    - (length l) - Only match if the data has a length of l. Uses of the length combinator should assert
-###      the data type before do a length check.
+###      the data type before doing a length check.
 ###    - (length min max) - Only match lengths between min and max inclusive
 ###    - (peg pattern) - Matches only if the peg matches
 ###    - (not pattern) - Only matches if pattern does not match
diff --git a/spork/sh.janet b/spork/sh.janet
index 4a19817..7001c56 100644
--- a/spork/sh.janet
+++ b/spork/sh.janet
@@ -11,7 +11,7 @@
   (os/open (if (= :windows (os/which)) "NUL" "/dev/null") :rw))
 
 (defn exec
-  "Execute command specified by args returning it's exit code"
+  "Execute command specified by args returning its exit code"
   [& args]
   (os/execute args :p))
 
diff --git a/spork/tasker.janet b/spork/tasker.janet
index 91254b6..1435e3d 100644
--- a/spork/tasker.janet
+++ b/spork/tasker.janet
@@ -170,8 +170,8 @@
 
 (defn queue-task
   "Add a task specification to a queue. Supply an argv string array that will be
-  used to invoke s a subprocess. The optional `note` parameter is just a textual note
-  for task trackingv. The `priority` parameter should be an integer between 0 and 9 inclusive, default
+  used to invoke a subprocess. The optional `note` parameter is just a textual note
+  for task tracking. The `priority` parameter should be an integer between 0 and 9 inclusive, default
   is 4. Lower priority jobs in the same queue will be executed by higher priority. Use input to pass in generic, 
   unstructured input to a task."
   [tasker argv &opt note priority qname timeout expiration input]
@@ -250,7 +250,7 @@
   (ev-utils/join-nursery (tasker :nurse)))
 
 (defn close-queues
-  "Prevent any tasks from being added to queues. When an executor finishes it's
+  "Prevent any tasks from being added to queues. When an executor finishes its
   current job, if there are any, it will terminate. When all executors complete, the
   call to `run-executors` will complete."
   [tasker]
diff --git a/spork/test.janet b/spork/test.janet
index be0b3fe..14d3bca 100644
--- a/spork/test.janet
+++ b/spork/test.janet
@@ -9,7 +9,7 @@
 (def- tests-run-ref (get (dyn 'num-tests-run) :ref))
 
 (defmacro assert
-  "Override's the default assert with some nice error handling."
+  "Overrides the default assert with some nice error handling."
   [x &opt e]
   (default e (string/format "%j" (dyn :macro-form)))
   (def xx (gensym))
@@ -51,7 +51,7 @@
   (set num-tests-run 0))
 
 (defn end-suite
-  "Ends test suite, prints summary and exits if any have failed."
+  "Ends test suite, prints summary and exits if any tests have failed."
   []
   (def delta (- (os/clock) start-time))
   (prinf "test suite %V finished in %.3f seconds - " suite-num delta)
@@ -61,7 +61,7 @@
 (defmacro timeit
   ```
   Time the execution of `form` using `os/clock` before and after,
-  and print the result to stdout.  returns: result of executing `form`.
+  and print the result to stdout.  Returns result of executing `form`.
   Uses `tag` (default "Elapsed time:") to tag the printout.
   ```
   [form &opt tag]
@@ -136,14 +136,14 @@
   ~(as-macro ,suppress-* :out ,;body))
 
 (defmacro suppress-stderr
-  "Suppreses stdout from the body"
+  "Suppreses stderr from the body"
   [& body]
   ~(as-macro ,suppress-* :err ,;body))
 
 (defn assert-docs
   ```
-  Assert that all symbols, when module on the path is required,
-  have proper doc string
+  Assert that all symbols have proper docstring when module on the
+  path is required.
   ```
   [path]
   (loop [[sym val] :pairs (require path)