Commit 52eecd09 authored by pcregut's avatar pcregut

Javadoc fixes (indigo is

stricter).
parent 3d9bc541
......@@ -79,7 +79,7 @@ public abstract class AnnotationVisitor {
* @param value the actual value, whose type must be {@link Byte},
* {@link Boolean}, {@link Character}, {@link Short},
* {@link Integer}, {@link Long}, {@link Float}, {@link Double},
* {@link String} or {@link Type}. This value can also be an array
* {@link String} or {@link java.lang.reflect.Type}. This value can also be an array
* of byte, boolean, short, char, int, long, float or double values
* (this is equivalent to using {@link #visitArray visitArray} and
* visiting each array element in turn, but is more convenient).
......@@ -125,7 +125,7 @@ public abstract class AnnotationVisitor {
* Visits an array value of the annotation. Note that arrays of primitive
* types (such as byte, boolean, short, char, int, long, float or double)
* can be passed as value to {@link #visit visit}. This is what
* {@link ClassReader} does.
* {@link ClassVisitor} does.
*
* @param name the value name.
* @return a visitor to visit the actual array value elements, or
......
......@@ -307,7 +307,7 @@ public class ApplicationReader {
* This application is the one specified in the constructor (see
* {@link #ApplicationReader(byte[]) ApplicationReader}).
*
* @param classVisitor the visitor that must visit this class.
* @param applicationVisitor the visitor that must visit this class.
* @param classesToVisit the names of the classes to visit, or Null to visit
* all the classes of the application.
* @param flags option flags that can be used to modify the default behavior
......@@ -325,7 +325,7 @@ public class ApplicationReader {
* This application is the one specified in the constructor (see
* {@link #ApplicationReader(byte[]) ApplicationReader}).
*
* @param classVisitor the visitor that must visit this class.
* @param applicationVisitor the visitor that must visit this class.
* @param flags option flags that can be used to modify the default behavior
* of this class. See {@link #SKIP_DEBUG}, {@link #SKIP_CODE}.
*/
......@@ -335,9 +335,8 @@ public class ApplicationReader {
}
/**
* Makes the given visitor visit the Java class of this {@link ClassReader}.
* This class is the one specified in the constructor (see
* {@link #ClassReader(byte[]) ClassReader}).
* Makes the given visitor visit the Java class of this {@link ClassVisitor}.
* This class is the one specified in the constructor
*
* @param applicationVisitor the visitor that must visit this Application.
* @param classesToVisit the names of the classes to visit, or null to visit
......@@ -1525,7 +1524,7 @@ public class ApplicationReader {
/**
* Copies the constant pool data into the given {@link ApplicationWriter}. Should
* be called before the {@link #accept(ApplicationWriter)} method.
* be called before the {@link #accept(ApplicationVisitor,int)} method.
*
* However, contrary to ASM, only the Strings, Types, Fields and Methods indexes are actually copied,
* because that's the only things the methods are referring to. Also note that the elements given to
......
......@@ -213,8 +213,7 @@ public class ApplicationWriter extends ApplicationVisitor {
* without emiting visit events for all the method instructions), which
* saves a <i>lot</i> of time. Untransformed methods are detected by the
* fact that the {@link ApplicationReader} receives {@link MethodVisitor} objects
* that come from a {@link ApplicationWriter} (and not from a custom
* {@link ApplicationAdapter} or any other {@link ApplicationVisitor} instance).</li>
* that come from a {@link ApplicationWriter} (and not from any other {@link ApplicationVisitor} instance).</li>
* </ul>
*
* @param applicationReader the {@link ApplicationReader} used to read the original
......
......@@ -126,10 +126,25 @@ public class MethodCodeReader {
/*
* The five "state machine" registers of the debug_info_item.
*/
/**
* register of debug state machine : the debug address
*/
protected int debugAddress;
/**
* register of debug state machine : the debug line
*/
protected int debugLine;
/**
* register of debug state machine : the source file
*/
protected String debugSourceFile;
/**
* register of debug state machine : the prologue end
*/
protected boolean debugPrologueEnd;
/**
* register of debug state machine : the epilogue end
*/
protected boolean debugEpilogueBegin;
/**
......@@ -176,8 +191,7 @@ public class MethodCodeReader {
/**
* Constructor of the MethodCodeReader.
* @param reader reader of the Dex file. Its position <i>will</i> change.
* @param applicationReader the application reader the method is linked to.
* @param dexFile the Dex file.
* @param methodVisitor visitor to visit the instructions of the code of the method.
* @param codeOffset offset of the code of the method inside the Dex file. May be 0 if
* the method is abstract or native.
......
......@@ -49,7 +49,7 @@ public class DebugInstructionAdvancePC extends DebugInstruction implements IDebu
/**
* Constructor of the Debug Instruction.
* @param difference difference in words between the current and next address.
* @param differenceAddress difference in words between the current and next address.
*/
public DebugInstructionAdvancePC(int differenceAddress) {
this.differenceAddress = differenceAddress;
......
......@@ -40,7 +40,7 @@ public interface IDebugRegisterInstruction {
/**
* The id of the register.
* @return
* @return id of register
*/
int getRegister();
......
......@@ -40,7 +40,7 @@ public interface IDebugSourceNameInstruction {
/**
* The name of the source file.
* @return
* @return source file name
*/
String getSourceName();
......
......@@ -40,7 +40,7 @@ public interface IOneRegisterInstruction {
/**
* The index of the register (called A value in Dalvik documentation)
* @return
* @return regoster A index
*/
int getRegisterA();
}
......@@ -40,17 +40,17 @@ public interface IThreeRegistersInstruction {
/**
* Gets the index of first register
* @return
* @return index
*/
int getRegisterA();
/**
* Gets the index of second register
* @return
* @return index
*/
int getRegisterB();
/**
* Gets the index of third register
* @return
* @return index
*/
int getRegisterC();
}
......@@ -40,12 +40,12 @@ public interface ITwoRegistersInstruction {
/**
* Gets the index of first register
* @return
* @return index
*/
int getRegisterA();
/**
* Gets the index of second register
* @return
* @return index
*/
int getRegisterB();
}
......@@ -184,7 +184,7 @@ public abstract class Instruction {
/**
* Returns the size in bytes of the given opcode.
* @param opcode, from 0 to 255.
* @param opcode from 0 to 255.
* @return the size in bytes of the given opcode.
*/
public static byte getInstructionSizeInByte(int opcode) {
......
......@@ -104,16 +104,7 @@ public class InstructionFormat10T extends Instruction implements IOffsetInstruct
return reader.getPos() - 2 + readOffset;
}
/**
* Returns the Offset encoded in the given 16-bit opcode.
* @return the Offset.
*/
// public static int getOffset(int opcode) {
// return (byte)((opcode >> 8) & 0xff) * 2; // * 2 because branch offsets are word based.
// }
public static void skip(IDalvikValueReader reader) {
}
/**
* Constructor of the Instruction by providing all the elements it's composed of.
......
......@@ -32,7 +32,6 @@
package org.ow2.asmdex.instruction;
import org.ow2.asmdex.lowLevelUtils.ByteVector;
import org.ow2.asmdex.lowLevelUtils.IDalvikValueReader;
import org.ow2.asmdex.structureWriter.ConstantPool;
/**
......@@ -47,18 +46,7 @@ public class InstructionFormat10X extends Instruction {
*/
private static final int INSTRUCTION_SIZE = 2;
/**
* Constructor of the Instruction, using a Reader to parse its bytecode.
* @param reader reader on the Instruction to parse, pointing after the 16-bit opcode.
* @param opcode 16-bit opcode.
*/
// public InstructionFormat10X(IDalvikValueReader reader, int opcode) {
// super(opcode);
// }
public static void skip(IDalvikValueReader reader) {
}
/**
* Constructor of the Instruction by providing all the elements it's composed of.
* @param opcode 8 or 16 bits opcode.
......
......@@ -79,7 +79,6 @@ implements IOneRegisterInstruction, ILiteralInstruction {
/**
* Constructor of the Instruction by providing all the elements it's composed of.
* @param reader reader on the Instruction to parse, pointing after the 16-bit opcode.
* @param opcode 8 or 16 bits opcode.
* @param destinationRegister the destination register.
* @param var the literal to store.
......
......@@ -76,7 +76,7 @@ public class InstructionFormat12X extends Instruction implements ITwoRegistersIn
* Constructor of the Instruction by providing all the elements it's composed of.
* @param opcode 8 or 16 bits opcode.
* @param destinationRegister the destination register.
* @param register the register.
* @param var the register.
*/
public InstructionFormat12X(int opcode, int destinationRegister, int var) {
super(opcode);
......
......@@ -112,7 +112,7 @@ implements ITwoRegistersInstruction, ILiteralInstruction {
/**
* Returns the LiteralC encoded inside the given value, that should contained both RegisterB and LiteralC
* from the getEncodedRegisterBAndLiteralC method.
* @param encodedRegisterBAndLiteralC the RegisterB and LiteralC encoded as an int.
* @param encodedRegisterBAndC the RegisterB and LiteralC encoded as an int.
* @return the LiteralC.
*/
public static int getLiteralCFromEncodedRegisterBAndLiteralC(int encodedRegisterBAndC) {
......
......@@ -47,6 +47,9 @@ public class BasicDexFileReader {
*/
public final static int NO_INDEX = 0xFFFFFFFF;
/**
* The stream of code.
*/
protected DalvikValueReader reader;
private byte[] magic = new byte[8];
......@@ -58,9 +61,21 @@ public class BasicDexFileReader {
private static final int OFFSET_FORMAT_VERSION_NUMBER_IN_MAGIC_SEQUENCE = 4;
private static final int LENGTH_FORMAT_VERSION_NUMBER_IN_MAGIC_SEQUENCE = 3;
protected final static int FILE_SIZE_OFFSET = 32; // Offset to the file_size field.
protected final static int HEADER_NOMINAL_SIZE = 0x70; // Fixed in documentation.
/**
* Offset to the file size field
*/
protected final static int FILE_SIZE_OFFSET = 32;
/**
* Header size
*/
protected final static int HEADER_NOMINAL_SIZE = 0x70;
/**
* Standard endianess marker
*/
protected final static int STANDARD_ENDIAN_VALUE = 0x12345678;
/**
* Reverse endian marker
*/
protected final static int REVERSE_ENDIAN_VALUE = 0x78563412;
/**
......@@ -88,22 +103,58 @@ public class BasicDexFileReader {
*/
public int linkTableSize;
/**
* Size of string ids table
*/
protected int stringIdsSize;
protected int stringIdsOffset; // Offset of the String Ids list.
/**
* Offset of string ids table
*/
protected int stringIdsOffset;
/**
* Size of type ids table
*/
protected int typeIdsSize;
/**
* Offset of type ids table
*/
protected int typeIdsOffset;
/**
* Size of prototypes ids table
*/
protected int protoIdsSize;
/**
* Offset of prototype ids table
*/
protected int protoIdsOffset;
/**
* Size of field ids table
*/
protected int fieldIdsSize;
/**
* Offset of field ids table
*/
protected int fieldIdsOffset;
/**
* Size of method ids table
*/
protected int methodIdsSize;
/**
* Offset of method ids table
*/
protected int methodIdsOffset;
/**
* Size of class definition table
*/
protected int classDefinitionsSize; // Class_defs_size in the documentation.
/**
* Offset of class definition table
*/
protected int classDefinitionsOffset;
/**
......@@ -123,8 +174,8 @@ public class BasicDexFileReader {
}
/**
* Takes an input stream corresponding to a Dex file and populate the structure.
* @param inputStream input stream of the Dex file to parse.
* Takes a byte array corresponding to a Dex file and populate the structure.
* @param dexBytes the code
* @throws IOException
*/
public void parse(byte[] dexBytes) throws IllegalArgumentException, IOException /*, RefNotFoundException */ {
......@@ -348,7 +399,7 @@ public class BasicDexFileReader {
// ------------------------------------
/**
* Endianess of the file
* @return
* @return true if standard endian
*/
public boolean isStandardEndian() {
return isStandardEndian;
......@@ -356,7 +407,7 @@ public class BasicDexFileReader {
/**
* Number of string ids in the pool
* @return
* @return number
*/
public int getStringIdsSize() {
return stringIdsSize;
......@@ -364,7 +415,7 @@ public class BasicDexFileReader {
/**
* Position of string table
* @return
* @return position
*/
public int getStringIdsOffset() {
return stringIdsOffset;
......@@ -372,7 +423,7 @@ public class BasicDexFileReader {
/**
* Number of type ids.
* @return
* @return positive or null number
*/
public int getTypeIdsSize() {
return typeIdsSize;
......@@ -380,7 +431,7 @@ public class BasicDexFileReader {
/**
* Position of type id table
* @return
* @return positive or null number
*/
public int getTypeIdsOffset() {
return typeIdsOffset;
......@@ -388,7 +439,7 @@ public class BasicDexFileReader {
/**
* Number of prototype ids
* @return
* @return positive or null number
*/
public int getProtoIdsSize() {
return protoIdsSize;
......@@ -396,7 +447,7 @@ public class BasicDexFileReader {
/**
* Position of prototype ids table
* @return
* @return offset
*/
public int getProtoIdsOffset() {
return protoIdsOffset;
......@@ -404,7 +455,7 @@ public class BasicDexFileReader {
/**
* Number of field declaration
* @return
* @return positive or null number
*/
public int getFieldIdsSize() {
return fieldIdsSize;
......@@ -412,7 +463,7 @@ public class BasicDexFileReader {
/**
* Position of the field table
* @return
* @return offset
*/
public int getFieldIdsOffset() {
return fieldIdsOffset;
......@@ -420,7 +471,7 @@ public class BasicDexFileReader {
/**
* Number of methods declared
* @return
* @return positive or null number
*/
public int getMethodIdsSize() {
return methodIdsSize;
......@@ -428,7 +479,7 @@ public class BasicDexFileReader {
/**
* Position of the method table
* @return
* @return offset
*/
public int getMethodIdsOffset() {
return methodIdsOffset;
......@@ -436,7 +487,7 @@ public class BasicDexFileReader {
/**
* Number of class declaration
* @return
* @return positive or null number
*/
public int getClassDefinitionsSize() {
return classDefinitionsSize;
......@@ -444,7 +495,7 @@ public class BasicDexFileReader {
/**
* Position of the class table
* @return
* @return offset
*/
public int getClassDefinitionsOffset() {
return classDefinitionsOffset;
......@@ -452,7 +503,7 @@ public class BasicDexFileReader {
/**
* Version of the format used by the file
* @return
* @return enumeration
*/
public byte[] getFormatVersionNumber() {
return formatVersionNumber;
......
......@@ -213,7 +213,7 @@ public class ByteVector {
/**
* The byte vector is <i>not</i> enlarged if necessary.
* @param i an int.
* @param s an int.
* @param position position in byte in the byte vector.
* @return this byte vector.
*/
......
......@@ -46,11 +46,14 @@ import java.util.Arrays;
public class DalvikValueReader implements IDalvikValueReader {
private byte[] contents;
/**
* Position in stream
*/
protected int pos = 0;
/**
* Constructor encapsulating an array of bytes.
* @param stream
* @param contents
*/
public DalvikValueReader(byte[] contents) {
this.contents = contents;
......@@ -94,7 +97,7 @@ public class DalvikValueReader implements IDalvikValueReader {
* Reads an integer directly from an input stream. Usually used
* while builder the value reader.
* @param stream
* @return
* @return the value read
* @throws IOException
*/
final public static int sint(InputStream stream) throws IOException {
......@@ -256,7 +259,7 @@ public class DalvikValueReader implements IDalvikValueReader {
* Extends a long read with SizedLong of length sz according to its sign.
* @param l
* @param sz size-1 of the encoded number.
* @return
* @return the value read
*/
final public long completeSignSizedLong(long l, int sz) {
sz++;
......
......@@ -56,6 +56,9 @@ public class DexFileReader extends BasicDexFileReader implements IDalvikValueRea
*/
private byte[] contents;
/**
* position
*/
protected int pos = 0;
/**
......@@ -397,7 +400,7 @@ public class DexFileReader extends BasicDexFileReader implements IDalvikValueRea
* Reads an integer directly from an input stream. Usually used
* while builder the value reader.
* @param stream
* @return
* @return an integer signed
* @throws IOException
*/
final public static int sint(InputStream stream) throws IOException {
......@@ -560,7 +563,7 @@ public class DexFileReader extends BasicDexFileReader implements IDalvikValueRea
* Extends a long read with SizedLong of length sz according to its sign.
* @param l
* @param sz size-1 of the encoded number.
* @return
* @return a long
*/
final public long completeSignSizedLong(long l, int sz) {
sz++;
......@@ -571,7 +574,6 @@ public class DexFileReader extends BasicDexFileReader implements IDalvikValueRea
/**
* Reads a given number of bytes.
* @param b
* @return
*/
public void bytes(byte [] b) {
for(int i=0; i < b.length; i++) b[i] = contents[pos+i];
......
......@@ -31,7 +31,6 @@
package org.ow2.asmdex.lowLevelUtils;
import java.io.IOException;
/**
* Interface to the DalvikValueReader.
......@@ -49,7 +48,6 @@ public interface IDalvikValueReader {
/**
* Reads next signed byte value.
* @return value read from stream
* @throws IOException
*/
public abstract byte sbyte();
......@@ -109,8 +107,8 @@ public interface IDalvikValueReader {
/**
* Reads a long of a given size. Considered as unsigned.
* @param l
* @return
* @param sz
* @return a positive long
*/
public abstract long sizedLong(int sz);
......@@ -118,19 +116,19 @@ public interface IDalvikValueReader {
* Extends a long read with SizedLong of length sz according to its sign.
* @param l
* @param sz
* @return
* @return long value
*/
public abstract long completeSignSizedLong(long l, int sz);
/**
* Reads a null terminated UTF8 string as handled by Dalvik (limited to unicode)
* @return
* @return string
*/
public abstract String utf8String();
/**
* Set the position of the pointer in the stream.
* @param pos
* @param pos positive absolute position
*/
public abstract void seek(int pos);
......@@ -142,20 +140,20 @@ public interface IDalvikValueReader {
/**
* Get the current position of the pointer in the stream. Usually to make a save restore.
* @return
* @return positive absolute position
*/
public abstract int getPos();
/**
* Parse a string coded as 16 bit character
* @param strSize
* @return
* @return string
*/
public abstract String unicodeString(int strSize);
/**
* Check if there are still data to read in the stream.
* @return
* @return true if more data
*/
public abstract boolean hasMore();
......
......@@ -85,7 +85,7 @@ public class InstructionEncoder {
* @param opcode
* @param method
* @param arguments
* @return
* @return abstract instruction
*/
public static Instruction encodeMethodInsn(int opcode, Method method, int[] arguments) {
// The opcode could be about an invoke Instruction, or an invoke/range.
......@@ -101,7 +101,7 @@ public class InstructionEncoder {
* @param opcode
* @param destinationRegister
* @param var
* @return
* @return instruction encoded
*/
public static Instruction encodeVarInsn(int opcode, int destinationRegister, int var) {
Instruction insn = null;
......@@ -158,7 +158,7 @@ public class InstructionEncoder {
* @param opcode
* @param destinationRegister
* @param var
* @return
* @return abstract instruction
*/
public static Instruction encodeVarInsn(int opcode, int destinationRegister, long var) {
Instruction insn = null;
......@@ -212,7 +212,7 @@ public class InstructionEncoder {
/**
* Encode instructions without args
* @param opcode
* @return
* @return abstract instruction
*/
public static Instruction encodeInsn(int opcode) {
return new InstructionFormat10X(opcode);
......@@ -225,7 +225,7 @@ public class InstructionEncoder {
* @param firstSourceRegister
* @param secondSourceRegister
* @param value
* @return
* @return abstract instruction
*/
public static Instruction encodeOperationInsn(int opcode, int destinationRegister,
int firstSourceRegister, int secondSourceRegister, int value) {
......@@ -258,7 +258,7 @@ public class InstructionEncoder {
* Unary instruction
* @param opcode
* @param operand
* @return
* @return abstract instruction
*/
public static Instruction encodeIntInsn(int opcode, int operand) {
return new InstructionFormat11X(opcode, operand);
......@@ -271,7 +271,7 @@ public class InstructionEncoder {
* @param registerA
* @param registerB
* @param instructionOffset
* @return
* @return abstract instruction
*/
public static Instruction encodeJumpInsn(int opcode, Label label, int registerA,
int registerB, int instructionOffset) {
......@@ -302,7 +302,7 @@ public class InstructionEncoder {
* @param arrayReference
* @param arrayLabel
* @param instructionOffset
* @return
* @return abstract instruction
*/
public static Instruction encodeFillArrayDataInsn(int opcode, int arrayReference,
Label arrayLabel, int instructionOffset) {
......@@ -316,7 +316,7 @@ public class InstructionEncoder {
* @param referenceBearingRegister
* @param sizeRegister
* @param type
* @return
* @return abstract instruction
*/
public static Instruction encodeTypeInsn(int opcode, int destinationRegister,
int referenceBearingRegister, int sizeRegister, String type) {
......@@ -344,7 +344,7 @@ public class InstructionEncoder {
* Multi new array
* @param type
* @param registers