From: Frank Duncan <frank@kank.net>
Date: Sat, 18 Dec 2021 22:18:37 +0000 (-0600)
Subject: Add documentation for all the exported symbols
X-Git-Url: https://code.consxy.com/gitweb/gitweb.cgi?a=commitdiff_plain;h=a50fef6f3bacc24a838e81092104f3082b15bad4;p=candle

Add documentation for all the exported symbols
---

diff --git a/src/main/base.lisp b/src/main/base.lisp
index 871da36..f5995a4 100644
--- 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)))
diff --git a/src/main/package.lisp b/src/main/package.lisp
index 7545b28..6365450 100644
--- a/src/main/package.lisp
+++ b/src/main/package.lisp
@@ -5,7 +5,12 @@
   #:project-job-information #:get-job-log #:retry-job #:job-project #:project-dir #:process-job-in-system
   #:shutdown-system
 
-  #:candle-error #:candle-error-reason))
+  #:candle-error #:candle-error-reason)
+ (:documentation "Main candle package.
+
+Candle is continuous integration server and command line utility for common
+lisp projects.  The package is mainly accessed through the command line
+scripts in the bin directory."))
 
 (defpackage #:candle-cli (:use :cl) (:export :run))
 (defpackage #:candle-server-cli (:use :cl) (:export :run))
diff --git a/src/main/processor.lisp b/src/main/processor.lisp
index 5e33639..5a37777 100644
--- a/src/main/processor.lisp
+++ b/src/main/processor.lisp
@@ -3,9 +3,56 @@
 (defvar *mutex* (sb-thread:make-mutex))
 (defvar *waitq* (sb-thread:make-waitqueue))
 
-(defvar *job-system*)
-(defgeneric process-job-in-system (job-system job))
-(defgeneric shutdown-system (job-system))
+(defvar *job-system* nil
+ "*JOB-SYSTEM*
+
+VALUE TYPE:
+
+  A keyword
+
+INITIAL VALUE:
+
+  NIL
+
+DESCRIPTION:
+
+  The job system the server is running under.  When implementing a job
+  system, the generics PROCESS-JOB-IN-SYSTEM and SHUTDOWN-SYSTEM must
+  be implemented.  Is set by the command line when the server is started.")
+
+(defgeneric process-job-in-system (job-system job)
+ (:documentation
+  "PROCESS-JOB-IN-SYSTEM JOB-SYSTEM JOB => SUCCESS, LOG
+
+ARGUMENTS AND VALUES:
+
+  JOB-SYSTEM: a keyword representing an installed system
+  JOB: A job to be run
+  SUCCESS: A boolean, whether the job was successful
+  LOG: The log from the job
+
+DESCRIPTION:
+
+  Runs a job in the specified system.  The code will be checked out,
+  so any defining system should copy the code from the job's project's
+  code dir to wherever it will run, and then ran `candle run` inside
+  that directory, capturing the output."))
+
+(defgeneric shutdown-system (job-system)
+ (:documentation
+  "SHUTDOWN-SYSTEM JOB-SYSTEM => UNUSED
+
+ARGUMENTS AND VALUES:
+
+  JOB-SYSTEM: a keyword representing an installed system
+  UNUSED: the result is unused
+
+DESCRIPTION:
+
+  Shuts down the specified system.  Sometimes this will be an empty
+  method, as the system requires no special shutdown instructions.
+  This is run when the candle server is shutdown for the job system
+  that's specified."))
 
 (defun start-processor-thread ()
  (log:info "Starting processor in ~(~A~) mode" *job-system*)
diff --git a/src/main/run.lisp b/src/main/run.lisp
index d6b963c..d979735 100644
--- a/src/main/run.lisp
+++ b/src/main/run.lisp
@@ -11,6 +11,16 @@
   (format t "~c[1;31m- ~:(~A~) Failed!~c[0m~%" #\Esc (getf task :name) #\Esc)))
 
 (defun run ()
+ "RUN => RESULT
+
+ARGUMENTS AND VALUES:
+
+  RESULT: a boolean, whether the process was successful
+
+DESCRIPTION:
+
+  Runs the script specified by the .candle file in the current directory.
+  When completed, the boolean will be returned if it was successful or not."
  (if
   (not (probe-file ".candle"))
   :dot-candle-absent
diff --git a/src/main/server.lisp b/src/main/server.lisp
index 3f022f3..e1b8cb6 100644
--- a/src/main/server.lisp
+++ b/src/main/server.lisp
@@ -1,6 +1,23 @@
 (in-package #:candle)
 
 (defun server (port &optional (background t))
+ "SERVER PORT &optional BACKGROUND => UNUSED
+
+ARGUMENTS AND VALUES:
+
+  PORT: the port to start the communication server on
+  BACKGROUND: a boolean, defaulting to T
+  UNUSED: the result is unused
+
+DESCRIPTION:
+
+  Starts the server, listening for commands from the client on PORT.
+
+  If BACKGROUND is T, then the communication thread starts in the background,
+  which is useful when starting the server from an already running process.
+  Generally, if running from a script, you'll want BACKGROUND to be NIL,
+  so that the process doesn't exit immediately."
+
  (when (not *candle-dir*) (error "Need a candle dir"))
  (let*
   ((data-dir (format nil "~Adata" *candle-dir*))
@@ -56,6 +73,23 @@
    (raise-candle-error :project-does-not-exist))))
 
 (defun add-project (name src)
+ "ADD-PROJECT NAME SRC => RESULT
+
+ARGUMENTS AND VALUES:
+
+  NAME: a string, representing the name of the project
+  SRC: a pathname, or pathstring, holding the location of the project
+  RESULT: if no error generated, returns t
+
+DESCRIPTION:
+
+  Creates and adds a project to the database.  NAME must be a
+  unique alphanumeric (hyphens allowed) string.  SRC must be a git
+  accessible location for the running user, requiring keys to be set
+  up or it be located on the local disk.
+
+  In addition to adding to the database, it will also clone the project
+  and analyze it intially (calling REFRESH-PROJECT)."
  (when
   (not (cl-ppcre:scan "^[0-9A-Za-z-]*$" name))
   (raise-candle-error :invalid-project-name))
@@ -73,6 +107,19 @@
  t)
 
 (defun refresh-project (name)
+ "REFRESH-PROJECT NAME => RESULT
+
+ARGUMENTS AND VALUES:
+
+  NAME: a string, representing the name of the project
+  RESULT: unused
+
+DESCRIPTION:
+
+  Refreshes the project from git's origin.  Fetches, and then
+  analysis all branches available to create jobs for any new
+  commits that those branches are set to.  Then wakes up the
+  processor thread to start working through those jobs."
  (let*
   ((project (find-project-by-name-or-die name))
    (branches (find-branch-by-project project)))
@@ -101,6 +148,17 @@
  (awaken-processor-thread))
 
 (defun delete-project (name)
+ "DELETE-PROJECT NAME => RESULT
+
+ARGUMENTS AND VALUES:
+
+  NAME: a string, representing the name of the project
+  RESULT: unused
+
+DESCRIPTION:
+
+  Removes a project from the database and the disk.  NAME must
+  be an existing project."
  (let
   ((project (find-project-by-name-or-die name)))
   (sb-ext:delete-directory (project-dir project) :recursive t)
@@ -112,6 +170,26 @@
  (list (project-name (job-project job)) (job-sha job) (job-status job) (job-create-date job)))
 
 (defun project-branch-information (name)
+ "PROJECT-BRANCH-INFORMATION NAME => BRANCHES-INFORMATION
+
+  BRANCHES-INFORMATION: BRANCH-INFORMATION*
+  BRANCH-INFORMATION: (BRANCH-NAME JOB-INFORMATION)
+  JOB-INFORMATION: (JOB-PROJECT-NAME SHA STATUS CREATED-DATE)
+  STATUS: :queued | :failed | :succeeded | :no-candle-file | :in-progress
+
+ARGUMENTS AND VALUES:
+
+  NAME: a string, the project for which we want information
+  BRANCH-NAME: a string, the name of the branch
+  JOB-PROJECT-NAME: a string, the project name for the attached job
+  SHA: a string, the sha for this job
+  CREATED-DATE: a universal time, the moment the job was first created
+
+DESCRIPTION:
+
+  Returns the information for all the branches in the given project,
+  which includes the job information for the commit that the branch
+  is currently pointing to."
  (let
   ((project (find-project-by-name-or-die name)))
   (mapcar
@@ -122,6 +200,22 @@
    (remove-if-not #'branch-in-git (find-branch-by-project project)))))
 
 (defun project-job-information (name)
+ "PROJECT-JOB-INFORMATION NAME => JOBS-INFORMATION
+
+  JOBS-INFORMATION: JOB-INFORMATION*
+  JOB-INFORMATION: (JOB-PROJECT-NAME SHA STATUS CREATED-DATE)
+  STATUS: :queued | :failed | :succeeded | :no-candle-file | :in-progress
+
+ARGUMENTS AND VALUES:
+
+  NAME: a string, the project for which we want information
+  JOB-PROJECT-NAME: a string, the project name for the attached job
+  SHA: a string, the sha for this job
+  CREATED-DATE: a universal time, the moment the job was first created
+
+DESCRIPTION:
+
+  Returns the information for all the jobs in the given project."
  (let
   ((project (find-project-by-name-or-die name)))
   (mapcar #'job->job-information
@@ -143,13 +237,56 @@
   job))
 
 (defun get-job-log (project-name sha)
+ "GET-JOB-LOG PROJECT-NAME SHA => LOG
+
+ARGUMENTS AND VALUES:
+
+  PROJECT-NAME: a string, representing the name of the project
+  SHA: a string, the commit sha for the job
+  LOG: the log from the run process
+
+DESCRIPTION:
+
+  Returns the log for the job specified.  When the job wasn't run
+  (for instance, if no candle file), just returns NIL.  The SHA
+  can be truncated, and if there are collisions, one of them will be
+  returned."
  (job-log (find-job-by-project-and-sha project-name sha)))
 
 (defun retry-job (project-name sha)
+ "RETRY-JOB PROJECT-NAME SHA => UNUSED
+
+ARGUMENTS AND VALUES:
+
+  PROJECT-NAME: a string, representing the name of the project
+  SHA: a string, the commit sha for the job
+  UNUSED: the result is unused
+
+DESCRIPTION:
+
+  Sets the job specified by PROJECT-NAME and SHA to :queued, which will
+  then be run.  Also awakes the processor thread to process it immediately
+  if available."
  (set-job-status (find-job-by-project-and-sha project-name sha) :queued)
  (awaken-processor-thread))
 
 (defun list-projects ()
+ "LIST-PROJECTS => PROJECTS-INFORMATION
+
+  PROJECTS-INFORMATION: PROJECT-INFORMATION*
+  PROJECT-INFORMATION: (NAME SRC FAILURES)
+
+ARGUMENTS AND VALUES:
+
+  NAME: a string, representing the name of the project
+  SRC: the git origin remote location
+  FAILURES: the number of failing branches
+
+DESCRIPTION:
+
+  Returns the information for all the projects in the system, as
+  is needed by the cli.  Returns it as a list of lists, as specified
+  above."
  (mapcar
   (lambda (project)
    (list
@@ -158,7 +295,18 @@
     (failures (project-name project))))
   *all-project*))
 
-(defun failures (project-name)
+(defun failures (&optional project-name)
+ "FAILURES &optional NAME => NUM-FAILURES
+
+ARGUMENTS AND VALUES:
+
+  NAME: a string, representing the name of the project
+  NUM-FAILURES: the number of failures
+
+DESCRIPTION:
+
+  Returns the number of failing branches.  When NAME is specified,
+  the branches are limited to the project it refers to."
  (let
   ((project (find-project-by-name-or-die project-name)))
   (length