Finished addressing the docstrings.

Author: Jason Duncan

TODO.org

@@ -1,4 +1,4 @@
-** TODO Some docstrings are quite long which lets you pass package-lint and makes for good enough M-x apropos output, but they wrap poorly in M-x help.
+** DONE Some docstrings are quite long which lets you pass package-lint and makes for good enough M-x apropos output, but they wrap poorly in M-x help.
 ** DONE "delimiater" -> "delimiter"
 ** DONE Since you're using Emacs 25 you can use the string-trim functions (could format-table-trim-row be rewritten as just (string-trim row begin-row end-row)?
 ** DONE Could the first conditional in format-table-remove-noise be written either as:

format-table.el

@@ -73,11 +73,11 @@
     (json . json)))
 
 (defun format-table-pad-right (value length)
-  "Pad the string VALUE to the length specified by LENGTH using spaces to the right."
+  "Pad the string VALUE to the LENGTH specified using spaces to the right."
   (format (concat "%-" (number-to-string length) "s") value))
 
 (defun format-table-pad-center (value length)
-  "Pad the string VALUE to the length specified by LENGTH by surrounding with spaces."
+  "Pad the string VALUE to the LENGTH specified by surrounding with spaces."
   (let* ((value-length (length value))
          (left-length (/ (- length value-length) 2))
          (right-length (+ left-length
@@ -93,6 +93,9 @@
      (make-string right-length ? ))))
 
 (defun format-table-remove-noise (lines input-mode)
+  "Remove lines which constitute noise, such as empty lines or results count.
+LINES is the list of source lines, split on newlines.  INPUT-MODE is used to
+determine what the results count should look like."
   "Given the set of table LINES and some extra information in INPUT-MODE, filter out any empty lines or lines which otherwise do not belong to the table of values."
   (let* ((row-count-format (plist-get input-mode :row-count-format))
          (regexp (when row-count-format (format row-count-format "[[:digit:]]+")))
@@ -107,7 +110,10 @@
           (-slice ret 0 (1- (length ret))) ret))))
 
 (defun format-table-get-col-widths (dashes input-mode)
-  "Using the line of all DASHES from the table and the INPUT-MODE, determine the widths of the columns and return them in a list."
+  "Determine the widths of each column in the table.
+DASHES is a string containing the row from the source table which separates the
+header from the body of the table.  INPUT-MODE is used to determine what column
+separators and such should look like."
   (let* ((separator-begin-row (regexp-quote (plist-get input-mode :separator-begin-row)))
          (separator-end-row (regexp-quote (plist-get input-mode :separator-end-row)))
          (separator-col-separator (plist-get input-mode :separator-col-separator))
@@ -116,7 +122,9 @@
                                  (regexp-quote separator-col-separator)))))
 
 (defun format-table-split-row (row col-widths input-mode)
-  "Split the given string ROW based on the fixed positions listed in COL-WIDTHS and any additional information in INPUT-MODE."
+  "Split the given string ROW based on the fixed positions listed in COL-WIDTHS.
+INPUT-MODE is used to determine what beginning of row, end of row, and column
+separators should look like."
   (let* ((begin-row (plist-get input-mode :begin-row))
          (end-row (plist-get input-mode :end-row))
          (col-separator (plist-get input-mode :col-separator))
@@ -135,29 +143,28 @@
                                 cur-width))))))))
 
 (defun format-table-assemble-table (header body)
-  "Given the HEADER list of column names and nested list of values BODY, return an alist with both and some extra meta information about same."
+  "Assemble the HEADER and BODY of the table into an alist with some extra info."
   (let ((max-col-widths (format-table-get-max-col-widths (cons header body))))
     (list :header header
           :body body
           :max-col-widths max-col-widths
           :row-count (length body))))
 
 (defun format-table-parse-table (lines col-widths input-mode)
-  "Given the list of table LINES, set of COL-WIDTHS, and INPUT-MODE, build a table of values as a plist."
+  "Parse the list of table LINES into a plist."
   (let* ((header (format-table-split-row (car lines) col-widths input-mode))
          (body (--map (format-table-split-row it col-widths input-mode) (-slice lines 2))))
     (format-table-assemble-table header body)))
 
 (defun format-table-get-max-col-widths (table)
-  "Determine the length of the longest value in each column from TABLE and return as a list."
+  "List the length of the longest value in each column from TABLE."
   (let ((last (make-list (length (car table)) 0)))
     (dolist (cur-row table last)
       (setq last
             (-zip-with #'max (-map #'length cur-row) last)))))
 
 (defun format-table-render-row (row max-col-widths output-mode &optional pad-fn)
   "Render a table row with the proper column separators and a newline.
-
 Arguments are the list of values ROW, the list of MAX-COL-WIDTHS, and delimiter
 information in OUTPUT-MODE.  Optionally use PAD-FN to pad each column value,
 otherwise values will be padded to the right with spaces."
@@ -177,7 +184,6 @@ otherwise values will be padded to the right with spaces."
 
 (defun format-table-render-separator-row (max-col-widths output-mode)
   "Render a row which separates the header row from the rest of the rows.
-
 Columns will be spaced accrding to MAX-COL-WIDTHS and delimited using strings
 from OUTPUT-MODE."
   (append
@@ -244,7 +250,7 @@ from OUTPUT-MODE."
     (format-table-assemble-table header body)))
 
 (defun format-table-cleanup-and-parse (str input-mode)
-  "Parse the given string STR using delimiter information in INPUT-MODE to a plist."
+  "Parse the given STR using delimiter information in INPUT-MODE to a plist."
   (if (equal input-mode 'json)
       (format-table-parse-json str)
     (let* ((lines (split-string str "[\n]+"))
@@ -255,7 +261,6 @@ from OUTPUT-MODE."
 
 (defun format-table (str input-mode output-mode)
   "Reformat tabular data.
-
 Process the given string STR containing a table in a format specified by
 INPUT-MODE, gather and reformat the table contained within to the format
 specified by OUTPUT-MODE."