Changeset 15436

Timestamp:

10/29/20 16:54:29 (3 years ago)

Author:

Mark Evenson

Message:

Add some docstrings

Location:

trunk/abcl/src/org/armedbear/lisp

Files:

• LispThread.java (modified) (5 diffs)
• aver.lisp (modified) (1 diff)
• threads.lisp (modified) (5 diffs)

trunk/abcl/src/org/armedbear/lisp/LispThread.java

@@ -1138 +1138 @@
     }
 
-    @DocString(name="make-thread", args="function &key name")
+    @DocString(name="make-thread",
+               args="function &key name",
+               doc="Create a thread of execution running FUNCTION possibly named NAME")
     private static final Primitive MAKE_THREAD =
         new Primitive("make-thread", PACKAGE_THREADS, true, "function &key name")
@@ -1164 +1166 @@
     };
 
-    @DocString(name="threadp", args="object",
-    doc="Boolean predicate testing if OBJECT is a thread.")
+    @DocString(name="threadp",
+               args="object",
+               doc="Boolean predicate returning non-nil if OBJECT is a lisp thread")
     private static final Primitive THREADP =
         new Primitive("threadp", PACKAGE_THREADS, true)
@@ -1176 +1179 @@
     };
 
-    @DocString(name="thread-alive-p", args="thread",
-    doc="Returns T if THREAD is alive.")
+    @DocString(name="thread-alive-p",
+               args="thread",
+               doc="Returns T if THREAD is alive.")
     private static final Primitive THREAD_ALIVE_P =
-        new Primitive("thread-alive-p", PACKAGE_THREADS, true, "thread",
-              "Boolean predicate whether THREAD is alive.")
+      new Primitive("thread-alive-p", PACKAGE_THREADS, true, "thread",
+                    "Boolean predicate whether THREAD is alive.")
     {
         @Override
@@ -1196 +1200 @@
     };
 
-    @DocString(name="thread-name", args="thread",
-    doc="Return the name of THREAD, if it has one.")
+    @DocString(name="thread-name",
+               args="thread",
+               doc="Return the name of THREAD, if it has one.")
     private static final Primitive THREAD_NAME =
         new Primitive("thread-name", PACKAGE_THREADS, true)
@@ -1212 +1217 @@
 
     private static final Primitive THREAD_JOIN =
-        new Primitive("thread-join", PACKAGE_THREADS, true, "thread",
-                      "Waits for thread to finish.")
+      new Primitive("thread-join", PACKAGE_THREADS, true, "thread",
+                    "Waits for THREAD to die before resuming execution\n"
+                    + "Returns the result of the joined thread as its primary value.\n"
+                    + "Returns T if the joined thread finishes normally or NIL if it was interrupted.")
     {
         @Override
         public LispObject execute(LispObject arg)
         {
-            // join the thread, and returns it's value.  The second return
+            // join the thread, and returns its value.  The second return
             // value is T if the thread finishes normally, NIL if its 
             // interrupted. 

trunk/abcl/src/org/armedbear/lisp/aver.lisp

@@ -42 +42 @@
 
 (defmacro aver (expr)
+  "Signal simple-error when EXPR is non-NIL."
   `(unless ,expr
      (%failed-aver ,(format nil "~A" expr))))

trunk/abcl/src/org/armedbear/lisp/threads.lisp

@@ -55 +55 @@
 
 (defstruct mailbox
+  "A first-in-first out queue of messages"
   queue)
 
@@ -103 +104 @@
 
 (defstruct mutex
+  "An object used as a mutex lock"
   in-use)
 
 (defun get-mutex (mutex)
-  "Acquires a lock on the `mutex'."
+  "Acquires the lock associated with the MUTEX"
   (synchronized-on mutex
     (loop
@@ -114 +116 @@
 
 (defun release-mutex (mutex)
-  "Releases a lock on the `mutex'."
+  "Releases a lock associated with MUTEX"
   (synchronized-on mutex
     (setf (mutex-in-use mutex) NIL)
@@ -120 +122 @@
 
 (defmacro with-mutex ((mutex) &body body)
-  "Acquires a lock on `mutex', executes the body
-and releases the lock."
+  "Acquires a lock on MUTEX, executes BODY, and then releases the lock"
   (let ((m (gensym)))
     `(let ((,m ,mutex))
@@ -136 +137 @@
 
 (defun make-thread-lock ()
-  "Returns an object to be used with the `with-thread-lock' macro."
+  "Returns an object to be used with the WITH-THREAD-LOCK macro."
   (gensym))
 
 (defmacro with-thread-lock ((lock) &body body)
-  "Acquires a lock on the `lock', executes `body' and releases the lock."
+  "Acquires the LOCK, executes BODY and releases the LOCK"
   (let ((glock (gensym)))
     `(let ((,glock ,lock))