[Jython-checkins] jython: Fix all present irregularities in the javadoc
jeff.allen
jython-checkins at python.org
Sun Aug 12 02:08:45 EDT 2018
https://hg.python.org/jython/rev/134c5c8c2332
changeset: 8179:134c5c8c2332
user: Jeff Allen <ja.py at farowl.co.uk>
date: Sat Aug 11 23:16:19 2018 +0100
summary:
Fix all present irregularities in the javadoc
It seems Gradle will not publish defective javadoc, so it has to be correct.
Most problems were due to imaginative choice of argument in @see and @link tags.
No code changes except that the solution was sometimes to add an import
statement for something referred to in documentation. The editor imposes a few
coding rules on save (trailing space, @Override, parentheses) but I have not
reformatted much, even code sorely divergent from our standard.
files:
build.gradle | 30 +-
src/com/ziclix/python/sql/connect/Connectx.java | 11 +-
src/com/ziclix/python/sql/handler/RowIdHandler.java | 5 +-
src/com/ziclix/python/sql/pipe/csv/CSVString.java | 19 +-
src/com/ziclix/python/sql/zxJDBC.java | 1 -
src/org/python/antlr/Visitor.java | 4 +-
src/org/python/compiler/LineNumberTable.java | 3 +-
src/org/python/compiler/ProxyMaker.java | 64 ++--
src/org/python/core/BaseBytes.java | 22 +-
src/org/python/core/BytecodeNotification.java | 22 +-
src/org/python/core/JyAttribute.java | 27 +-
src/org/python/core/Py.java | 122 ++++-----
src/org/python/core/PyBUF.java | 4 +-
src/org/python/core/PyModule.java | 32 +-
src/org/python/core/PyObject.java | 9 +-
src/org/python/core/PyString.java | 6 +-
src/org/python/core/PyUnicode.java | 2 +-
src/org/python/core/Traverseproc.java | 6 +-
src/org/python/core/buffer/BaseBuffer.java | 12 +-
src/org/python/core/buffer/SimpleStringBuffer.java | 2 +-
src/org/python/core/buffer/Strided1DBuffer.java | 3 +-
src/org/python/core/buffer/Strided1DNIOBuffer.java | 3 +-
src/org/python/core/codecs.java | 32 +-
src/org/python/core/stringlib/InternalFormat.java | 2 +-
src/org/python/core/stringlib/MarkupIterator.java | 2 +-
src/org/python/expose/generate/ExposedTypeVisitor.java | 6 +-
src/org/python/indexer/Indexer.java | 34 +-
src/org/python/indexer/IndexingException.java | 3 +-
src/org/python/indexer/NBinding.java | 18 +-
src/org/python/indexer/Outliner.java | 14 +-
src/org/python/indexer/Scope.java | 6 +-
src/org/python/indexer/ast/DefaultNodeVisitor.java | 56 ++++-
src/org/python/indexer/ast/NNode.java | 13 +-
src/org/python/indexer/types/NUnionType.java | 13 +-
src/org/python/modules/_io/PyIOBase.java | 2 +-
src/org/python/modules/cStringIO.java | 25 +-
src/org/python/modules/cmath.java | 12 +-
src/org/python/modules/gc.java | 99 ++++---
src/org/python/util/InteractiveConsole.java | 4 +-
src/org/python/util/PythonInterpreter.java | 8 +-
40 files changed, 427 insertions(+), 331 deletions(-)
diff --git a/build.gradle b/build.gradle
--- a/build.gradle
+++ b/build.gradle
@@ -101,7 +101,9 @@
java {
srcDirs = ['src', project.ext.antlrGenDir]
- exclude 'com/**' // for now
+ // Reference to proprietary libraries not supplied
+ exclude 'com/ziclix/python/sql/handler/InformixDataHandler.java'
+ exclude 'com/ziclix/python/sql/handler/OracleDataHandler.java'
}
resources {
@@ -116,22 +118,29 @@
java {
srcDirs = ['tests/java']
- exclude 'com/**' // XXX for now
+ // Reference to proprietary libraries not supplied
+ exclude 'com/ziclix/python/sql/**'
}
}
}
dependencies {
/*
- * These must correspond fairly exactly with the external libraries (JARs)
- * mentioned in the Ant build.xml.
+ * Must these correspond exactly with the external libraries (JARs)
+ * mentioned in the Ant build.xml, or is it better to allow "at least"
+ * matching of versions, to grant this freedom to user applications?
*/
// Using a version available from repo (not 'extlibs/servlet-api-2.5' as in build.xml)
implementation group: 'javax.servlet', name: 'javax.servlet-api', version: '3.1.0'
- // implementation 'mysql-connector-java-5.1.42-bin'
- // implementation 'postgresql-42.1.1.jre7'
+ /*
+ * These seem to be unnecessary while the proprietary database support is
+ * not bundled with Jython. Applications needing them can cite thse or a
+ * version they prefer.
+ */
+ //implementation group: 'mysql', name: 'mysql-connector-java', version: '5.1.42'
+ //implementation group: 'org.postgresql', name: 'postgresql', version: '42.1.1.jre7'
// pin to Antlr 3.1.3 until we upgrade parsing
antlr 'org.antlr:antlr:3.1.3' // use ANTLR version 3
@@ -601,7 +610,9 @@
'version': project.version,
'build-compiler': 'modern',
'jdk-target-version': project.targetCompatibility,
- 'debug': compileJava.options.debug
+ 'debug': compileJava.options.debug,
+ 'informix': false,
+ 'oracle': false
], 'Build-Info' )
}
}
@@ -682,7 +693,7 @@
// Also provide the source.
artifact sourcesJar
// Also provide the docs. (Some javadoc errors currently.)
- //artifact javadocJar
+ artifact javadocJar
}
}
@@ -735,8 +746,9 @@
// Place cache outside the targets for jar task
systemProperty 'python.cachedir', "${project.buildDir}/cachedir"
- // Include/exclude based on Ant target javatest-basepath
include '**/*Test*'
+
+ // Exclude based on Ant target javatest-basepath
exclude '**/InterpTestCase'
exclude '**/jythonTest*' // Must run interactively
exclude 'org/python/antlr/**'
diff --git a/src/com/ziclix/python/sql/connect/Connectx.java b/src/com/ziclix/python/sql/connect/Connectx.java
--- a/src/com/ziclix/python/sql/connect/Connectx.java
+++ b/src/com/ziclix/python/sql/connect/Connectx.java
@@ -113,11 +113,6 @@
return pc;
}
- /**
- * Method toString
- *
- * @return String
- */
@Override
public String toString() {
return String.format("<connectx object at %s>", Py.id(this));
@@ -126,9 +121,9 @@
/**
* Method invoke
*
- * @param Object src
- * @param String methodName
- * @param Object value
+ * @param src
+ * @param methodName
+ * @param value
*/
protected void invoke(Object src, String methodName, Object value) {
Method method = null;
diff --git a/src/com/ziclix/python/sql/handler/RowIdHandler.java b/src/com/ziclix/python/sql/handler/RowIdHandler.java
--- a/src/com/ziclix/python/sql/handler/RowIdHandler.java
+++ b/src/com/ziclix/python/sql/handler/RowIdHandler.java
@@ -37,7 +37,7 @@
* Return the name of the method that returns the last row id. The
* method can take no arguments but the return type is flexible and
* will be figured out by the Jython runtime system.
- * @return
+ * @return name of the method that returns the last row id
*/
protected abstract String getRowIdMethodName();
@@ -47,7 +47,8 @@
* @return an object representing the last row id
* @throws SQLException
*/
- public PyObject getRowId(Statement stmt) throws SQLException {
+ @Override
+public PyObject getRowId(Statement stmt) throws SQLException {
Class<?> c = stmt.getClass();
Object o = ROWIDS.get(c);
diff --git a/src/com/ziclix/python/sql/pipe/csv/CSVString.java b/src/com/ziclix/python/sql/pipe/csv/CSVString.java
--- a/src/com/ziclix/python/sql/pipe/csv/CSVString.java
+++ b/src/com/ziclix/python/sql/pipe/csv/CSVString.java
@@ -44,17 +44,16 @@
}
/**
- * Returns a new string resulting from replacing the first occurrence, or all occurrences,
- * of search string in this string with replace string.
- * If the string search does not occur in the character sequence represented by this object,
- * then this string is returned.
+ * Returns a new string resulting from replacing the first occurrence, or all occurrences, of
+ * search string in this string with replace string. If the string search does not occur in the
+ * character sequence represented by this object, then this string is returned.
*
- * @param search the old string
- * @param replace the new string
- * @param all=true all occurrences of the search string are replaced
- * @param all=false only the first occurrence of the search string is replaced
- * @return a string derived from this string by replacing the first occurrence,
- * or every occurrence of search with replace.
+ * @param search the old string
+ * @param replace the new string
+ * @param all if {@code true} all occurrences of the search string are replaced; if
+ * {@code false} only the first occurrence
+ * @return a string derived from this string by replacing the first occurrence, or every
+ * occurrence, of {@code search} with {@code replace}.
*/
public static String replace(String original, String search, String replace, boolean all) {
diff --git a/src/com/ziclix/python/sql/zxJDBC.java b/src/com/ziclix/python/sql/zxJDBC.java
--- a/src/com/ziclix/python/sql/zxJDBC.java
+++ b/src/com/ziclix/python/sql/zxJDBC.java
@@ -419,7 +419,6 @@
*
* @param classname
* @param superclass
- * @param classCodeName
* @return PyObject
*/
protected static PyObject buildClass(String classname, PyObject superclass) {
diff --git a/src/org/python/antlr/Visitor.java b/src/org/python/antlr/Visitor.java
--- a/src/org/python/antlr/Visitor.java
+++ b/src/org/python/antlr/Visitor.java
@@ -6,8 +6,9 @@
/**
* Visit each of the children one by one.
- * @args node The node whose children will be visited.
+ * @param node The node whose children will be visited.
*/
+ @Override
public void traverse(PythonTree node) throws Exception {
node.traverse(this);
}
@@ -27,6 +28,7 @@
return ret;
}
+ @Override
protected Object unhandled_node(PythonTree node) throws Exception {
return this;
}
diff --git a/src/org/python/compiler/LineNumberTable.java b/src/org/python/compiler/LineNumberTable.java
--- a/src/org/python/compiler/LineNumberTable.java
+++ b/src/org/python/compiler/LineNumberTable.java
@@ -7,8 +7,9 @@
import java.io.IOException;
/**
- * @Deprecated Not used. Delete in 2.6.
+ * @deprecated Not used. Delete in 2.6.
*/
+ at Deprecated
public class LineNumberTable {
int attName;
Vector<Short> lines;
diff --git a/src/org/python/compiler/ProxyMaker.java b/src/org/python/compiler/ProxyMaker.java
--- a/src/org/python/compiler/ProxyMaker.java
+++ b/src/org/python/compiler/ProxyMaker.java
@@ -16,7 +16,6 @@
import static org.python.util.CodegenUtils.p;
import static org.python.util.CodegenUtils.sig;
-
public class ProxyMaker extends ProxyCodeHelpers implements ClassConstants, Opcodes
{
protected final Class<?> superclass;
@@ -33,8 +32,7 @@
* <code>org.python.proxies.(superclassName)</code> with <code>superclass</code> as an
* implemented interface or extended class, depending on the its type.
*
- * @deprecated - Use {@link ProxyMaker#ProxyMaker(String, Class, Class[])
-
+ * @deprecated - Use {@link ProxyMaker#ProxyMaker(String, Class, Class[])}
*/
@Deprecated
public ProxyMaker(String superclassName, Class<?> superclass) {
@@ -265,8 +263,9 @@
doNullReturn(code, ret);
code.freeLocal(excLocal);
- if (exception == Throwable.class)
+ if (exception == Throwable.class) {
throwableFound = true;
+ }
}
if (!throwableFound) {
@@ -293,7 +292,7 @@
addMethod(method.getName(), method.getReturnType(), method.getParameterTypes(),
method.getExceptionTypes(), access, method.getDeclaringClass());
}
-
+
/**
* Adds a method of the given name to the class being implemented. If
* <code>declaringClass</code> is null, the generated method will expect to find an object of
@@ -310,21 +309,20 @@
addMethod(name, name, ret, parameters, exceptions, access, declaringClass, null, null);
}
-
+
/**
* Generates and adds a proxy method to the proxy class
- *
- * @param name: name of the java method
- * @param pyName: name of the python method to which the java method
- * proxies (useful for clamped objects)
- *
- * @param ret: return type
- * @param parameters: parameter types
- * @param exceptions: throwable exception types
+ *
+ * @param name of the java method
+ * @param pyName name of the python method to which the java method proxies (useful for clamped
+ * objects)
+ * @param ret return type
+ * @param parameters parameter types
+ * @param exceptions throwable exception types
* @param access
* @param declaringClass
- * @param methodAnnotations: method annotations
- * @param parameterAnnotations: parameter annotations
+ * @param methodAnnotations method annotations
+ * @param parameterAnnotations parameter annotations
* @throws Exception
*/
public void addMethod(String name,
@@ -337,7 +335,7 @@
AnnotationDescr[] methodAnnotations,
AnnotationDescr[][]parameterAnnotations) throws Exception {
boolean isAbstract = false;
-
+
if (Modifier.isAbstract(access)) {
access = access & ~Modifier.ABSTRACT;
isAbstract = true;
@@ -400,7 +398,7 @@
doNullReturn(code, ret);
}
}
-
+
/**
* A constructor that is also a method (!)
*/
@@ -412,7 +410,7 @@
Code code) throws Exception {
code.aload(0);
code.ldc(pyName);
-
+
int tmp = code.getLocal("org/python/core/PyObject");
code.invokestatic("org/python/compiler/ProxyMaker", "findPython",
makeSig($pyObj, $pyProxy, $str));
@@ -421,7 +419,7 @@
callMethod(code, "<init>", parameters, Void.TYPE, exceptions);
}
-
+
private String methodString(Method m) {
StringBuffer buf = new StringBuffer(m.getName());
buf.append(":");
@@ -500,7 +498,7 @@
addConstructor(name, parameters, Void.TYPE, makeSig(Void.TYPE, parameters), access);
}
}
-
+
protected void addClassAnnotation(AnnotationDescr annotation) {
classfile.addClassAnnotation(annotation);
}
@@ -635,21 +633,21 @@
addProxy();
visitConstructors();
classfile.addInterface("org/python/core/PyProxy");
-
+
visitClassAnnotations();
visitMethods();
doConstants();
addClassDictInit();
}
-
+
/**
* Visits all methods declared on the given class and classes in its inheritance hierarchy.
* Methods visible to subclasses are added to <code>seen</code>.
*/
protected void visitMethods(Class<?> klass) throws Exception {
for (Method method : klass.getDeclaredMethods()) {
-
-
+
+
// make sure we have only one name + signature pair available per method
if (!namesAndSigs.add(methodString(method))) {
continue;
@@ -689,9 +687,10 @@
}
/**
- * Called for every method on the proxy's superclass and interfaces that can be overriden by the
- * proxy class. If the proxy wants to perform Python lookup and calling for the method,
- * {@link #addMethod(Method)} should be called. For abstract methods, addMethod must be called.
+ * Called for every method on the proxy's superclass and interfaces that can be overridden by
+ * the proxy class. If the proxy wants to perform Python lookup and calling,
+ * {@link #addMethod(Method, int)} or one of its more complex forms should be called. For
+ * abstract methods, {@code addMethod} must be called.
*/
protected void visitMethod(Method method) throws Exception {
addMethod(method, method.getModifiers());
@@ -708,14 +707,14 @@
visitMethods(iface);
}
}
-
+
/** Adds a constructor that calls through to superclass. */
protected void addConstructor(Class<?>[] parameters, int access) throws Exception {
String sig = makeSig(Void.TYPE, parameters);
Code code = classfile.addMethod("<init>", sig, access);
callSuper(code, "<init>", mapClass(superclass), parameters, Void.TYPE, true);
}
-
+
/**
* Called for every constructor on the proxy's superclass that can be overridden by
* the proxy class.
@@ -747,16 +746,15 @@
code.visitMethodInsn(INVOKEVIRTUAL, classfile.name, "__initProxy__", makeSig("V", $objArr), false);
code.visitInsn(RETURN);
}
-
+
/**
* Visits constructors from this proxy's superclass.
*/
protected void visitConstructors() throws Exception {
addConstructors(superclass);
}
-
+
protected void visitClassAnnotations() throws Exception {
// ProxyMaker itself does nothing with class annotations for now
}
-
}
diff --git a/src/org/python/core/BaseBytes.java b/src/org/python/core/BaseBytes.java
--- a/src/org/python/core/BaseBytes.java
+++ b/src/org/python/core/BaseBytes.java
@@ -175,11 +175,9 @@
* Helper for <code>__new__</code> and <code>__init__</code> and the Java API constructor from
* PyObject in subclasses.
*
- * @see org.python.core.ByteArray#bytearray___init__(PyObject[], String[])
- * @see org.python.core.ByteArray#ByteArray(PyObject)
+ * @see org.python.core.PyByteArray#bytearray___init__(PyObject[], String[])
+ * @see org.python.core.PyByteArray#PyByteArray(PyObject)
* @param arg primary argument from which value is taken
- * @param encoding name of optional encoding (must be a string type)
- * @param errors name of optional errors policy (must be a string type)
*/
protected void init(PyObject arg) {
@@ -229,7 +227,7 @@
* Helper for <code>__new__</code> and <code>__init__</code> and the Java API constructor from a
* text string with the specified encoding in subclasses.
*
- * @see #bytearray___init__(PyObject[], String[])
+ * @see PyByteArray#bytearray___init__(PyObject[], String[])
* @see PyByteArray#PyByteArray(PyString, String, String)
* @param arg primary argument from which value is taken
* @param encoding name of optional encoding (must be a string type)
@@ -245,7 +243,7 @@
* Helper for <code>__new__</code> and <code>__init__</code> and the Java API constructor from a
* text string with the specified encoding in subclasses.
*
- * @see #bytearray___init__(PyObject[], String[])
+ * @see PyByteArray#bytearray___init__(PyObject[], String[])
* @see PyByteArray#PyByteArray(PyString, String, String)
* @param arg primary argument from which value is taken
* @param encoding name of optional encoding
@@ -264,7 +262,7 @@
* encoding in subclasses. This method thinly wraps a call to the codecs module and deals with
* checking for PyUnicode (where the encoding argument is mandatory).
*
- * @see #ByteArray(PyString, String, String)
+ * @see PyByteArray#PyByteArray(PyString, String, String)
* @param arg primary argument from which value is taken
* @param encoding name of optional encoding
* @param errors name of optional errors policy
@@ -1170,7 +1168,7 @@
*
* @param args Python argument list
* @param keywords Assocaited keywords
- * @return
+ * @return object containing the decoded characters
*/
protected final PyObject basebytes_decode(PyObject[] args, String[] keywords) {
ArgParser ap = new ArgParser("decode", args, keywords, "encoding", "errors");
@@ -2905,13 +2903,13 @@
//
/**
- * Helper to check the fill byte for {@link #rjust(String)}, {@link #ljust(String)} and
- * {@link #center(String)}, which is required to be a single character string, treated as a
- * byte.
+ * Helper to check the fill byte for {@link #basebytes_rjust(int, String)},
+ * {@link #basebytes_ljust(int, String)} and {@link #basebytes_center(int, String)}, which is
+ * required to be a single character string, treated as a byte.
*
* @param function name
* @param fillchar or <code>null</code>
- * @return
+ * @return the (checked) single fill byte
*/
protected static byte fillByteCheck(String function, String fillchar) {
if (fillchar == null) {
diff --git a/src/org/python/core/BytecodeNotification.java b/src/org/python/core/BytecodeNotification.java
--- a/src/org/python/core/BytecodeNotification.java
+++ b/src/org/python/core/BytecodeNotification.java
@@ -1,17 +1,16 @@
package org.python.core;
+import java.io.ByteArrayOutputStream;
import java.util.List;
import java.util.concurrent.CopyOnWriteArrayList;
-import java.util.Collections;
-import java.io.ByteArrayOutputStream;
/**
* Notifies registered callbacks if new bytecode is loaded.
*/
public class BytecodeNotification {
/**
- * Interface for callbacks.
- * Notifies the name of the loaded class, raw bytes of the class,
+ * Interface for callbacks.
+ * Notifies the name of the loaded class, raw bytes of the class,
* and the Java class object.
*/
public interface Callback {
@@ -19,8 +18,8 @@
}
/**
- * The following list stores register callback objects.
- * The list is shared among the PySystemState objects
+ * The following list stores register callback objects.
+ * The list is shared among the PySystemState objects
* if there are multiple instances.
*/
private static List<Callback> callbacks = new CopyOnWriteArrayList();
@@ -28,6 +27,7 @@
static {
// Maintain legacy behavior
register(new Callback() {
+ @Override
public void notify(String name, byte[] bytes, Class c) {
if (Options.proxyDebugDirectory == null ||
(!name.startsWith("org.python.pycode.") &&
@@ -52,11 +52,11 @@
* Unregisters the callback object
*
* @param n the callback object
- * @return true if successfully removed and
+ * @return true if successfully removed and
* false if the callback object was not registered
*/
public static boolean unregister(Callback n) { return callbacks.remove(n); }
-
+
/**
* Clears all the registered callbacks
*/
@@ -67,14 +67,14 @@
*
* @param name the name of the class of the new bytecode
* @param data raw byte data of the class
- * @param class Java class object of the new bytecode
+ * @param klass Java class object of the new bytecode
*/
public static void notify(String name, byte[] data, Class klass) {
- for (Callback c:callbacks) {
+ for (Callback c : callbacks) {
try {
c.notify(name, data, klass);
} catch (Exception e) {
- Py.writeWarning("BytecodeNotification", "Exception from callback:"+e);
+ Py.writeWarning("BytecodeNotification", "Exception from callback:" + e);
}
}
}
diff --git a/src/org/python/core/JyAttribute.java b/src/org/python/core/JyAttribute.java
--- a/src/org/python/core/JyAttribute.java
+++ b/src/org/python/core/JyAttribute.java
@@ -68,10 +68,7 @@
*/
public static final byte WEAKREF_PENDING_GET_ATTR = 3;
- /**
- * Only used internally by
- * {@linkorg.python.core.Py#javaPyClass(PyObject, Class<?>)}
- */
+ /** Only used internally by {@link Py#javaPyClass(PyObject, Class)} */
public static final byte PYCLASS_PY2JY_CACHE_ATTR = 4;
/**
@@ -94,8 +91,8 @@
private static byte nonBuiltinTransientAttrTypeOffset = 7;
/**
- * Reserves and returns a new non-transient attr type for custom use.
- *
+ * Reserves and returns a new non-transient attr type for custom use.
+ *
* @return a non-transient attr type for custom use
*/
public static byte reserveCustomAttrType() {
@@ -106,8 +103,8 @@
}
/**
- * Reserves and returns a new transient attr type for custom use.
- *
+ * Reserves and returns a new transient attr type for custom use.
+ *
* @return a transient attr type for custom use
*/
public static byte reserveTransientCustomAttrType() {
@@ -128,18 +125,22 @@
this.value = value;
}
+ @Override
protected JyAttribute getNext() {
return next;
}
+ @Override
protected void setNext(JyAttribute next) {
this.next = next;
}
+ @Override
protected Object getValue() {
return value;
}
+ @Override
protected void setValue(Object value) {
this.value = value;
}
@@ -154,18 +155,22 @@
this.value = value;
}
+ @Override
protected JyAttribute getNext() {
return next;
}
+ @Override
protected void setNext(JyAttribute next) {
this.next = next;
}
+ @Override
protected Object getValue() {
return value;
}
+ @Override
protected void setValue(Object value) {
this.value = value;
}
@@ -230,9 +235,9 @@
}
/**
- * Sets the attribute of type {@code attr_type} in {@code ob} to {@code value}.
- * If no corresponding attribute exists yet, one is created. If {@value == null},
- * the attribute is removed (if it existed at all).
+ * Sets the attribute of type {@code attr_type} in {@code ob} to {@code value}. If no
+ * corresponding attribute exists yet, one is created. If {@code value == null}, the attribute
+ * is removed (if it existed at all).
*/
public static void setAttr(PyObject ob, byte attr_type, Object value) {
synchronized (ob) {
diff --git a/src/org/python/core/Py.java b/src/org/python/core/Py.java
--- a/src/org/python/core/Py.java
+++ b/src/org/python/core/Py.java
@@ -2721,17 +2721,16 @@
}
/**
- * Returns a Python-class that extends {@code cls} and {@code interfce}.
- * If {@code cls} already extends {@code interfce}, simply {@code cls}
- * is returned. Otherwise a new class is created (if not yet cached).
- * It caches such classes and only creates a new one if no appropriate
+ * Returns a Python-class that extends {@code cls} and {@code interfce}. If {@code cls} already
+ * extends {@code interfce}, simply {@code cls} is returned. Otherwise a new class is created
+ * (if not yet cached). It caches such classes and only creates a new one if no appropriate
* class was cached yet.
*
* @return a Python-class that extends {@code cls} and {@code interfce}
*/
public static synchronized PyObject javaPyClass(PyObject cls, Class<?> interfce) {
- py2JyClassCacheItem cacheItem = (py2JyClassCacheItem)
- JyAttribute.getAttr(cls, JyAttribute.PYCLASS_PY2JY_CACHE_ATTR);
+ py2JyClassCacheItem cacheItem = (py2JyClassCacheItem) JyAttribute.getAttr(cls,
+ JyAttribute.PYCLASS_PY2JY_CACHE_ATTR);
PyObject result;
if (cacheItem == null) {
result = ensureInterface(cls, interfce);
@@ -2748,22 +2747,21 @@
}
/**
- * This method is a compact helper to access Python-constructors from Java.
- * It creates an instance of {@code cls} and retruns it in form of
- * {@code jcls}, which must be an interface. This method even works if
- * {@code cls} does not extend {@code jcls} in Python-code. In that case,
- * it uses {@link #javaPyClass(PyObject, Class)} to create an appropriate
- * class on the fly.<br>
+ * This method is a compact helper to access Python-constructors from Java. It creates an
+ * instance of {@code cls} and retruns it in form of {@code jcls}, which must be an interface.
+ * This method even works if {@code cls} does not extend {@code jcls} in Python-code. In that
+ * case, it uses {@link #javaPyClass(PyObject, Class)} to create an appropriate class on the
+ * fly.
+ * <p>
* It automatically converts {@code args} to {@link org.python.core.PyObject}s.<br>
- * For keyword-support use
- * {@link #newJ(PyObject, Class, String[], Object...)}.
+ * For keyword-support use {@link #newJ(PyObject, Class, String[], Object...)}.
*
- * {@see #newJ(PyObject, Class, PyObject[], String[])}
- * {@see #newJ(PyObject, Class, String[], Object...)}
- * {@see #newJ(PyModule, Class, Object...)}
- * {@see #newJ(PyModule, Class, String[], Object...)}
- * {@see org.python.core.PyModule#newJ(Class, Object...)}
- * {@see org.python.core.PyModule#newJ(Class, String[], Object...)}
+ * @see #newJ(PyObject, Class, PyObject[], String[])
+ * @see #newJ(PyObject, Class, String[], Object...)
+ * @see #newJ(PyModule, Class, Object...)
+ * @see #newJ(PyModule, Class, String[], Object...)
+ * @see PyModule#newJ(Class, Object...)
+ * @see PyModule#newJ(Class, String[], Object...)
*
* @param cls - the class to be instanciated
* @param jcls - the Java-type to be returned
@@ -2778,20 +2776,20 @@
}
/**
- * This method is a compact helper to access Python-constructors from Java.
- * It creates an instance of {@code cls} and retruns it in form of
- * {@code jcls}, which must be an interface. This method even works if
- * {@code cls} does not extend {@code jcls} in Python-code. In that case,
- * it uses {@link #javaPyClass(PyObject, Class)} to create an appropriate
- * class on the fly.<br>
+ * This method is a compact helper to access Python-constructors from Java. It creates an
+ * instance of {@code cls} and retruns it in form of {@code jcls}, which must be an interface.
+ * This method even works if {@code cls} does not extend {@code jcls} in Python-code. In that
+ * case, it uses {@link #javaPyClass(PyObject, Class)} to create an appropriate class on the
+ * fly.
+ * <p>
* {@code keywordss} are applied to the last {@code args} in the list.
*
- * {@see #newJ(PyObject, Class, Object...)}
- * {@see #newJ(PyObject, Class, String[], Object...)}
- * {@see #newJ(PyModule, Class, Object...)}
- * {@see #newJ(PyModule, Class, String[], Object...)}
- * {@see org.python.core.PyModule#newJ(Class, Object...)}
- * {@see org.python.core.PyModule#newJ(Class, String[], Object...)}
+ * @see #newJ(PyObject, Class, Object...)
+ * @see #newJ(PyObject, Class, String[], Object...)
+ * @see #newJ(PyModule, Class, Object...)
+ * @see #newJ(PyModule, Class, String[], Object...)
+ * @see PyModule#newJ(Class, Object...)
+ * @see PyModule#newJ(Class, String[], Object...)
*
* @param cls - the class to be instanciated
* @param jcls - the Java-type to be returned
@@ -2807,21 +2805,21 @@
}
/**
- * This method is a compact helper to access Python-constructors from Java.
- * It creates an instance of {@code cls} and retruns it in form of
- * {@code jcls}, which must be an interface. This method even works if
- * {@code cls} does not extend {@code jcls} in Python-code. In that case,
- * it uses {@link #javaPyClass(PyObject, Class)} to create an appropriate
- * class on the fly.<br>
+ * This method is a compact helper to access Python-constructors from Java. It creates an
+ * instance of {@code cls} and retruns it in form of {@code jcls}, which must be an interface.
+ * This method even works if {@code cls} does not extend {@code jcls} in Python-code. In that
+ * case, it uses {@link #javaPyClass(PyObject, Class)} to create an appropriate class on the
+ * fly.
+ * <p>
* It automatically converts {@code args} to {@link org.python.core.PyObject}s.<br>
* {@code keywordss} are applied to the last {@code args} in the list.
*
- * {@see #newJ(PyObject, Class, PyObject[], String[])}
- * {@see #newJ(PyObject, Class, Object...)}
- * {@see #newJ(PyModule, Class, Object...)}
- * {@see #newJ(PyModule, Class, String[], Object...)}
- * {@see org.python.core.PyModule#newJ(Class, Object...)}
- * {@see org.python.core.PyModule#newJ(Class, String[], Object...)}
+ * @see #newJ(PyObject, Class, PyObject[], String[])
+ * @see #newJ(PyObject, Class, Object...)
+ * @see #newJ(PyModule, Class, Object...)
+ * @see #newJ(PyModule, Class, String[], Object...)
+ * @see PyModule#newJ(Class, Object...)
+ * @see PyModule#newJ(Class, String[], Object...)
*
* @param cls - the class to be instanciated
* @param jcls - the Java-type to be returned
@@ -2837,17 +2835,17 @@
}
/**
- * Works like {@link #newJ(PyObject, Class, Object...)}, but looks
- * up the Python-class in the module-dict using the interface-name, i.e.
- * {@code jcls.getSimpleName()}.<br>
+ * Works like {@link #newJ(PyObject, Class, Object...)}, but looks up the Python-class in the
+ * module-dict using the interface-name, i.e. {@code jcls.getSimpleName()}.
+ * <p>
* For keywords-support use {@link #newJ(PyModule, Class, String[], Object...)}.
*
- * {@see #newJ(PyModule, Class, String[], Object...)}
- * {@see #newJ(PyObject, Class, PyObject[], String[])}
- * {@see #newJ(PyObject, Class, Object...)}
- * {@see #newJ(PyObject, Class, String[], Object...)}
- * {@see org.python.core.PyModule#newJ(Class, Object...)}
- * {@see org.python.core.PyModule#newJ(Class, String[], Object...)}
+ * @see #newJ(PyModule, Class, String[], Object...)
+ * @see #newJ(PyObject, Class, PyObject[], String[])
+ * @see #newJ(PyObject, Class, Object...)
+ * @see #newJ(PyObject, Class, String[], Object...)
+ * @see PyModule#newJ(Class, Object...)
+ * @see PyModule#newJ(Class, String[], Object...)
*
* @param module the module containing the desired class
* @param jcls Java-type of the desired clas, must have the same name
@@ -2861,17 +2859,17 @@
}
/**
- * Works like {@link #newJ(PyObject, Class, String[], Object...)}, but looks
- * up the Python-class in the module-dict using the interface-name, i.e.
- * {@code jcls.getSimpleName()}.<br>
+ * Works like {@link #newJ(PyObject, Class, String[], Object...)}, but looks up the Python-class
+ * in the module-dict using the interface-name, i.e. {@code jcls.getSimpleName()}.
+ * <p>
* {@code keywordss} are applied to the last {@code args} in the list.
*
- * {@see #newJ(PyModule, Class, Object...)}
- * {@see #newJ(PyObject, Class, PyObject[], String[])}
- * {@see #newJ(PyObject, Class, Object...)}
- * {@see #newJ(PyObject, Class, String[], Object...)}
- * {@see org.python.core.PyModule#newJ(Class, Object...)}
- * {@see org.python.core.PyModule#newJ(Class, String[], Object...)}
+ * @see #newJ(PyModule, Class, Object...)
+ * @see #newJ(PyObject, Class, PyObject[], String[])
+ * @see #newJ(PyObject, Class, Object...)
+ * @see #newJ(PyObject, Class, String[], Object...)
+ * @see PyModule#newJ(Class, Object...)
+ * @see PyModule#newJ(Class, String[], Object...)
*
* @param module the module containing the desired class
* @param jcls Java-type of the desired class, must have the same name
diff --git a/src/org/python/core/PyBUF.java b/src/org/python/core/PyBUF.java
--- a/src/org/python/core/PyBUF.java
+++ b/src/org/python/core/PyBUF.java
@@ -203,14 +203,14 @@
* Equivalent to <code>(INDIRECT | WRITABLE | FORMAT)</code>. Also use this in the request if
* you plan only to use the fully-encapsulated API (<code>byteAt</code>, <code>storeAt</code>,
* <code>copyTo</code>, <code>copyFrom</code>, etc.), without ever calling
- * {@link PyBuffer#getNIOByteBuffer()} or using {@link PyBuffer#Pointer()}.
+ * {@link PyBuffer#getNIOByteBuffer()} or using {@link PyBuffer.Pointer}.
*/
static final int FULL = INDIRECT | WRITABLE | FORMAT;
/**
* Equivalent to <code>(INDIRECT | FORMAT)</code>. Also use this in the request if you plan only
* to use the fully-encapsulated API (<code>byteAt</code>, <code>copyTo</code>, etc.), read
* only, without ever calling {@link PyBuffer#getNIOByteBuffer()} or using
- * {@link PyBuffer#Pointer()}.
+ * {@link PyBuffer.Pointer}.
*/
static final int FULL_RO = INDIRECT | FORMAT;
diff --git a/src/org/python/core/PyModule.java b/src/org/python/core/PyModule.java
--- a/src/org/python/core/PyModule.java
+++ b/src/org/python/core/PyModule.java
@@ -214,17 +214,15 @@
}
/**
- * Delegates to {@link #newJ(PyModule, Class, Object...)}, .<br>
- * For keywords-support use {@link #newJ(Class, String[], Object...)}.
+ * Delegates to {@link Py#newJ(PyModule, Class, Object...)}. For keyword support use
+ * {@link #newJ(Class, String[], Object...)}.
*
- * {@see #newJ(Class, String[], Object...)}
- * {@see org.python.core.Py#newJ(PyModule, Class, Object...)}
- * {@see org.python.core.Py#newJ(PyModule, Class, String[], Object...)}
- * {@see org.python.core.Py#newJ(PyObject, Class, PyObject[], String[])}
- * {@see org.python.core.Py#newJ(PyObject, Class, Object...)}
- * {@see org.python.core.Py#newJ(PyObject, Class, String[], Object...)}
+ * @see #newJ(Class, String[], Object...)
+ * @see Py#newJ(PyModule, Class, String[], Object...)
+ * @see Py#newJ(PyObject, Class, PyObject[], String[])
+ * @see Py#newJ(PyObject, Class, Object...)
+ * @see Py#newJ(PyObject, Class, String[], Object...)
*
- * @param module the module containing the desired class
* @param jcls Java-type of the desired clas, must have the same name
* @param args constructor-arguments
* @return a new instance of the desired class
@@ -235,15 +233,14 @@
}
/**
- * Delgates to {@link org.python.core.Py#newJ(PyModule, Class, String[], Object...)}.<br>
- * {@code keywordss} are applied to the last {@code args} in the list.
+ * Delgates to {@link org.python.core.Py#newJ(PyModule, Class, String[], Object...)}.
+ * {@code keywords} are applied to the last {@code args} in the list.
*
- * {@see #newJ(Class, Object...)}
- * {@see org.python.core.Py#newJ(PyModule, Class, Object...)}
- * {@see org.python.core.Py#newJ(PyModule, Class, String[], Object...)}
- * {@see org.python.core.Py#newJ(PyObject, Class, PyObject[], String[])}
- * {@see org.python.core.Py#newJ(PyObject, Class, Object...)}
- * {@see org.python.core.Py#newJ(PyObject, Class, String[], Object...)}
+ * @see #newJ(Class, Object...)
+ * @see Py#newJ(PyModule, Class, String[], Object...)
+ * @see Py#newJ(PyObject, Class, PyObject[], String[])
+ * @see Py#newJ(PyObject, Class, Object...)
+ * @see Py#newJ(PyObject, Class, String[], Object...)
*
* @param jcls Java-type of the desired class, must have the same name
* @param keywords are applied to the last {@code args} in the list
@@ -255,7 +252,6 @@
return Py.newJ(this, jcls, keywords, args);
}
-
/* Traverseproc implementation */
@Override
public int traverse(Visitproc visit, Object arg) {
diff --git a/src/org/python/core/PyObject.java b/src/org/python/core/PyObject.java
--- a/src/org/python/core/PyObject.java
+++ b/src/org/python/core/PyObject.java
@@ -129,10 +129,11 @@
* {@link org.python.core.finalization.FinalizablePyObject}.
* </p>
* <p>
- * Note that this empty finalizer implementation is optimized away by the JVM (See
- * {@link http://www.javaspecialists.eu/archive/Issue170.html}). So {@code PyObject}s are not
- * expensively treated as finalizable objects by the Java-GC. Its single intention is to prevent
- * subclasses from having Java-style finalizers.
+ * Note that this empty finalizer implementation is optimized away by the JVM. (See <a
+ * href=http://www.javaspecialists.eu/archive/Issue170.html}>Discovering Objects with
+ * Non-trivial Finalizers</a>). So {@code PyObject}s are not expensively treated as finalizable
+ * objects by the Java-GC. Its single intention is to prevent subclasses from having Java-style
+ * finalizers.
* </p>
*/
@Override
diff --git a/src/org/python/core/PyString.java b/src/org/python/core/PyString.java
--- a/src/org/python/core/PyString.java
+++ b/src/org/python/core/PyString.java
@@ -824,7 +824,7 @@
* This is to be overridden in a subclass to return its own type.
*
* @param str to wrap
- * @return
+ * @return instance wrapping {@code str}
*/
public PyString createInstance(String str) {
return new PyString(str);
@@ -834,9 +834,9 @@
* Create an instance of the same type as this object, from the Java String given as argument.
* This is to be overridden in a subclass to return its own type.
*
- * @param string UTF-16 string encoding the characters (as Java).
+ * @param str Java string representing the characters (as Java UTF-16).
* @param isBasic is ignored in <code>PyString</code> (effectively true).
- * @return
+ * @return instance wrapping {@code str}
*/
protected PyString createInstance(String str, boolean isBasic) {
// ignore isBasic, doesn't apply to PyString, just PyUnicode
diff --git a/src/org/python/core/PyUnicode.java b/src/org/python/core/PyUnicode.java
--- a/src/org/python/core/PyUnicode.java
+++ b/src/org/python/core/PyUnicode.java
@@ -156,7 +156,7 @@
/**
* The instance of index translation in use in this string. It will be set to either
- * {@link #BASIC} or and instance of {@link #Supplementary}.
+ * {@link #BASIC} or an instance of {@link PyUnicode.Supplementary}.
*/
private final IndexTranslator translator;
diff --git a/src/org/python/core/Traverseproc.java b/src/org/python/core/Traverseproc.java
--- a/src/org/python/core/Traverseproc.java
+++ b/src/org/python/core/Traverseproc.java
@@ -45,7 +45,7 @@
* </p>
* <p>
* Note that the slots-array and - if existent - the user-dict of {@code fooDerived}
- * classes is traversed by {@link org.python.core.TraverseProcDerived}.
+ * 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
* {@link org.python.modules.gc#traverse(PyObject, Visitproc, Object)} rather
@@ -469,7 +469,7 @@
* EncodeBasestringAsciiFunction - no refs, untraversable<br>
* <br>
* org.python.modules._jythonlib:<br>
- * dict_builder - Traverseproc<br>
+ * dict_builder - Traverseproc<br>
* <br>
* org.python.modules._threading:<br>
* Condition - Traverseproc<br>
@@ -653,7 +653,7 @@
* If {@link Visitproc#visit(PyObject, Object)} returns
* nonzero, this return value
* must be returned immediately by traverse.
- *
+ *
* {@link Visitproc#visit(PyObject, Object)} must not be
* called with a {@code null} PyObject-argument.
*/
diff --git a/src/org/python/core/buffer/BaseBuffer.java b/src/org/python/core/buffer/BaseBuffer.java
--- a/src/org/python/core/buffer/BaseBuffer.java
+++ b/src/org/python/core/buffer/BaseBuffer.java
@@ -22,12 +22,12 @@
* {@link #getNIOByteBufferImpl()} for <code>ByteBuffer</code>s that wrap the storage, and a factory
* for slices {@link #getBufferSlice(int, int, int, int)}.
* <p>
- * The sub-class constructor must specify the feature flags (see {@link #BaseBuffer(int)}), set
- * {@link #index0}, {@link #shape} and {@link #strides}, and finally check the client capabilities
- * with {@link #checkRequestFlags(int)}. Sub-classes intended to represent slices of exporters that
- * must count their exports as part of a locking protocol, as does <code>bytearray</code>, must
- * override {@link #getRoot()} so that a buffer view {@link #release()} on a slice, propagates to
- * the buffer view that provided it.
+ * The sub-class constructor must specify the feature flags (see
+ * {@link #BaseBuffer(int, int, int[], int[])}), set {@link #index0}, {@link #shape} and
+ * {@link #strides}, and finally check the client capabilities with {@link #checkRequestFlags(int)}.
+ * A sub-class intended to represent slices of an exporter that counts its exports, as part of a
+ * locking protocol like <code>bytearray</code>'s, must override {@link #getRoot()} so that a call
+ * to {@link #release()} on a view of slice, propagates to the buffer view that provided the slice.
* <p>
* Access methods provided here necessarily work with the abstracted {@link #byteAtImpl(int)},
* {@link #storeAtImpl(byte, int)} interface, but subclasses are able to override them with more
diff --git a/src/org/python/core/buffer/SimpleStringBuffer.java b/src/org/python/core/buffer/SimpleStringBuffer.java
--- a/src/org/python/core/buffer/SimpleStringBuffer.java
+++ b/src/org/python/core/buffer/SimpleStringBuffer.java
@@ -10,7 +10,7 @@
* Buffer API that appears to be a one-dimensional array of one-byte items providing read-only API,
* but which is actually backed by a Java String. Some of the buffer API absolutely needs access to
* the data as a byte array (those parts that involve a {@link java.nio.ByteBuffer} or
- * {@link PyBuffer.Pointer} result), and therefore this class must create a byte array from the
+ * {@link org.python.core.PyBuffer.Pointer} result), and therefore this class must create a byte array from the
* String for them. However, it defers creation of a byte array until that part of the API is
* actually used. Where possible, this class overrides those methods in SimpleBuffer that would
* otherwise access the byte array attribute to use the String instead.
diff --git a/src/org/python/core/buffer/Strided1DBuffer.java b/src/org/python/core/buffer/Strided1DBuffer.java
--- a/src/org/python/core/buffer/Strided1DBuffer.java
+++ b/src/org/python/core/buffer/Strided1DBuffer.java
@@ -46,8 +46,7 @@
* <p>
* The sub-class constructor should check that the intended access is compatible with this
* object by calling {@link #checkRequestFlags(int)}. (See the source of
- * {@link Strided1DWritableBuffer#Strided1DWritableBuffer(int, byte[], int, int, int)} for an
- * example of this use.)
+ * {@link Strided1DWritableBuffer} for an example of this use.)
*
* @param obj exporting object (or <code>null</code>)
* @param storage raw byte array containing exported data
diff --git a/src/org/python/core/buffer/Strided1DNIOBuffer.java b/src/org/python/core/buffer/Strided1DNIOBuffer.java
--- a/src/org/python/core/buffer/Strided1DNIOBuffer.java
+++ b/src/org/python/core/buffer/Strided1DNIOBuffer.java
@@ -48,8 +48,7 @@
* <p>
* The sub-class constructor should check that the intended access is compatible with this
* object by calling {@link #checkRequestFlags(int)}. (See the source of
- * {@link Strided1DWritableBuffer#Strided1DWritableBuffer(int, ByteBuffer, int, int, int)} for
- * an example of this use.)
+ * {@link Strided1DWritableBuffer} for an example of this use.)
*
* @param obj exporting object (or <code>null</code>)
* @param storage the <code>ByteBuffer</code> wrapping the exported object state. NOTE: this
diff --git a/src/org/python/core/codecs.java b/src/org/python/core/codecs.java
--- a/src/org/python/core/codecs.java
+++ b/src/org/python/core/codecs.java
@@ -63,15 +63,13 @@
}
/**
- * Decode the bytes <code>v</code> using the codec registered for the <code>encoding</code>.
- * The <code>encoding</code> defaults to the system default encoding
- * (see {@link codecs#getDefaultEncoding()}).
- * The string <code>errors</code> may name a different error handling
- * policy (built-in or registered with {@link #register_error(String, PyObject)}).
- * The default error policy is 'strict' meaning that encoding errors raise a
- * <code>ValueError</code>.
- * This method is exposed through the _codecs module as
- * {@link _codecs#decode(PyString, String, String)}.
+ * Decode the bytes <code>v</code> using the codec registered for the <code>encoding</code>. The
+ * <code>encoding</code> defaults to the system default encoding (see
+ * {@link codecs#getDefaultEncoding()}). The string <code>errors</code> may name a different
+ * error handling policy (built-in or registered with
+ * {@link #register_error(String, PyObject)}). The default error policy is 'strict' meaning that
+ * encoding errors raise a <code>ValueError</code>. This method is exposed through the _codecs
+ * module as {@link _codecs#decode(PyString, PyString, PyString)}
*
* @param v bytes to be decoded
* @param encoding name of encoding (to look up in codec registry)
@@ -400,15 +398,15 @@
};//@formatter:on
/**
- * Determine whether this character should be encoded as itself. The answer depends on whether
- * we are encoding set O (optional special characters) as itself, and also on whether we are
- * encoding whitespace as itself. RFC2152 makes it clear that the answers to these questions
- * vary between applications, so this code needs to be flexible.
+ * Determine whether, in the UTF-7 encoder, this character should be encoded as itself. The
+ * answer depends on whether we are encoding set O (optional special characters) as itself, and
+ * also on whether we are encoding whitespace as itself. RFC2152 makes it clear that the answers
+ * to these questions vary between applications, so this code needs to be flexible.
*
* @param c code point of the character
* @param directO true if characters in "set O" may be encoded as themselves
* @param directWS true if whitespace characters may be encoded as themselves
- * @return
+ * @return {@code true} if {@code c} should be encoded as itself
*/
private static boolean ENCODE_DIRECT(int c, boolean directO, boolean directWS) {
@@ -418,7 +416,7 @@
switch (utf7_category[c]) {
case 0: // This is a regular character
return true;
- case 1: // This is a whilespace character
+ case 1: // This is a white space character
return directWS;
case 2: // This is an optional special character
return directO;
@@ -870,7 +868,7 @@
// Currently we are in Base64 encoding: should we switch out?
if (ENCODE_DIRECT(ch, !base64SetO, !base64WhiteSpace)) {
/*
- * The next character is one for which we do not neeed to be in Base64, so pad
+ * The next character is one for which we do not need to be in Base64, so pad
* out to 6n the Base64 bits we currently have buffered and emit them. Then
* switch to US-ASCII.
*/
@@ -891,7 +889,7 @@
ch = '-'; // Comes out as +-
} else if (!ENCODE_DIRECT(ch, !base64SetO, !base64WhiteSpace)) {
/*
- * The next character is one for which we neeed to be in Base64, so switch to it
+ * The next character is one for which we need to be in Base64, so switch to it
* and emit the Base64 start marker and initialise the coder.
*/
v.append('+');
diff --git a/src/org/python/core/stringlib/InternalFormat.java b/src/org/python/core/stringlib/InternalFormat.java
--- a/src/org/python/core/stringlib/InternalFormat.java
+++ b/src/org/python/core/stringlib/InternalFormat.java
@@ -428,7 +428,7 @@
}
/**
- * Fix-up the zero-padding of the last formatted number in {@link #result()} in the special
+ * Fix-up the zero-padding of the last formatted number in {@link #result} in the special
* case where a sign-aware padding (<code>{@link #spec}.align='='</code>) was requested, the
* fill character is <code>'0'</code>, and the digits are to be grouped. In these exact
* circumstances, the grouping, which must already have been applied to the (whole part)
diff --git a/src/org/python/core/stringlib/MarkupIterator.java b/src/org/python/core/stringlib/MarkupIterator.java
--- a/src/org/python/core/stringlib/MarkupIterator.java
+++ b/src/org/python/core/stringlib/MarkupIterator.java
@@ -142,7 +142,7 @@
/**
* Return the next {@link Chunk} from the iterator, which is a structure containing parsed
* elements of the replacement field (if any), and its preceding text. This is the Java
- * equivalent of the tuple returned by {@link __iternext__()}. This finds use in the
+ * equivalent of the tuple returned by {@link #__iternext__()}. This finds use in the
* implementation of <code>str.format</code> and <code>unicode.format</code>.
*
* @return the chunk
diff --git a/src/org/python/expose/generate/ExposedTypeVisitor.java b/src/org/python/expose/generate/ExposedTypeVisitor.java
--- a/src/org/python/expose/generate/ExposedTypeVisitor.java
+++ b/src/org/python/expose/generate/ExposedTypeVisitor.java
@@ -57,9 +57,9 @@
/**
* @param name the name the type should be exposed as from the annotation
- * @param name the specified base type
- * @param name the value of the isBaseType flag
- * @param name the type's docstring
+ * @param base the specified base type
+ * @param isBaseType the value of the isBaseType flag
+ * @param doc the type's docstring
*/
public abstract void handleResult(String name, Type base, boolean isBaseType, String doc);
}
diff --git a/src/org/python/indexer/Indexer.java b/src/org/python/indexer/Indexer.java
--- a/src/org/python/indexer/Indexer.java
+++ b/src/org/python/indexer/Indexer.java
@@ -7,6 +7,7 @@
import org.python.indexer.ast.NNode;
import org.python.indexer.ast.NModule;
import org.python.indexer.ast.NName;
+import org.python.indexer.ast.NStr;
import org.python.indexer.ast.NUrl;
import org.python.indexer.types.NModuleType;
import org.python.indexer.types.NType;
@@ -159,7 +160,7 @@
}
/**
- * If aggressive assertions are enabled, propages the passed
+ * If aggressive assertions are enabled, propagates the passed
* {@link Throwable}, wrapped in an {@link IndexingException}.
* @param msg descriptive message; ok to be {@code null}
* @throws IndexingException
@@ -193,7 +194,7 @@
* If aggressive assertions are enabled, throws an {@code IndexingException}.
* Otherwise the message is logged as a warning, and indexing continues.
* @param msg a descriptive message about the problem
- * @see enableAggressiveAssertions
+ * @see #enableAggressiveAssertions(boolean)
* @throws IndexingException
*/
public void reportFailedAssertion(String msg) {
@@ -233,7 +234,7 @@
/**
* Returns the module search path -- the project directory followed by any
- * paths that were added by {@link addPath}.
+ * paths that were added by {@link #addPath(String)}.
*/
public List<String> getLoadPath() {
List<String> loadPath = new ArrayList<String>();
@@ -321,8 +322,8 @@
* @return a list of entries constituting the file outline.
* Returns an empty list if the indexer hasn't indexed that path.
*/
- public List<Outliner.Entry> generateOutline(String file) throws Exception {
- return new Outliner().generate(this, file);
+ public List<Outliner.Entry> generateOutline(String path) throws Exception {
+ return new Outliner().generate(this, path);
}
/**
@@ -508,7 +509,7 @@
* If it is a directory, it is suffixed with "__init__.py", and
* only that file is loaded from the directory.
*
- * @param noparents {@code true} to skip loading ancestor packages
+ * @param skipChain {@code true} to skip loading ancestor packages
*
* @return {@code null} if {@code path} could not be loaded
*/
@@ -650,18 +651,19 @@
}
/**
- * This method searches the module path for the module {@code modname}.
- * If found, it is passed to {@link #loadFile}.
+ * This method searches the module path for the module {@code modname}. If found, it is passed
+ * to {@link #loadFile}.
+ *
+ * <p>
+ * The mechanisms for importing modules are in general statically undecidable. We make a
+ * reasonable effort to follow the most common lookup rules.
*
- * <p>The mechanisms for importing modules are in general statically
- * undecidable. We make a reasonable effort to follow the most common
- * lookup rules.
+ * @param modname a module name. Can be a relative path to a directory or a file (without the
+ * extension) or a possibly-qualified module name. If it is a module name, cannot
+ * contain leading dots.
*
- * @param modname a module name. Can be a relative path to a directory
- * or a file (without the extension) or a possibly-qualified
- * module name. If it is a module name, cannot contain leading dots.
- *
- * @see http://docs.python.org/reference/simple_stmts.html#the-import-statement
+ * @see <a href="http://docs.python.org/reference/simple_stmts.html#the-import-statement">The
+ * Import Statement</a>
*/
public NModuleType loadModule(String modname) throws Exception {
if (failedModules.contains(modname)) {
diff --git a/src/org/python/indexer/IndexingException.java b/src/org/python/indexer/IndexingException.java
--- a/src/org/python/indexer/IndexingException.java
+++ b/src/org/python/indexer/IndexingException.java
@@ -6,7 +6,8 @@
/**
* Signals that indexing is being aborted.
- * @see {Indexer#enableAggressiveAssertions}
+ *
+ * @see Indexer#enableAggressiveAssertions(boolean)
*/
public class IndexingException extends RuntimeException {
diff --git a/src/org/python/indexer/NBinding.java b/src/org/python/indexer/NBinding.java
--- a/src/org/python/indexer/NBinding.java
+++ b/src/org/python/indexer/NBinding.java
@@ -8,6 +8,7 @@
import org.python.indexer.ast.NUrl;
import org.python.indexer.types.NModuleType;
import org.python.indexer.types.NType;
+import org.python.indexer.types.NUnionType;
import org.python.indexer.types.NUnknownType;
import java.util.ArrayList;
@@ -17,15 +18,13 @@
import java.util.Set;
/**
- * An {@code NBinding} collects information about a fully qualified name (qname)
- * in the code graph.<p>
- *
- * Each qname has an associated {@link NType}. When a particular qname is
- * assigned values of different types at different locations, its type is
- * represented as a {@link NUnionType}. <p>
- *
- * Each qname has a set of one or more definitions, and a set of zero or
- * more references. Definitions and references correspond to code locations. <p>
+ * An {@code NBinding} collects information about a fully qualified name (qname) in the code graph.
+ * <p>
+ * Each qname has an associated {@link NType}. When a particular qname is assigned values of
+ * different types at different locations, its type is represented as a {@link NUnionType}.
+ * <p>
+ * Each qname has a set of one or more definitions, and a set of zero or more references.
+ * Definitions and references correspond to code locations.
*/
public class NBinding implements Comparable<Object> {
@@ -256,6 +255,7 @@
/**
* Bindings can be sorted by their location for outlining purposes.
*/
+ @Override
public int compareTo(Object o) {
return getSignatureNode().start() - ((NBinding)o).getSignatureNode().start();
}
diff --git a/src/org/python/indexer/Outliner.java b/src/org/python/indexer/Outliner.java
--- a/src/org/python/indexer/Outliner.java
+++ b/src/org/python/indexer/Outliner.java
@@ -121,18 +121,23 @@
public Branch(String qname, int start, NBinding.Kind kind) {
super(qname, start, kind);
}
+ @Override
public boolean isLeaf() {
return false;
}
+ @Override
public boolean isBranch() {
return true;
}
+ @Override
public boolean hasChildren() {
return children != null && !children.isEmpty();
}
+ @Override
public List<Entry> getChildren() {
return children;
}
+ @Override
public void setChildren(List<Entry> children) {
this.children = children;
}
@@ -142,9 +147,11 @@
* An entry with no children.
*/
public static class Leaf extends Entry {
+ @Override
public boolean isLeaf() {
return true;
}
+ @Override
public boolean isBranch() {
return false;
}
@@ -155,12 +162,15 @@
public Leaf(String qname, int start, NBinding.Kind kind) {
super(qname, start, kind);
}
+ @Override
public boolean hasChildren() {
return false;
}
+ @Override
public List<Entry> getChildren() {
return new ArrayList<Entry>();
}
+ @Override
public void setChildren(List<Entry> children) {
throw new UnsupportedOperationException("Leaf nodes cannot have children.");
}
@@ -168,8 +178,8 @@
/**
* Create an outline for a file in the index.
- * @param scope the file scope
- * @param path the file for which to build the outline
+ * @param idx index holding the file scope
+ * @param abspath the file for which to build the outline
* @return a list of entries constituting the file outline.
* Returns an empty list if the indexer hasn't indexed that path.
*/
diff --git a/src/org/python/indexer/Scope.java b/src/org/python/indexer/Scope.java
--- a/src/org/python/indexer/Scope.java
+++ b/src/org/python/indexer/Scope.java
@@ -148,10 +148,10 @@
/**
* Directly assigns a binding to a name in this table. Does not add a new
* definition or reference to the binding. This form of {@code put} is
- * often followed by a call to {@link putLocation} to create a reference to
+ * often followed by a call to {@link Indexer#putLocation} to create a reference to
* the binding. When there is no code location associated with {@code id},
* or it is otherwise undesirable to create a reference, the
- * {@link putLocation} call is omitted.
+ * {@link Indexer#putLocation} call is omitted.
*/
public void put(String id, NBinding b) {
putBinding(id, b);
@@ -482,7 +482,7 @@
/**
* Look up an attribute in the local scope and superclass scopes.
- * @see lookupAttr(String,boolean)
+ * @see #lookupAttr(String,boolean)
*/
public NBinding lookupAttr(String name) {
return lookupAttr(name, false);
diff --git a/src/org/python/indexer/ast/DefaultNodeVisitor.java b/src/org/python/indexer/ast/DefaultNodeVisitor.java
--- a/src/org/python/indexer/ast/DefaultNodeVisitor.java
+++ b/src/org/python/indexer/ast/DefaultNodeVisitor.java
@@ -20,224 +20,278 @@
* and then tree traversal halts. <p>
*
* If the traversal should be halted immediately without visiting any further
- * nodes, the visitor can throw a {@link StopIterationException}.
+ * nodes, the visitor can throw a {@link NNodeVisitor.StopIterationException}.
*/
public void stopTraversal() {
traverseIntoNodes = false;
}
+ @Override
public boolean visit(NAlias n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NAssert n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NAssign n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NAttribute n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NAugAssign n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NBinOp n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NBlock n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NBoolOp n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NBreak n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NCall n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NClassDef n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NCompare n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NComprehension n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NContinue n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NDelete n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NDict n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NEllipsis n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NExceptHandler n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NExec n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NFor n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NFunctionDef n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NGeneratorExp n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NGlobal n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NIf n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NIfExp n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NImport n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NImportFrom n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NIndex n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NKeyword n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NLambda n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NList n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NListComp n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NModule n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NName n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NNum n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NPass n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NPlaceHolder n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NPrint n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NQname n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NRaise n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NRepr n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NReturn n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NExprStmt n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NSlice n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NStr n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NSubscript n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NTryExcept n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NTryFinally n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NTuple n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NUnaryOp n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NUrl n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NWhile n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NWith n) {
return traverseIntoNodes;
}
+ @Override
public boolean visit(NYield n) {
return traverseIntoNodes;
}
diff --git a/src/org/python/indexer/ast/NNode.java b/src/org/python/indexer/ast/NNode.java
--- a/src/org/python/indexer/ast/NNode.java
+++ b/src/org/python/indexer/ast/NNode.java
@@ -85,7 +85,7 @@
/**
* Returns the type for this node. It is never {@code null}.
* If the node has not been resolved, the type will default to
- * {@link Indexer.idx.builtins.None}.
+ * {@code Indexer.idx.builtins.None}.
*/
public NType getType() {
if (type == null) {
@@ -122,11 +122,11 @@
}
/**
- * Returns {@code true} if this is a name-binding node.
- * Includes functions/lambdas, function/lambda params, classes,
- * assignments, imports, and implicit assignment via for statements
- * and except clauses.
- * @see http://www.python.org/dev/peps/pep-0227
+ * Returns {@code true} if this is a name-binding node. Includes functions/lambdas,
+ * function/lambda params, classes, assignments, imports, and implicit assignment via for
+ * statements and except clauses.
+ *
+ * @see <a href="http://www.python.org/dev/peps/pep-0227">PEP 227</a>
*/
public boolean bindsName() {
return false;
@@ -350,6 +350,7 @@
return deepest;
}
+ @Override
public boolean dispatch(NNode node) {
// This node ends before the offset, so don't look inside it.
if (offset > node.end) {
diff --git a/src/org/python/indexer/types/NUnionType.java b/src/org/python/indexer/types/NUnionType.java
--- a/src/org/python/indexer/types/NUnionType.java
+++ b/src/org/python/indexer/types/NUnionType.java
@@ -17,11 +17,12 @@
public class NUnionType extends NType {
/**
- * Union types can lead to infinite recursion in the occurs check. Until
- * we've got a handle on these cases, I'm limiting the recursion depth.
+ * Union types can lead to infinite recursion in the occurs check. Until we've got a handle on
+ * these cases, I'm limiting the recursion depth.
*
- * @see http://www.cs.kuleuven.ac.be/~dtai/projects/ALP/newsletter/archive_93_96/net/impl/occur.html
- * for an interesting and highly relevant discussion.
+ * @see <a href=
+ * "http://www.cs.kuleuven.ac.be/~dtai/projects/ALP/newsletter/archive_93_96/net/impl/occur.html">
+ * The Occurs Check</a> for an interesting and highly relevant discussion.
*/
private static final int MAX_RECURSION_DEPTH = 15;
@@ -133,7 +134,7 @@
}
/**
- * @see http://en.wikipedia.org/wiki/Occurs_check
+ * @see <a href="http://en.wikipedia.org/wiki/Occurs_check">Occurs check</a>
*/
private static boolean occurs(NType u, NType v, int depth) {
if (depth++ > MAX_RECURSION_DEPTH) {
@@ -210,7 +211,7 @@
/**
* Returns the first alternate whose type is not unknown and
- * is not {@link Indexer.idx.builtins.None}.
+ * is not {@code Indexer#idx.builtins.None}.
* @return the first non-unknown, non-{@code None} alternate, or {@code null} if none found
*/
public NType firstKnownNonNullAlternate() {
diff --git a/src/org/python/modules/_io/PyIOBase.java b/src/org/python/modules/_io/PyIOBase.java
--- a/src/org/python/modules/_io/PyIOBase.java
+++ b/src/org/python/modules/_io/PyIOBase.java
@@ -33,7 +33,7 @@
* <b>Implementation note:</b> The code is based heavily on the Jython 2.6-ish
* <code>_fileio.PyFileIO</code>, the purely Java-accessible {@link org.python.core.io.IOBase} (both
* Philip Jenvey's work), and the Python implementation in <code>Lib/_pyio</code>. We do not simply
- * delegate to the implementation in {@link org.python.core.io} because of the need to override
+ * delegate to the implementation in {@code org.python.core.io} because of the need to override
* parts of the implementation in Python subclasses. A call to {@link #close()}, for example, is
* required to call {@link #flush()}, but if delegated to the pure Java implementation would not
* call the version of <code>flush()</code> overridden in a Python sub-class of
diff --git a/src/org/python/modules/cStringIO.java b/src/org/python/modules/cStringIO.java
--- a/src/org/python/modules/cStringIO.java
+++ b/src/org/python/modules/cStringIO.java
@@ -99,7 +99,7 @@
/**
* The StringIO object
* @see cStringIO#StringIO()
- * @see cStringIO#StringIO(String)
+ * @see cStringIO#StringIO(CharSequence)
*/
public static class StringIO extends PyIterator {
public boolean softspace = false;
@@ -122,8 +122,9 @@
}
private void _complain_ifclosed() {
- if (closed)
+ if (closed) {
throw Py.ValueError("I/O operation on closed file");
+ }
}
private int _convert_to_int(long val) {
@@ -146,8 +147,9 @@
public PyObject __iternext__() {
_complain_ifclosed();
PyString r = readline();
- if (r.__len__() == 0)
+ if (r.__len__() == 0) {
return null;
+ }
return r;
}
@@ -187,7 +189,7 @@
/**
* Position the file pointer to the position in the .
- *
+ *
* @param pos
* the position in the file.
* @param mode
@@ -313,8 +315,9 @@
int newpos = (i < 0) ? len : i;
String r = buf.substring(pos, newpos);
pos = newpos;
- if (pos < len) // Skip the newline
+ if (pos < len) {
pos++;
+ }
return new PyString(r);
}
@@ -343,8 +346,9 @@
while (line.__len__() > 0) {
lines.append(line);
total += line.__len__();
- if (0 < sizehint_int && sizehint_int <= total)
+ if (0 < sizehint_int && sizehint_int <= total) {
break;
+ }
line = readline();
}
return lines;
@@ -367,8 +371,9 @@
throw Py.IOError("Negative size not allowed");
}
int pos_int = _convert_to_int(pos);
- if (pos_int < 0)
+ if (pos_int < 0) {
pos_int = this.pos;
+ }
buf.setLength(pos_int);
this.pos = pos_int;
}
@@ -402,8 +407,9 @@
int l = spos - slen;
char[] bytes = new char[l];
- for (int i = 0; i < l - 1; i++)
+ for (int i = 0; i < l - 1; i++) {
bytes[i] = '\0';
+ }
buf.append(bytes);
slen = spos;
@@ -434,8 +440,9 @@
*/
public synchronized void writeChar(char ch) {
int len = buf.length();
- if (len <= pos)
+ if (len <= pos) {
buf.setLength(pos + 1);
+ }
buf.setCharAt(pos++, ch);
}
diff --git a/src/org/python/modules/cmath.java b/src/org/python/modules/cmath.java
--- a/src/org/python/modules/cmath.java
+++ b/src/org/python/modules/cmath.java
@@ -475,9 +475,8 @@
* Helper to compute either cos <i>z</i> or cosh <i>z</i>.
*
* @param z
- * @param h <code>true</code> to compute cosh <i>z</i>, <code>false</code> to compute cos
- * <i>z</i>.
- * @return
+ * @param h <code>true</code> for cosh, <code>false</code> for cos.
+ * @return cos <i>z</i> or cosh <i>z</i>
*/
private static PyComplex cosOrCosh(PyComplex z, boolean h) {
double x, y, u, v;
@@ -631,7 +630,7 @@
*
* @param r radius
* @param phi angle
- * @return
+ * @return <i>r</i>e<sup><i>iφ</i></sup>
*/
public static PyComplex rect(double r, double phi) {
double x, y;
@@ -828,9 +827,8 @@
* Helper to compute either sin <i>z</i> or sinh <i>z</i>.
*
* @param z
- * @param h <code>true</code> to compute sinh <i>z</i>, <code>false</code> to compute sin
- * <i>z</i>.
- * @return
+ * @param h <code>true</code> for sinh, <code>false</code> for sin.
+ * @return sinh <i>z</i> or sin <i>z</i>.
*/
private static PyComplex sinOrSinh(PyComplex z, boolean h) {
double x, y, u, v;
diff --git a/src/org/python/modules/gc.java b/src/org/python/modules/gc.java
--- a/src/org/python/modules/gc.java
+++ b/src/org/python/modules/gc.java
@@ -80,7 +80,7 @@
* the number of collected objects in the same manner as in CPython, i.e. counts only those
* that participate in reference cycles. This allows a unified test implementation across
* Jython and CPython (which applies to most tests in test_gc.py). If not any object is
- * gc-monitored, {@link #collect()} just delegates to {@link java.lang.System.gc()}, runs
+ * gc-monitored, {@link #collect()} just delegates to {@link java.lang.System#gc()}, runs
* asynchronously (i.e. non-blocking) and returns {@link #UNKNOWN_COUNT}.
* See also {@link #DEBUG_SAVEALL} for a useful gc debugging feature that is supported by
* Jython from version 2.7 onwards.
@@ -178,7 +178,7 @@
* reserved to indicate an error.
*/
public static final int UNKNOWN_COUNT = -2;
-
+
/* Jython-specific gc flags: */
/**
* This flag tells every newly created PyObject to register for
@@ -349,7 +349,7 @@
/**
* Enables collection-related verbose output.
- *
+ *
* @see #setJythonGCFlags(short)
* @see #getJythonGCFlags()
* @see #addJythonGCFlags(short)
@@ -702,14 +702,17 @@
}
}
+ @Override
public String toString() {
return str;
}
+ @Override
public int hashCode() {
return hashCode;
}
+ @Override
public boolean equals(Object ob) {
Object ownReferent = get();
if (ob instanceof WeakReferenceGC) {
@@ -750,7 +753,7 @@
new WeakrefGCCompareDummy();
protected PyObject compare;
int hashCode = 0;
-
+
public void setCompare(PyObject compare) {
this.compare = compare;
hashCode = System.identityHashCode(compare);
@@ -761,10 +764,12 @@
hashCode = 0;
}
+ @Override
public int hashCode() {
return hashCode;
}
-
+
+ @Override
@SuppressWarnings("rawtypes")
public boolean equals(Object ob) {
if (ob instanceof Reference) {
@@ -779,11 +784,12 @@
private static class GCSentinel {
Thread waiting;
-
+
public GCSentinel(Thread notifyOnFinalize) {
waiting = notifyOnFinalize;
}
+ @Override
protected void finalize() throws Throwable {
notifyPreFinalization();
if ((gcFlags & VERBOSE_COLLECT) != 0) {
@@ -880,7 +886,7 @@
cm = (CycleMarkAttr) JyAttribute.getAttr(obj, JyAttribute.GC_CYCLE_MARK_ATTR);
cyclic = cm != null && cm.isUncollectable();
}
-
+
if ((gcFlags & VERBOSE_DELAYED) != 0 || (gcFlags & VERBOSE_FINALIZE) != 0) {
writeDebug("gc", "notify finalizer abort; cyclic? "+cyclic);
}
@@ -929,6 +935,7 @@
}
}
+ @Override
public void run() {
if ((gcFlags & VERBOSE_DELAYED) != 0) {
writeDebug("gc", "run delayed finalization. Index: "+
@@ -1100,6 +1107,7 @@
// If delayed callbacks were turned off, we process remaining
// queued callbacks immediately (but in a new thread though):
Thread dlcProcess = new Thread() {
+ @Override
public void run() {
GlobalRef.processDelayedCallbacks();
}
@@ -1163,6 +1171,7 @@
protected static PostFinalizationProcessor defaultInstance =
new PostFinalizationProcessor();
+ @Override
public void run() {
/* We wait until last postFinalizationTimestamp is at least timeOut ago.
* This should only be measured when openFinalizeCount is zero.
@@ -1435,7 +1444,7 @@
//--------------Monitoring section---------------------------------------------
-
+
public static void monitorObject(PyObject ob) {
monitorObject(ob, false);
}
@@ -1607,10 +1616,10 @@
* {@link #MONITOR_GLOBAL} - Automatically monitors all PyObjects created from now on.<br>
* {@link #DONT_FINALIZE_CYCLIC_GARBAGE} - Adds cyclic finalizable PyObjects to {@link #garbage}.<br>
* {@link #PRESERVE_WEAKREFS_ON_RESURRECTION} - Keeps weak references alive if the referent is resurrected.<br>
- * {@link #DONT_FINALIZE_RESURRECTED_OBJECTS} -
+ * {@link #DONT_FINALIZE_RESURRECTED_OBJECTS} -
* Emulates CPython behavior regarding resurrected objects and finalization.<br>
* {@link #DONT_TRAVERSE_BY_REFLECTION} - Inhibits reflection-based traversion.<br>
- * {@link #SUPPRESS_TRAVERSE_BY_REFLECTION_WARNING} -
+ * {@link #SUPPRESS_TRAVERSE_BY_REFLECTION_WARNING} -
* Suppress warnings for PyObjects that neither implement {@link org.python.core.Traverseproc} nor
* are marked as {@link org.python.core.Untraversable}.<br>
* {@link #USE_PY_WRITE_DEBUG} - uses {@link org.python.core.Py#writeDebug(String, String)} for
@@ -1742,7 +1751,7 @@
/**
* The generation parameter is only for compatibility with
- * CPython {@link gc.collect()} and is ignored.
+ * CPython {@link #collect()} and is ignored.
* @param generation (ignored)
* @return Collected monitored cyclic trash objects or
* {@code gc.UNKNOWN_COUNT} if nothing is monitored or -1 if
@@ -1752,7 +1761,7 @@
public static int collect(int generation) {
return collect();
}
-
+
private static boolean needsTrashPrinting() {
return ((debugFlags & DEBUG_COLLECTABLE) != 0 ||
(debugFlags & DEBUG_UNCOLLECTABLE) != 0) &&
@@ -1770,7 +1779,7 @@
* non-erroneous default value. If objects are monitored,
* it emulates a synchronous gc run in the sense that it waits
* until all collected monitored objects were finalized.
- *
+ *
* @return Number of collected monitored cyclic trash objects
* or {@link #UNKNOWN_COUNT} if nothing is monitored or -1
* if an error occurred and collection did not complete.
@@ -1784,7 +1793,7 @@
cme.printStackTrace();
} catch (NullPointerException npe) {
npe.printStackTrace();
- }
+ }
return -1;
}
@@ -1811,7 +1820,7 @@
}
/* We must fail fast in this case to avoid deadlocks.
* Deadlock would for instance occur if a finalizer calls
- * gc.collect (like is done in some tests in test_gc).
+ * gc.collect (like is done in some tests in test_gc).
* Former version: throw new IllegalStateException("GC is already running.");
*/
return -1; /* better not throw exception here, as calling code
@@ -1847,9 +1856,9 @@
++gcMonitoredRunCount;
delayedFinalizationMode = MARK_REACHABLE_CRITICALS;
notifyRerun = false;
-
+
int[] stat = {0, 0};
-
+
syncCollect(stat, (debugFlags & DEBUG_STATS) != 0);
delayedFinalizationMode = NOTIFY_FOR_RERUN;
@@ -1975,7 +1984,7 @@
System.err.println("Finalize wait count should be initially 0!");
finalizeWaitCount = 0;
}
-
+
/* We tidy up a bit... (Because it is not unlikely that
* the preparation stuff done so far has caused a gc run.)
* This is not entirely safe as gc could interfere with
@@ -1984,7 +1993,7 @@
* Maybe we will include more mechanisms to ensure safety
* in the future.
*/
-
+
try {
trash = gcTrash.remove(initWaitTime);
if (trash != null && (gcFlags & VERBOSE_COLLECT) != 0) {
@@ -2016,7 +2025,7 @@
}
cyclicLookup = null;
List<WeakReferenceGC> collectBuffer;
-
+
/* The following out commented block is a nice idea to sync gc in a more
* elegant way. Unfortunately it proved infeasible because MXBean appears
* to be no reliable measurement for gc to have finished enqueueing trash.
@@ -2080,19 +2089,19 @@
* listing related to DEBUG_X flags also counts/lists
* objects that participate in a cycle with uncollectable
* finalizable objects.
- *
+ *
* Comprehension:
* An object is uncollectable if it is in a ref cycle and
* has a finalizer.
- *
+ *
* CPython
- *
+ *
* - counts and prints the whole uncollectable cycle in context
* of DEBUG_X flags.
- *
+ *
* - stores only those objects from the cycle that actually have
* finalizers in gc.garbage.
- *
+ *
* While slightly contradictory to the doc, we reproduce this
* behavior here.
*/
@@ -2406,7 +2415,7 @@
* Set the garbage collection debugging flags. Debugging information is
* written to {@code System.err}.<br>
* <br>
- * {@flags} flags is an {@code int}eger and can have the following bits turned on:<br>
+ * {@code flags} flags is an {@code int}eger and can have the following bits turned on:<br>
* <br>
* {@link #DEBUG_STATS} - Print statistics during collection.<br>
* {@link #DEBUG_COLLECTABLE} - Print collectable objects found.<br>
@@ -2565,7 +2574,7 @@
* contained in the resulting set, i.e. missing participants will be added.
* This method completely operates on weak references to ensure that the returned
* set does not manipulate gc behavior.
- *
+ *
* Note that this method is not threadsafe. Within the gc module it is only used
* by the collect method, which ensures threadsafety by a synchronized block.
*/
@@ -2573,7 +2582,7 @@
removeNonCyclicWeakRefs(Iterable<WeakReferenceGC> pool) {
@SuppressWarnings("unchecked")
IdentityHashMap<PyObject, WeakReferenceGC>[] pools = new IdentityHashMap[2];
-
+
pools[0] = new IdentityHashMap<PyObject, WeakReferenceGC>();
pools[1] = new IdentityHashMap<PyObject, WeakReferenceGC>();
PyObject referent;
@@ -2591,8 +2600,9 @@
/* this means the pool is already entirely traversable */
for (WeakReferenceGC ref: pool) {
referent = ref.get();
- if (referent != null)
- pools[0].put(referent, ref);
+ if (referent != null) {
+ pools[0].put(referent, ref);
+ }
}
}
IdentityHashMap<PyObject, WeakReferenceGC> tmp;
@@ -2660,7 +2670,7 @@
pools[1] = new IdentityHashMap<PyObject, PyObject>();
IdentityHashMap<PyObject, PyObject> tmp;
IdentityHashMap<PyObject, PyObject> toProcess = new IdentityHashMap<>();
-
+
/* We complete pools[0] with all reachable objects.
* Note the difference to the implementation in removeNonCyclic.
* There pools[0] was initialized with the contents of pool and
@@ -2694,14 +2704,14 @@
* contained in the resulting set, i.e. missing participants will be added.
* This method completely operates on weak references to ensure that the returned
* set does not manipulate gc behavior.
- *
+ *
* Note that this method is not threadsafe. Within the gc module it is only used
* by the collect method which ensures threadsafety by a synchronized block.
*/
private static Set<PyObject> removeNonCyclic(Iterable<PyObject> pool) {
@SuppressWarnings("unchecked")
IdentityHashMap<PyObject, PyObject>[] pools = new IdentityHashMap[2];
-
+
pools[0] = new IdentityHashMap<PyObject, PyObject>();
pools[1] = new IdentityHashMap<PyObject, PyObject>();
if (monitorNonTraversable) {
@@ -2721,7 +2731,7 @@
}
IdentityHashMap<PyObject, PyObject> tmp;
IdentityHashMap<PyObject, PyObject> toProcess = new IdentityHashMap<>();
-
+
/* We complete pools[0] with all reachable objects. */
for (PyObject obj: pools[0].keySet()) {
traverse(obj, ReachableFinder.defaultInstance, pools);
@@ -2780,7 +2790,7 @@
return;
}
/* Search contains the cyclic objects that participate in a cycle with start,
- * i.e. which are reachable from start AND can reach start.
+ * i.e. which are reachable from start AND can reach start.
* Mark these...
*/
CycleMarkAttr cm;
@@ -2880,12 +2890,16 @@
if (ob instanceof Traverseproc) {
retVal = ((Traverseproc) ob).traverse(visit, arg);
traversed = true;
- if (retVal != 0) return retVal;
+ if (retVal != 0) {
+ return retVal;
+ }
}
if (ob instanceof TraverseprocDerived) {
retVal = ((TraverseprocDerived) ob).traverseDerived(visit, arg);
traversed = true;
- if (retVal != 0) return retVal;
+ if (retVal != 0) {
+ return retVal;
+ }
}
boolean justAddedWarning = false;
if ((gcFlags & SUPPRESS_TRAVERSE_BY_REFLECTION_WARNING) == 0) {
@@ -3064,7 +3078,7 @@
return canLinkToPyObject(cls.getComponentType(), false);
}
Class<?> cls2 = cls;
-
+
/* Fail fast if no fields exist in cls: */
int fieldCount = cls2.getDeclaredFields().length;
while (fieldCount == 0 && cls2 != Object.class) {
@@ -3179,6 +3193,7 @@
* Expects arg to be a list-like {@code PyObject} where the
* referents will be inserted.
*/
+ @Override
public int visit(PyObject object, Object arg) {
((org.python.core.PySequenceList) arg).pyadd(object);
return 0;
@@ -3202,6 +3217,7 @@
* Expects arg to be a list-like {@code PyObject} where the
* referents will be inserted.
*/
+ @Override
@SuppressWarnings("unchecked")
public int visit(PyObject object, Object arg) {
IdentityHashMap<PyObject, PyObject>[] reachSearch =
@@ -3217,10 +3233,11 @@
private static class ReachableFinderWeakRefs implements Visitproc {
public static ReachableFinderWeakRefs defaultInstance = new ReachableFinderWeakRefs();
+ @Override
@SuppressWarnings("unchecked")
public int visit(PyObject object, Object arg) {
if (isTraversable(object)) {
- IdentityHashMap<PyObject, WeakReferenceGC>[] pools =
+ IdentityHashMap<PyObject, WeakReferenceGC>[] pools =
(IdentityHashMap<PyObject, WeakReferenceGC>[]) arg;
WeakReferenceGC ref = pools[0].get(object);
if (ref == null) {
@@ -3241,6 +3258,7 @@
* {@code arg[0]} and the destination list (a list-like {@code PyObject}
* where the referrers will be inserted) at {@code arg[1]}.
*/
+ @Override
public int visit(PyObject object, Object arg) {
if (((PyObject[]) arg)[0].__eq__(object).__nonzero__()) {
((org.python.core.PySequenceList) ((PyObject[]) arg)[1]).pyadd(object);
@@ -3258,6 +3276,7 @@
private static class RefersToSetFinder implements Visitproc {
public static RefersToSetFinder defaultInstance = new RefersToSetFinder();
+ @Override
@SuppressWarnings("unchecked")
public int visit(PyObject object, Object arg) {
return ((Set<PyObject>) arg).contains(object) ? 1 : 0;
@@ -3287,6 +3306,7 @@
* Expects {@code arg} to be a 2-component array of
* {@link java.util.Map}s.
*/
+ @Override
public int visit(PyObject object, Object arg) {
@SuppressWarnings("unchecked")
IdentityHashMap<PyObject, WeakReferenceGC>[] pools =
@@ -3308,6 +3328,7 @@
* Expects {@code arg} to be a 2-component array of
* {@link java.util.Map}s.
*/
+ @Override
public int visit(PyObject object, Object arg) {
@SuppressWarnings("unchecked")
IdentityHashMap<PyObject, PyObject>[] pools =
diff --git a/src/org/python/util/InteractiveConsole.java b/src/org/python/util/InteractiveConsole.java
--- a/src/org/python/util/InteractiveConsole.java
+++ b/src/org/python/util/InteractiveConsole.java
@@ -34,7 +34,7 @@
/**
* Construct an interactive console, which will "run" when {@link #interact()} is called. The
- * name of the console (e.g. in error messages) will be {@value #CONSOLE_FILENAME}.
+ * name of the console (e.g. in error messages) will be {@link #CONSOLE_FILENAME}.
*/
public InteractiveConsole() {
this(null, CONSOLE_FILENAME);
@@ -42,7 +42,7 @@
/**
* Construct an interactive console, which will "run" when {@link #interact()} is called. The
- * name of the console (e.g. in error messages) will be {@value #CONSOLE_FILENAME}.
+ * name of the console (e.g. in error messages) will be {@link #CONSOLE_FILENAME}.
*
* @param locals dictionary to use, or if <code>null</code>, a new empty one will be created
*/
diff --git a/src/org/python/util/PythonInterpreter.java b/src/org/python/util/PythonInterpreter.java
--- a/src/org/python/util/PythonInterpreter.java
+++ b/src/org/python/util/PythonInterpreter.java
@@ -198,8 +198,8 @@
}
/**
- * Sets a {@link Writer} to use for the standard output stream, <code>sys.stdout</code>. The
- * behaviour as implemented is to output each object <code>o</code> by calling
+ * Sets a {@link java.io.Writer} to use for the standard output stream, <code>sys.stdout</code>.
+ * The behaviour as implemented is to output each object <code>o</code> by calling
* <code>o.toString()</code> and writing this as UTF-16.
*
* @param outStream to use as the output stream
@@ -229,8 +229,8 @@
}
/**
- * Sets a {@link Writer} to use for the standard output stream, <code>sys.stdout</code>. The
- * behaviour as implemented is to output each object <code>o</code> by calling
+ * Sets a {@link java.io.Writer} to use for the standard output stream, <code>sys.stdout</code>.
+ * The behaviour as implemented is to output each object <code>o</code> by calling
* <code>o.toString()</code> and writing this as UTF-16.
*
* @param outStream to use as the error output stream
--
Repository URL: https://hg.python.org/jython
More information about the Jython-checkins
mailing list