From a50fef6f3bacc24a838e81092104f3082b15bad4 Mon Sep 17 00:00:00 2001 From: Frank Duncan Date: Sat, 18 Dec 2021 16:18:37 -0600 Subject: [PATCH] Add documentation for all the exported symbols --- src/main/base.lisp | 69 +++++++++++++++++- src/main/package.lisp | 7 +- src/main/processor.lisp | 53 +++++++++++++- src/main/run.lisp | 10 +++ src/main/server.lisp | 150 +++++++++++++++++++++++++++++++++++++++- 5 files changed, 282 insertions(+), 7 deletions(-) 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 -- 2.25.1