Changeset 12030

Timestamp:

07/04/09 21:27:12 (14 years ago)

Author:

ehuelsmann

Message:

Add documentation on different symbol value lookup functions.

Location:

trunk/abcl/src/org/armedbear/lisp

Files:

• LispThread.java (modified) (1 diff)
• Symbol.java (modified) (4 diffs)

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

@@ -333 +333 @@
     }
 
+    /** Looks up the value of a special binding in the context of the
+     * given thread.
+     *
+     * In order to find the value of a special variable (in general),
+     * use {@link Symbol#symbolValue}.
+     *
+     * @param name The name of the special variable, normally a symbol
+     * @return The inner most binding of the special, or null if unbound
+     *
+     * @see Symbol#symbolValue
+     */
     public final LispObject lookupSpecial(LispObject name)
     {

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

@@ -284 +284 @@
   }
 
-  // Raw accessor.
+  /** Gets the value associated with the symbol
+   * as set by SYMBOL-VALUE.
+   *
+   * @return The associated value, or null if unbound.
+   *
+   * @see Symbol#symbolValue
+   */
   @Override
   public LispObject getSymbolValue()
@@ -291 +297 @@
   }
 
+  /** Sets the value associated with the symbol
+   * as if set by SYMBOL-VALUE.
+   *
+   * @return The associated value, or null if unbound.
+   *
+   * @see Symbol#symbolValue
+   */
   public final void setSymbolValue(LispObject value)
   {
@@ -296 +309 @@
   }
 
+  /** Returns the value associated with this symbol in the current
+   * thread context when it is treated as a special variable.
+   *
+   * A lisp error is thrown if the symbol is unbound.
+   *
+   * @return The associated value
+   * @throws org.armedbear.lisp.ConditionThrowable
+   *
+   * @see LispThread#lookupSpecial
+   * @see Symbol#getSymbolValue()
+   *
+   */
   public final LispObject symbolValue() throws ConditionThrowable
   {
-    LispObject val = LispThread.currentThread().lookupSpecial(this);
-    if (val != null)
-      return val;
-    if (value != null)
-      return value;
-    return error(new UnboundVariable(this));
-  }
-
+    return symbolValue(LispThread.currentThread());
+  }
+
+  /** Returns the value associated with this symbol in the specified
+   * thread context when it is treated as a special variable.
+   *
+   * A lisp error is thrown if the symbol is unbound.
+   *
+   * @return The associated value
+   * @throws org.armedbear.lisp.ConditionThrowable
+   *
+   * @see LispThread#lookupSpecial
+   * @see Symbol#getSymbolValue()
+   *
+   */
   public final LispObject symbolValue(LispThread thread) throws ConditionThrowable
   {
@@ -316 +348 @@
   }
 
+  /** Returns the value of the symbol in the current thread context;
+   * if the symbol has been declared special, the value of the innermost
+   * binding is returned. Otherwise, the SYMBOL-VALUE is returned, or
+   * null if unbound.
+   *
+   * @return A lisp object, or null if unbound
+   *
+   * @see LispThread#lookupSpecial
+   * @see Symbol#getSymbolValue()
+   *
+   */
   public final LispObject symbolValueNoThrow()
   {
-    if ((flags & FLAG_SPECIAL) != 0)
-      {
-        LispObject val = LispThread.currentThread().lookupSpecial(this);
-        if (val != null)
-          return val;
-      }
-    return value;
-  }
-
+    return symbolValueNoThrow(LispThread.currentThread());
+  }
+
+  /** Returns the value of the symbol in the current thread context;
+   * if the symbol has been declared special, the value of the innermost
+   * binding is returned. Otherwise, the SYMBOL-VALUE is returned, or
+   * null if unbound.
+   *
+   * @return A lisp object, or null if unbound
+   *
+   * @see LispThread#lookupSpecial
+   * @see Symbol#getSymbolValue()
+   *
+   */
   public final LispObject symbolValueNoThrow(LispThread thread)
   {