Migrate from travis to candle

[wolf] / src / main / syntax-checker.lisp

diff --git a/src/main/syntax-checker.lisp b/src/main/syntax-checker.lisp
index 1190818bd2bea72a1a1e4cf09e639a01f743ed95..f6c31da66c7415ee683e1088287c6a5b64e08070 100644 (file)
--- a/src/main/syntax-checker.lisp
+++ b/src/main/syntax-checker.lisp
@@ -87,6 +87,30 @@
   (let ((seq (make-sequence sequence-type (file-length str)))) (read-sequence seq str) seq)))
 
 (defun check-file (file)
+ "CHECK-FILE FILE => RESULT
+
+  RESULT: SUCCESS-RESULT | FAILURE-RESULT
+  SUCCESS-RESULT: (:success FILENAME)
+  FAILURE-RESULT: (:success FILENAME MSG LINE-NO COL-NO)
+
+ARGUMENTS AND VALUES:
+
+  FILE: a pathname
+  FILENAME: the file this check was run on
+  MSG: a string containing the failure message
+  LINE-NO: an integer, the line number on which the failure appeared
+  COL-NO: an integer, the column number on which the failure appeared
+
+DESCRIPTION:
+
+  CHECK-FILE runs all the checks against a file and returns
+  as soon as the first style error is found.
+
+EXAMPLES:
+
+  (check-file #P\"path/to/file.lisp\") => (:success \"path/to/file.lisp\")
+  (check-file #P\"path/to/error.lisp\") => (:failure \"path/to/error.lisp\" \"File cannot end with empty line\" 20 0)"
+
  (if (string= "package" (pathname-name file))
   (set-state :normal)
   (set-state :begin))
@@ -102,6 +126,23 @@
    (list :failure file (check-failure-msg cf) (check-failure-line-no cf) (check-failure-col-no cf)))))
 
 (defun check-directory (dir)
+ "CHECK-DIRECTORY DIR => RESULTS
+
+  RESULTS: RESULT*
+
+ARGUMENTS AND VALUES:
+
+  DIR: A directory to recurse into and check files
+  RESULT: A result as returned by check-file
+
+DESCRIPTION:
+
+  CHECK-DIRECTORY grabs all .lisp files in the tree under DIR, and loads
+  checks them all.
+
+  The results are then put together into a list which can be programatically
+  evaluated.  As opposed to pretty-print-check-directory, this function doesn't
+  clutter up your standard out."
  (mapcar #'check-file (directory (format nil "~A/**/*.lisp" dir))))
 
 (defun any-failures (checks)
@@ -118,6 +159,24 @@
   (+ (fifth failure) 2)))
 
 (defun pretty-print-check-directory (dir)
+ "PRETTY-PRINT-CHECK-DIRECTORY DIR => SUCCESS
+
+ARGUMENTS AND VALUES:
+
+  DIR: A directory to recurse into and check files
+  SUCCESS: T if there were no failures
+
+DESCRIPTION:
+
+  PRETTY-PRINT-CHECK-DIRECTORY checks DIR for any errors, dumping them to output
+  and returning a single flag.
+
+  Unlike check-directory, PRETTY-PRINT-CHECK-DIRECTORY is built for continuous
+  integration, dumping errors to standard out and returning a singular result.
+
+EXAMPLES:
+
+  (pretty-print-check-directory \"src\") => nil"
  (let
   ((checks (check-directory dir)))
   (format t "In ~A: Checked ~A files with ~A failures~%~%"