Various doc- and style-improvements.

Author: Stewori

src/org/python/core/PyBytecode.java

@@ -164,13 +164,13 @@ public PyObject __findattr_ex__(String name) {
 
     enum Why {
 
-        NOT, /* No error */
+        NOT,       /* No error */
         EXCEPTION, /* Exception occurred */
-        RERAISE, /* Exception re-raised by 'finally' */
-        RETURN, /* 'return' statement */
-        BREAK, /* 'break' statement */
-        CONTINUE, /* 'continue' statement */
-        YIELD    /* 'yield' operator */
+        RERAISE,   /* Exception re-raised by 'finally' */
+        RETURN,    /* 'return' statement */
+        BREAK,     /* 'break' statement */
+        CONTINUE,  /* 'continue' statement */
+        YIELD      /* 'yield' operator */
 
     };
 
@@ -1054,7 +1054,8 @@ protected PyObject interpret(PyFrame f, ThreadState ts) {
                         break;
 
                     case Opcode.WITH_CLEANUP: {
-                        /* TOP is the context.__exit__ bound method.
+                        /*
+                        TOP is the context.__exit__ bound method.
                         Below that are 1-3 values indicating how/why
                         we entered the finally clause:
                         - SECOND = None

src/org/python/core/PyObject.java

@@ -20,18 +20,22 @@
 
 /**
  * All objects known to the Jython runtime system are represented by an instance
- * of the class <code>PyObject</code> or one of its subclasses.
+ * of the class {@code PyObject} or one of its subclasses.
  */
 @ExposedType(name = "object", doc = BuiltinDocs.object_doc)
 public class PyObject implements Serializable {
 
     public static final PyType TYPE = PyType.fromClass(PyObject.class);
 
     /**
-     * This should have been suited at org.python.modules.gc, but that would cause
-     * a dependency cycle in the init-phases of gc.class and PyObject.class.
-     * Now this boolean mirrors the presence of the MONITOR_GLOBAL-flag of
-     * Jython's gc module.
+     * This should have been suited at {@link org.python.modules.gc},
+     * but that would cause a dependency cycle in the init-phases of
+     * {@code gc.class} and {@code PyObject.class}. Now this boolean
+     * mirrors the presence of the
+     * {@link org.python.modules.gc#MONITOR_GLOBAL}-flag in Jython's
+     * gc module.<br>
+     * <br>
+     * <b>Do not change manually.</b>
      */
     public static boolean gcMonitorGlobal = false;
 
@@ -45,12 +49,15 @@ public class PyObject implements Serializable {
      * objects can be accessed by the methods and keys in
      * {@link org.python.core.JyAttribute}.
      * A notable attribute is the javaProxy (accessible via
-     * {@code JyAttribute.getAttr(this, JAVA_PROXY_ATTR)}),
+     * {@code JyAttribute.getAttr(this, JyAttribute.JAVA_PROXY_ATTR)}),
      * an underlying Java instance that this object is wrapping or is a
      * subclass of. Anything attempting to use the proxy should go through
      * {@link #getJavaProxy()} which ensures that it's initialized.
+     *
+     * @see org.python.core.JyAttribute
+     * @see org.python.core.JyAttribute#JAVA_PROXY_ATTR
+     * @see #getJavaProxy()
      */
-    //protected Object javaProxy;
     protected Object attributes;
 
     /** Primitives classes their wrapper classes. */
@@ -1708,7 +1715,6 @@ public final PyObject _gt(PyObject o) {
     public PyObject _is(PyObject o) {
         // Access javaProxy directly here as is is for object identity, and at best getJavaProxy
         // will initialize a new object with a different identity
-        //return this == o || (javaProxy != null && javaProxy == o.javaProxy) ? Py.True : Py.False;
         return this == o || (JyAttribute.hasAttr(this, JyAttribute.JAVA_PROXY_ATTR) &&
             JyAttribute.getAttr(this, JyAttribute.JAVA_PROXY_ATTR) ==
             JyAttribute.getAttr(o, JyAttribute.JAVA_PROXY_ATTR)) ? Py.True : Py.False;
@@ -1723,7 +1729,6 @@ public PyObject _is(PyObject o) {
     public PyObject _isnot(PyObject o) {
         // Access javaProxy directly here as is is for object identity, and at best getJavaProxy
         // will initialize a new object with a different identity
-        //return this != o && (javaProxy == null || javaProxy != o.javaProxy) ? Py.True : Py.False;
         return this != o && (!JyAttribute.hasAttr(this, JyAttribute.JAVA_PROXY_ATTR) ||
                 JyAttribute.getAttr(this, JyAttribute.JAVA_PROXY_ATTR) !=
                 JyAttribute.getAttr(o, JyAttribute.JAVA_PROXY_ATTR)) ? Py.True : Py.False;

src/org/python/core/Traverseproc.java

@@ -20,8 +20,7 @@
  * tracefunc in {@link org.python.core.PyFrame}).
  * PyObjects that don't own references to other PyObjects under any condition
  * and neither inherit such references from a superclass are strictly recommended
- * to be annotated {@code {@literal @}Untraversable}
- * (see {@link org.python.core.Untraversable} for details).
+ * to be annotated {@link org.python.core.Untraversable}.
  * </p>
  * <p>
  * Jython's traverse mechanism serves debugging purposes to ease finding memory
@@ -42,14 +41,16 @@
  * Note that the slots-array and - if existent - the user-dict of fooDerived classes
  * is traversed by {@link org.python.core.TraverseProcDerived}.
  * The gc module takes care of exploiting both traverse methods in its static traverse
- * method. So for manual traversion one should always use {@code gc.traverse} rather
+ * method. So for manual traversion one should always use
+ * {@link org.python.modules.gc#traverse(PyObject, Visitproc, Object)} rather
  * than directly calling methods in this interface.
  * </p>
  * <p>
- * Also note that {@code objtype} is not subject to {@code Traverseproc}s
- * by default. In CPython only objects with heap-types traverse their
- * ob_type field. In Jython, {@code fooDerived}-classes are the
- * equivalents of heapTypes. For such classes, objtype is actually
+ * Also note that {@link org.python.core.PyObject#objtype} is not subject to
+ * {@code Traverseproc}s by default. In CPython only objects with heap-types
+ * traverse their {@code ob_type}-field. In Jython, {@code fooDerived}-classes
+ * are the equivalents of heapTypes. For such classes
+ * {@link org.python.core.PyObject#objtype} is actually
  * traversed (along with the user dict).
  * </p>
  * <p>
@@ -439,6 +440,9 @@
  *   UAdd                          - no refs, extends PythonTree<br>
  *   USub                          - no refs, extends PythonTree<br>
  * </p>
+ * @see org.python.core.Untraversable
+ * @see org.python.core.Visitproc
+ * @see org.python.modules.gc#traverse(PyObject, Visitproc, Object)
  */
 public interface Traverseproc {
 

src/org/python/core/TraverseprocDerived.java

@@ -6,7 +6,7 @@
  * {@code fooDerived}-classes. This way we avoid that the traverse
  * method of a traversable {@link org.python.core.PyObject} is
  * overwritten by the derived version.
- * The {@link org.python.modules.gc}-module takes care of
+ * {@link org.python.modules.gc#traverse(PyObject, Visitproc, Object)} takes care of
  * exploiting both traverse methods.
  */
 public interface TraverseprocDerived {

src/org/python/core/finalization/FinalizeTrigger.java

@@ -12,35 +12,15 @@
 public class FinalizeTrigger {
     /**
      * This flag tells the finalize trigger to call
-     * gc.notifyFinalize after it called the finalizer.
+     * {@link gc#notifyFinalize(PyObject)} after it called the finalizer.
      */
     public static final byte NOTIFY_GC_FLAG =           (1<<0);
-    
-    /**
-     * This flag tells the finalize trigger to refrain from actually
-     * running the PyObject's {@code __del__} method (or variants for
-     * derived or builtins).
-     * It can be used to have finalize triggers for debugging and
-     * monitoring purposes. The actual purpose is for Jython gc's
-     * {@code DONT_FINALIZE_CYCLIC_GARBAGE} flag that tells the gc to emulate
-     * CPython's <3.4 policy never to finalize cyclic garbage.
-     */
-    //public static final byte INHIBIT_FINALIZER_FLAG =   (1<<1);
-    
-    /**
-     * Tells the finalizer to add the finalized PyObject to the gc's
-     * garbage list. This allows gc to mimic CPython's way to deal
-     * with cyclic finalizable objects prior 3.4
-     * (c.f. CPython's gc's DEBUG_SAVEALL flag).
-     */
-    //public static final byte ADD_TO_GARBAGE_LIST_FLAG = (1<<2);
 
     /**
-     * Similar to {@code INHIBIT_FINALIZER_FLAG}, but indicates that the
-     * underlying PyObject was never intended to be finalized, while
-     * {@code INHIBIT_FINALIZER_FLAG} indicates that there actually *is* a
-     * finalizer that is just not processed due to special
-     * circumstances (i.e. inactive {@code DONT_FINALIZE_CYCLIC_GARBAGE} flag).
+     * Indicates that the underlying PyObject was never intended to be finalized.
+     * It is actually not finalizable and the trigger only exists to notify
+     * {@link org.python.modules.gc} that the underlying object was finalized.
+     * This is needed for some advanced gc-functionality.
      */
     public static final byte NOT_FINALIZABLE_FLAG = (1<<3);
 
@@ -186,7 +166,7 @@ public void performFinalization() {
             	}
             }
             if ((gc.getJythonGCFlags() & gc.VERBOSE_FINALIZE) != 0) {
-        		Py.writeDebug("gc", "finalization of "+toFinalize);
+        		gc.writeDebug("gc", "finalization of "+toFinalize);
         	}
             if (saveGarbage == 1 || (saveGarbage == 0 &&
                     (gc.get_debug() & gc.DEBUG_SAVEALL) != 0 && isCyclic())) {
@@ -199,13 +179,13 @@ public void performFinalization() {
                 }
                 gc.garbage.add(toFinalize);
                 if ((gc.getJythonGCFlags() & gc.VERBOSE_FINALIZE) != 0) {
-                	Py.writeDebug("gc", toFinalize+" added to garbage.");
+                	gc.writeDebug("gc", toFinalize+" added to garbage.");
             	}
             }
         }
         if ((flags & NOTIFY_GC_FLAG) != 0) {
         	if ((gc.getJythonGCFlags() & gc.VERBOSE_FINALIZE) != 0) {
-        		Py.writeDebug("gc", "notify finalization of "+toFinalize);
+        		gc.writeDebug("gc", "notify finalization of "+toFinalize);
         	}
             gc.notifyFinalize(toFinalize);
             flags &= ~NOTIFY_GC_FLAG;
@@ -217,7 +197,7 @@ protected void finalize() throws Throwable {
         gc.notifyPreFinalization();
         if (gc.delayedFinalizationEnabled() && toFinalize != null) {
         	if ((gc.getJythonGCFlags() & gc.VERBOSE_FINALIZE) != 0) {
-        		Py.writeDebug("gc", "delayed finalization for "+toFinalize);
+        		gc.writeDebug("gc", "delayed finalization for "+toFinalize);
         	}
             gc.registerForDelayedFinalization(toFinalize);
         } else {

src/org/python/modules/_weakref/AbstractReference.java

@@ -84,7 +84,7 @@ protected PyObject get() {
                 return null;
             }
             if ((gc.getJythonGCFlags() & gc.VERBOSE_WEAKREF) != 0) {
-                Py.writeDebug("gc", "pending in get of abstract ref "+this+": "+
+                gc.writeDebug("gc", "pending in get of abstract ref "+this+": "+
                         Thread.currentThread().getId());
             }
             JyAttribute.setAttr(this, JyAttribute.WEAKREF_PENDING_GET_ATTR, Thread.currentThread());
@@ -96,14 +96,14 @@ protected PyObject get() {
             }
             JyAttribute.delAttr(this, JyAttribute.WEAKREF_PENDING_GET_ATTR);
             if ((gc.getJythonGCFlags() & gc.VERBOSE_WEAKREF) != 0) {
-                Py.writeDebug("gc", "pending of "+this+" resolved: "+
+                gc.writeDebug("gc", "pending of "+this+" resolved: "+
                         Thread.currentThread().getId());
                 if (gref.cleared) {
-                    Py.writeDebug("gc", "reference was cleared.");
+                    gc.writeDebug("gc", "reference was cleared.");
                 } else if (result != null){
-                    Py.writeDebug("gc", "reference was restored.");
+                    gc.writeDebug("gc", "reference was restored.");
                 } else {
-                    Py.writeDebug("gc", "something went very wrong.");
+                    gc.writeDebug("gc", "something went very wrong.");
                 }
             }
             return result;

src/org/python/modules/_weakref/GlobalRef.java

@@ -20,8 +20,8 @@
 public class GlobalRef extends WeakReference<PyObject> {
 
     /**
-     * This reference's hashCode: the System.identityHashCode of the referent. Only used
-     * internally.
+     * This reference's hashCode: The {@code System.identityHashCode} of the referent.
+     * Only used internally.
      */
     private int hashCode;
 
@@ -31,16 +31,19 @@ public class GlobalRef extends WeakReference<PyObject> {
      */
     private int pythonHashCode;
 
-    /** Whether pythonHashCode was already determined. */
+    /** Whether {@link #pythonHashCode} was already determined. */
     private boolean havePythonHashCode;
 
     /**
-     * This boolean is set true when the callback is processed. If the reference is
-     * cleared it might potentially be restored until this boolean is set true.
-     * If weak reference restoring is activated (c.f.
-     * {@code gc.PRESERVE_WEAKREFS_ON_RESURRECTION}), {@code AbstractReference.get}
+     * This boolean is set {@code true} when the callback is processed.
+     * If the reference is cleared it might potentially be restored until
+     * this boolean is set true. If weak reference restoring is activated (c.f.
+     * {@link gc#PRESERVE_WEAKREFS_ON_RESURRECTION}), {@link AbstractReference#get()}
      * would block until a consistent state is reached (i.e. referent is
      * non-{@code null} or {@code cleared == true}).
+     *
+     * @see gc#PRESERVE_WEAKREFS_ON_RESURRECTION
+     * @see AbstractReference#get()
      */
     protected boolean cleared = false;
 
@@ -108,7 +111,10 @@ synchronized void call() {
     }
 
     /**
-     * Call all callbacks that were enqueued via delayedCallback method.
+     * Call all callbacks that were enqueued via
+     * {@link #delayedCallback(GlobalRef)} method.
+     *
+     * @see #delayedCallback(GlobalRef)
      */
     public static void processDelayedCallbacks() {
         if (delayedCallbacks != null) {
@@ -124,9 +130,11 @@ public static void processDelayedCallbacks() {
     /**
      * Stores the callback for later processing. This is needed if
      * weak reference restoration (c.f.
-     * {@code gc.PRESERVE_WEAKREFS_ON_RESURRECTION})
+     * {@link gc#PRESERVE_WEAKREFS_ON_RESURRECTION})
      * is active. In this case the callback is delayed until it was
      * determined whether a resurrection restored the reference.
+     *
+     * @see gc#PRESERVE_WEAKREFS_ON_RESURRECTION
      */
     private static void delayedCallback(GlobalRef cl) {
         if (delayedCallbacks == null) {
@@ -196,6 +204,9 @@ public static GlobalRef newInstance(PyObject object) {
      * If the given {@link org.python.core.PyObject} is not the former
      * referent of this weak reference, an
      * {@link java.lang.IllegalArgumentException} is thrown.
+     *
+     * @throws java.lang.IllegalArgumentException if {@code formerReferent} is not
+     * the actual former referent.
      */
     public void restore(PyObject formerReferent) {
         if (JyAttribute.getAttr(formerReferent, JyAttribute.WEAK_REF_ATTR) != this) {
@@ -265,8 +276,8 @@ public static int getCount(PyObject object) {
      * Return a list of references to the specified
      * {@link org.python.core.PyObject}.
      *
-     * @param object a PyObject
-     * @return a PyList of references. may be empty
+     * @param object a {@link org.python.core.PyObject}
+     * @return a {@link org.python.core.PyList} of references. May be empty.
      */
     public static PyList getRefs(PyObject object) {
         GlobalRef ref = objects.get(new GlobalRef(object));

src/org/python/modules/_weakref/ReferenceType.java

@@ -68,9 +68,9 @@ final void weakref___init__(PyObject[] args, String[] keywords) {
      * to passthru).
      *
      * @param funcName the name of the caller
-     * @param args PyObject array of args
-     * @param keywords String array of keywords
-     * @return an ArgParser instance
+     * @param args {@link or.python.core.PyObject} array of args
+     * @param keywords {@code String}-array of keywords
+     * @return an {@link or.python.core.ArgParser} instance
      */
     private static ArgParser parseInitArgs(String funcName, PyObject[] args, String[] keywords) {
         if (keywords.length > 0) {