From jython-checkins at python.org Fri Aug 3 18:04:10 2018 From: jython-checkins at python.org (jeff.allen) Date: Fri, 03 Aug 2018 22:04:10 +0000 Subject: [Jython-checkins] =?utf-8?q?jython=3A_Separate_main_and_test_mat?= =?utf-8?q?erial_into_JARs_during_Gradle_build=2E?= Message-ID: <20180803220410.1.7727BED24C558030@mg.python.org> https://hg.python.org/jython/rev/ed155b929cf7 changeset: 8178:ed155b929cf7 user: Jeff Allen date: Fri Aug 03 07:15:42 2018 +0100 summary: Separate main and test material into JARs during Gradle build. files: build.gradle | 133 +++++++++++++++++++++++++++----------- 1 files changed, 93 insertions(+), 40 deletions(-) diff --git a/build.gradle b/build.gradle --- a/build.gradle +++ b/build.gradle @@ -43,6 +43,7 @@ // Valid examples (please preserve in comments): //version = '2.7.2a2' +//version = '2.7.2b1-SNAPSHOT' //version = '2.7.2b1' //version = '2.7.2rc1' //version = '2.7.2' @@ -56,6 +57,9 @@ sourceCompatibility = '1.7' targetCompatibility = '1.7' +project.compileJava.options.debug = true + + // Separate the Gradle build from that of Ant buildDir = file('build2') ext { @@ -70,8 +74,11 @@ unexposedDir = "$buildDir/unexposed" exposedDir = "$buildDir/exposed" // The standard library may safely be assembled in-place as a resource + pythonLibDir = "$buildDir/python/Lib/" buildLibDir = "$buildDir/resources/main/Lib/" + buildTestLibDir = "$buildDir/resources/test/Lib/" compiledLibDir = "$buildDir/resources/main/Lib/" + compiledTestLibDir = "$buildDir/resources/test/Lib/" } @@ -191,15 +198,14 @@ generateGrammarSource { maxHeapSize = "512m" - outputDirectory = file(project.ext.antlrGenDir) + outputDirectory = file(antlrGenDir) } -// ---------------- compleJava Task ------------------------------------------------- +// ---------------- compleJava Task -------------------------------------------- compileJava { // Divert compiled classes to intermediate location pre-exposure. - destinationDir = file(project.ext.unexposedDir) - println "compileJava.destinationDir = $destinationDir}" + destinationDir = file(unexposedDir) } // ---------------- Expose Task ------------------------------------------------ @@ -216,7 +222,7 @@ dependencies { // The expose (Ant) task depends on classes compiled to here: - expose files(project.ext.unexposedDir) + expose files(unexposedDir) } // A (Gradle) task to run the Ant task 'expose'. @@ -314,14 +320,6 @@ // In principle it could match more than once: take the leftmost def versionResult = versionMatcher[0] - - // Useful debug - /* - for (int i=0; i < versionResult.size(); i++) { - String part = versionResult[i] - println "versionResult[$i] = $part" - } */ - // . means ..0 String major = versionResult[1] String minor = versionResult[2] @@ -404,6 +402,14 @@ ext { libPython = 'lib-python/2.7' libJython = 'Lib' + libTestSpecs = [ + 'distutils/tests/', + 'email/test/', + 'json/tests/', + 'lib2to3/tests/', + 'unittest/test/', + 'test/' + ] } /* @@ -413,23 +419,22 @@ * Files from the Jython library having the same name (relative path) as one * in CPythonLib.includes thereby take precedence. */ -task copyLib( +task mergePythonLib( type: Copy, - description: 'Merge lib-python and Jython Lib during assembly') { + description: 'Merge lib-python and Jython Lib') { - into "${project.ext.buildLibDir}" + // There might be a way using a collection of File rather than actual copy. + into pythonLibDir // Copy Jython Lib, with precedence over CPython files of the same name - from file(project.ext.libJython) - exclude 'test/' + duplicatesStrategy = DuplicatesStrategy.INCLUDE + from libJython exclude '**/*.class' - duplicatesStrategy = DuplicatesStrategy.INCLUDE // Allow Gradle to infer the need to regenerate the outputs - inputs.dir project.ext.libJython - inputs.dir project.ext.libPython + inputs.dir libJython + inputs.dir libPython inputs.file file('CPythonLib.includes') - outputs.dir project.ext.buildLibDir doFirst { // Select the CPython stdlib files by making a list. @@ -443,18 +448,51 @@ } // Copy the subset as specified by the list project.copy { - into project.ext.buildLibDir - from file(project.ext.libPython) + into pythonLibDir + duplicatesStrategy = DuplicatesStrategy.EXCLUDE + from libPython include cPythonLibIncludes exclude '**/*.pyc', '**/*.pyd' - duplicatesStrategy = DuplicatesStrategy.EXCLUDE } } } +/* + * Copy from the merge location into the main resources, excluding material + * only needed for tests. + */ +task copyLib( + type: Copy, + dependsOn: mergePythonLib, + description: 'Copy merged Python library (main excluding tests)') { + into buildLibDir + from pythonLibDir + exclude '**/*.pyc', '**/*.pyd', '**/*.class' + // Exclude tests and test material + exclude libTestSpecs +} + // Attach this task to processResources processResources.dependsOn(copyLib) +/* + * Copy from the merge location into the test resopurces, including only + * that extra material needed for tests. + */ +task copyTestLib( + type: Copy, + dependsOn: mergePythonLib, + description: 'Copy merged Python library (tests only)') { + into buildTestLibDir + from pythonLibDir + exclude '**/*.pyd', '**/*.class' // test material includes .pyc files + // Include only tests and test material + include libTestSpecs +} + +// Attach this task to processResources +processTestResources.dependsOn(copyTestLib) + // ---------------- Jython-Compile Python -------------------------------------- @@ -528,11 +566,10 @@ excludes: exclusions.join(',') // Yes, it's that way round :o ) } - } -// ---------------- Building the JAR ------------------------------------------- +// ---------------- Building the JARs ------------------------------------------ /* * The default behaviour of the Java plug-in is to make a JAR of the classes in @@ -552,15 +589,6 @@ // We don't JAR the expose tool itself exclude 'org/python/expose/generate/**' - // Exclude tests and test material from the main JAR - exclude 'Lib/distutils/tests/' - exclude 'Lib/email/test/' - exclude 'Lib/json/tests/' - exclude 'Lib/lib2to3/tests/' - exclude 'Lib/unittest/tests/' - exclude 'Lib/test/' - // XXX is this not more naturally done by having separate test resources? - // Build a custom manifest manifest { // These attribute values are based on inspecting the ant build @@ -573,14 +601,38 @@ 'version': project.version, 'build-compiler': 'modern', 'jdk-target-version': project.targetCompatibility, - 'debug': true, + 'debug': compileJava.options.debug ], 'Build-Info' ) } +} + +/* + * This is a task complementary to the jar task, taking just the test material. + * This is not published via the main repositories because it counts as a + * distinct needs a distinct artefact with its own POM. + */ +task testJar(type: Jar) { + classifier = 'tests' - doFirst { - println "jar: for ${archiveName}" + from sourceSets.test.output + // We don't JAR the expose tool, so we don't JAR the tests + exclude 'org/python/expose/generate/**' + + // Build a custom manifest + manifest { + // These attribute values are based on inspecting the ant build + attributes ([ + //'Main-Class': 'org.python.util.jython', + 'Built-By': 'build.gradle', + ]) + + attributes( [ // Build-Info section + 'version': project.version, + 'build-compiler': 'modern', + 'jdk-target-version': project.targetCompatibility, + 'debug': compileTestJava.options.debug + ], 'Build-Info' ) } - } @@ -666,6 +718,7 @@ compileTestJava { dependsOn expose + options.debug = project.compileJava.options.debug } test { -- Repository URL: https://hg.python.org/jython From jython-checkins at python.org Sun Aug 12 02:08:45 2018 From: jython-checkins at python.org (jeff.allen) Date: Sun, 12 Aug 2018 06:08:45 +0000 Subject: [Jython-checkins] =?utf-8?q?jython=3A_Fix_all_present_irregulari?= =?utf-8?q?ties_in_the_javadoc?= Message-ID: <20180812060845.1.D15977B1C88C393B@mg.python.org> https://hg.python.org/jython/rev/134c5c8c2332 changeset: 8179:134c5c8c2332 user: Jeff Allen 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("", 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 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 @@ * org.python.proxies.(superclassName) with superclass 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 * declaringClass 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, "", 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 seen. */ 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("", sig, access); callSuper(code, "", 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 __new__ and __init__ 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 __new__ and __init__ 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 __new__ and __init__ 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 null - * @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 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.
+ * 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. + *

