Add documentation for all the exported symbols

[candle] / src / main / base.lisp

diff --git a/src/main/base.lisp b/src/main/base.lisp
index 871da36596bc4939a5cf924cb1c5df7b839defba..f5995a4aedc5711435f82b17ce36582826934f16 100644 (file)
--- a/src/main/base.lisp
+++ b/src/main/base.lisp
@@ -1,8 +1,50 @@
 (in-package #:candle)
 
-(defvar *candle-dir*)
+(defvar *candle-dir* nil
+ "*CANDLE-DIR*
+
+VALUE TYPE:
+
+  A pathname or pathstring
+
+INITIAL VALUE:
+
+  NIL
+
+DESCRIPTION:
+
+  The main directory for all candle work to be done in.  When the server is running
+  in local mode, this is also the place that builds are built in")
+
+(define-condition candle-error (error)
+ ((reason :initarg :reason :reader candle-error-reason))
+ (:documentation
+  "An error on the server that needs to be handled in the client.
+
+This error is usually because some input was incorrect.  The response will
+have a reason that is a keyword that must be handled.  The current used keywords
+are:
+
+- :project-does-not-exist - if the project isn't in the database
+- :invalid-project-name - the specified name doesn't match the requirements
+- :invlides-project-uri - the uri isn't reachable by git
+- :project-name-taken - name is a duplicate
+- :project-failed-to-get-branches - when refreshing fails
+- :job-does-not-exist - the specified job can't be found"))
+
+(setf (documentation 'candle-error-reason 'function)
+ "CANDLE-ERROR-REASON CANDLE-ERROR => REASON
+
+ARGUMENTS AND VALUES:
+
+  CANDLE-ERROR: the error for the reason
+  REASON: a keyword representing the reason
+
+DESCRIPTION:
+
+  Returns the reason for this candle error.  See the documentation of
+  the candle-error condition for possible values")
 
-(define-condition candle-error (error) ((reason :initarg :reason :reader candle-error-reason)))
 (defun raise-candle-error (reason) (error (make-instance 'candle-error :reason reason)))
 
 (lame-db:defdbstruct project name src)
@@ -15,9 +57,32 @@
 ; - :in-progress - job is running
 (lame-db:defdbstruct job status sha create-date log (project :join project))
 
+(setf (documentation 'job-project 'function)
+ "JOB-PROJECT JOB => PROJECT
+
+ARGUMENTS AND VALUES:
+
+  JOB: a job
+  PROJECT: the project for this job
+
+DESCRIPTION:
+
+  Returns the project for the job in question.")
+
 ; in-git here refers to whether the branch exists in git.  As branches get deleted,
 ; this will get set to nil but we keep them around for historical reference
 (lame-db:defdbstruct branch name in-git (project :join project) (job :join job))
 
 (defun project-dir (project)
+ "PROJECT-DIR PROJECT => DIR
+
+ARGUMENTS AND VALUES:
+
+  PROJECT: the project
+  DIR: the working directory for the project
+
+DESCRIPTION:
+
+  Returns the checked out directory for this project, specifically for use
+  in candle.  Resides in the *CANDLE-DIR*."
  (format nil "~Arepos/~A/" *candle-dir* (project-name project)))