low: Add missing docstrings.

1 files changed, 36 insertions, 0 deletions

diff --git a/drmaa/v1/low.scm b/drmaa/v1/low.scm
index ca2b8d7..d1b9b9d 100644
--- a/drmaa/v1/low.scm
+++ b/drmaa/v1/low.scm
@@ -108,6 +108,8 @@ STRING-LIST."
                       (char*->string error-message)))))))))
 
 (define (DRMAA sym)
+  "Return the DRMAA value corresponding to SYM as defined in the DRMAA
+headers."
   (or (drmaa-v1-ffi-symbol-val (symbol-append 'DRMAA_ sym))
       (raise (condition
               (&message
@@ -118,6 +120,8 @@ STRING-LIST."
 ;;; String vector helpers
 
 (define (get-next-attr-name! names)
+  "Return the next attribute name from the opaque list of attribute
+NAMES."
   (let* ((name
           (make-char* (bytevector->pointer
                        (make-bytevector (DRMAA 'ATTR_BUFFER)))))
@@ -128,6 +132,8 @@ STRING-LIST."
          (char*->string name))))
 
 (define (get-next-attr-value! values)
+  "Return the next attribute value from the opaque list of attribute
+VALUES."
   (let* ((value
           (make-char* (bytevector->pointer
                        (make-bytevector (DRMAA 'ATTR_BUFFER)))))
@@ -138,6 +144,8 @@ STRING-LIST."
          (char*->string value))))
 
 (define (get-next-job-id! values)
+  "Return the next job identifier from the opaque list of job name
+VALUES."
   (let* ((value
           (make-char* (bytevector->pointer
                        ;; TODO: Perhaps not correct to use JOBNAME_BUFFER here
@@ -150,6 +158,7 @@ STRING-LIST."
          (char*->string value))))
 
 (define (get-num-attr-names values)
+  "Return the number of attribute names in the opaque list VALUES."
   (let* ((size (make-size_t))
          (ret (drmaa_get_num_attr_names
                values (pointer-to size))))
@@ -157,6 +166,7 @@ STRING-LIST."
          (fh-object-ref size))))
 
 (define (get-num-attr-values values)
+  "Return the number of attribute values in the opaque list VALUES."
   (let* ((size (make-size_t))
          (ret (drmaa_get_num_attr_values
                values (pointer-to size))))
@@ -164,6 +174,7 @@ STRING-LIST."
          (fh-object-ref size))))
 
 (define (get-num-job-ids values)
+  "Return the number of job identifiers in the opaque list VALUES."
   (let* ((size (make-size_t))
          (ret (drmaa_get_num_job_ids
                values (pointer-to size))))
@@ -171,14 +182,20 @@ STRING-LIST."
          (fh-object-ref size))))
 
 (define (release-attr-names! values)
+  "Tell the DRMAA library that the attribute names in VALUES can be
+destroyed."
   (drmaa_release_attr_names values)
   #true)
 
 (define (release-attr-values! values)
+  "Tell the DRMAA library that the attribute values in VALUES can be
+destroyed."
   (drmaa_release_attr_values values)
   #true)
 
 (define (release-job-ids! values)
+  "Tell the DRMAA library that the job identifiers in VALUES can be
+destroyed."
   (drmaa_release_job_ids values)
   #true)
 
@@ -241,6 +258,8 @@ not be affected by this."
 ;;; Job templates
 
 (define (allocate-job-template!)
+  "Allocate a job template and return the opaque template value.
+Remember to call DELETE-JOB-TEMPLATE! to destroy it."
   (let ((template (make-drmaa_job_template_t*))
         (error-message
          (make-char* (bytevector->pointer
@@ -252,6 +271,8 @@ not be affected by this."
             error-message)))
 
 (define (delete-job-template! template)
+  "Destroy the job TEMPLATE that has previously been created with
+ALLOCATE-JOB-TEMPLATE!."
   ;; TODO: Call this in a finalizer.
   (let ((error-message
          (make-char* (bytevector->pointer
@@ -263,6 +284,7 @@ not be affected by this."
             error-message)))
 
 (define (set-attribute! template name value)
+  "Modify TEMPLATE by setting its attribute NAME to VALUE."
   (let ((valid (get-attribute-names)))
     (unless (member name valid)
       (raise (condition
@@ -280,6 +302,7 @@ not be affected by this."
               error-message))))
 
 (define (get-attribute template name)
+  "Return the TEMPLATE value's attribute identified by NAME."
   (let ((error-message
          (make-char* (bytevector->pointer
                       (make-bytevector (DRMAA 'ERROR_STRING_BUFFER)))))
@@ -296,6 +319,8 @@ not be affected by this."
             error-message)))
 
 (define (set-vector-attribute! template name . values)
+  "Modify the TEMPLATE by setting its vector attribute identified by
+NAME to the provided VALUES."
   (let ((valid (get-vector-attribute-names)))
     (unless (member name valid)
       (raise (condition
@@ -315,6 +340,8 @@ not be affected by this."
               error-message))))
 
 (define (get-vector-attribute template name)
+  "Return the list of values stored for the TEMPLATE value's vector
+attribute identified by NAME."
   (let ((error-message
          (make-char* (bytevector->pointer
                       (make-bytevector (DRMAA 'ERROR_STRING_BUFFER)))))
@@ -328,6 +355,7 @@ not be affected by this."
             error-message)))
 
 (define (get-attribute-names)
+  "Return the list of names of all singular attributes."
   (let ((error-message
          (make-char* (bytevector->pointer
                       (make-bytevector (DRMAA 'ERROR_STRING_BUFFER)))))
@@ -339,6 +367,7 @@ not be affected by this."
             error-message)))
 
 (define (get-vector-attribute-names)
+  "Return the list of names of all vector attributes."
   (let ((error-message
          (make-char* (bytevector->pointer
                       (make-bytevector (DRMAA 'ERROR_STRING_BUFFER)))))
@@ -463,6 +492,11 @@ the current session will be affected."
               (format #false "Unexpected status: ~a" status-code))))))))
 
 (define (job-ps job-id)
+  "Return a symbol corresponding to the current status of the job
+identified by JOB-ID (a string).  The return value is one of the
+following symbols: FAILED, DONE, USER-SYSTEM-SUSPENDED,
+USER-SUSPENDED, RUNNING, USER-SYSTEM-ON-HOLD, USER-ON-HOLD,
+QUEUED-ACTIVE, UNDETERMINED."
   (let ((error-message
          (make-char* (bytevector->pointer
                       (make-bytevector (DRMAA 'ERROR_STRING_BUFFER)))))
@@ -543,6 +577,7 @@ alist of resource usage statistics."
             error-message)))
 
 (define (w-if-exited? status-code)
+  "Return #TRUE if the STATUS-CODE indicates that the job has exited."
   (let ((exited (make-uint8))
         (error-message
          (make-char* (bytevector->pointer
@@ -555,6 +590,7 @@ alist of resource usage statistics."
             error-message)))
 
 (define (w-exit-status status-code)
+  "Return the numeric value of STATUS-CODE."
   (let ((exit-status (make-uint8))
         (error-message
          (make-char* (bytevector->pointer