Merge pull request #164 from sogaiu/minor-tweaks

Mostly tweak some docstrings

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]

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)

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

spork/getline.janet

@@ -60,20 +60,20 @@
 
 (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)
   (default autocomplete-options default-autocomplete-options)
   (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)

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

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

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

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

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,28 +337,28 @@
 
 (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]
   ~(as-macro ,cap* :out ,;body))
 
 (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))
 

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

spork/randgen.janet

@@ -56,7 +56,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))
@@ -82,13 +82,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))))