5 Documentation Bugs in Various Classes
The following methods contain documentation bugs relating to Java naming
conventions. The methods either throw an Exception or return an unexpected
value when used as currently documented.
We explain each of these documentation bugs in detail below.
We detected these errors using the Checker Framework
(http://types.cs.washington.edu/checker-framework/).
Attached to this bug report is a patch file that corrects all documentation errors.
Bug #1:
The constructor "org.objectweb.asm.ClassReader.ClassReader(String)" is
documented to take a fully qualified name, however it should take a binary name.
If called as documented (with a fully qualified name that is not also a binary
name) the method throws IOException.
Details: The argument string is transformed into a path (by replacing '.' with
'/' and adding .class at the end). Then this path is passed to
ClassLoader.getResourceAsStream(String) method. This method looks if the file
exists in the file system and if it does not, it returns null. Since the
compiled file generated for an inner class has '$' in it (i.e., they follow the
binary name convention), for inner classes, getResourceAsStream will return
null if called with a path that does not include '$' (but includes '/'
instead). Later the result of getResourceAsStream is passed to
ClassReader.readClass(InputStream). This method throws an IOException if the
input is null.
Bug #2:
The method "String org.objectweb.asm.Type.getClassName()" is documented to
return a fully qualified name, however it should return a binary name.
The return value of the method contradicts the documentation when the type
represents an Object.
Details: When the type is an Object, the first and the last elements of the
'buf' (which is the char array for the underlying field descriptor) is
stripped, and '/' is replaced with '.'. Since field descriptors for inner
classes contains '$', and the operation done on the array does not change this
sign, the resulting string will also contain '$' sign. '$' signs are only
contained in binary names.
Bug #3:
The input for the following programs:
org.objectweb.asm.util.CheckClassAdapter.java
org.objectweb.asm.util.TraceClassVisitor.java
org.objectweb.asm.util.ASMifierClassVisitor.java
are documented as a "fully qualified class name or class file name", however
they should be "binary name or class file name".
The input given to these programs are passed to org.objectweb.asm.ClassReader's
constructor. As explained in bug #1, they should be binary names.