[armedbear-cvs] r12030 - trunk/abcl/src/org/armedbear/lisp

[Erik Huelsmann]

Author: ehuelsmann
Date: Sat Jul  4 17:27:12 2009
New Revision: 12030

Log:
Add documentation on different symbol value lookup functions.

Modified:
   trunk/abcl/src/org/armedbear/lisp/LispThread.java
   trunk/abcl/src/org/armedbear/lisp/Symbol.java

Modified: trunk/abcl/src/org/armedbear/lisp/LispThread.java
==============================================================================
--- trunk/abcl/src/org/armedbear/lisp/LispThread.java	(original)
+++ trunk/abcl/src/org/armedbear/lisp/LispThread.java	Sat Jul  4 17:27:12 2009
@@ -332,6 +332,17 @@
             new SpecialBinding(name, name.getSymbolValue(), lastSpecialBinding);
     }
 
+    /** 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)
     {
         SpecialBinding binding = lastSpecialBinding;

Modified: trunk/abcl/src/org/armedbear/lisp/Symbol.java
==============================================================================
--- trunk/abcl/src/org/armedbear/lisp/Symbol.java	(original)
+++ trunk/abcl/src/org/armedbear/lisp/Symbol.java	Sat Jul  4 17:27:12 2009
@@ -283,28 +283,60 @@
       }
   }
 
-  // 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()
   {
     return value;
   }
 
+  /** 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)
   {
     this.value = value;
   }
 
+  /** 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
   {
     LispObject val = thread.lookupSpecial(this);
@@ -315,17 +347,33 @@
     return error(new UnboundVariable(this));
   }
 
+  /** 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)
   {
     if ((flags & FLAG_SPECIAL) != 0)