* It automatically converts {@code args} to {@link org.python.core.PyObject}s.
- * 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.
+ * 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. + *

* {@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.
+ * 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. + *

* It automatically converts {@code args} to {@link org.python.core.PyObject}s.
* {@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()}.
+ * 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()}. + *

* 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()}.
+ * 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()}. + *

* {@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 (INDIRECT | WRITABLE | FORMAT). Also use this in the request if * you plan only to use the fully-encapsulated API (byteAt, storeAt, * copyTo, copyFrom, 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 (INDIRECT | FORMAT). Also use this in the request if you plan only * to use the fully-encapsulated API (byteAt, copyTo, 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...)}, .
- * 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...)}.
- * {@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}. *

- * 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 Discovering Objects with + * Non-trivial Finalizers). 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. *

*/ @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 PyString (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 @@ *

* 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
*
* org.python.modules._jythonlib:
- * dict_builder - Traverseproc
+ * dict_builder - Traverseproc
*
* org.python.modules._threading:
* Condition - Traverseproc
@@ -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 ByteBuffers that wrap the storage, and a factory * for slices {@link #getBufferSlice(int, int, int, int)}. *

- * 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 bytearray, 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 bytearray'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. *

* 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 @@ *

* 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 null) * @param storage the ByteBuffer 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 v using the codec registered for the encoding. - * The encoding defaults to the system default encoding - * (see {@link codecs#getDefaultEncoding()}). - * The string errors 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 - * ValueError. - * This method is exposed through the _codecs module as - * {@link _codecs#decode(PyString, String, String)}. + * Decode the bytes v using the codec registered for the encoding. The + * encoding defaults to the system default encoding (see + * {@link codecs#getDefaultEncoding()}). The string errors 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 ValueError. 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 ({@link #spec}.align='=') was requested, the * fill character is '0', 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 str.format and unicode.format. * * @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 getLoadPath() { List loadPath = new ArrayList(); @@ -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 generateOutline(String file) throws Exception { - return new Outliner().generate(this, file); + public List 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}. + * + *

+ * The mechanisms for importing modules are in general statically undecidable. We make a + * reasonable effort to follow the most common lookup rules. * - *

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 The + * Import Statement */ 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.

- * - * 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}.

- * - * 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.

+ * An {@code NBinding} collects information about a fully qualified name (qname) in the code graph. + *

+ * 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}. + *

+ * 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