javadocs / java warnings (jdk8) fixes

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1747327 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/poi/ddf/AbstractEscherOptRecord.java

@@ -35,6 +35,8 @@ public abstract class AbstractEscherOptRecord extends EscherRecord
 
     /**
      * Add a property to this record.
+     * 
+     * @param prop the escher property to add
      */
     public void addEscherProperty( EscherProperty prop )
     {

src/java/org/apache/poi/ddf/EscherBSERecord.java

@@ -337,6 +337,8 @@ public final class EscherBSERecord extends EscherRecord {
 
     /**
      * Any remaining data in this record.
+     * 
+     * @return the remaining bytes
      */
     public byte[] getRemainingData() {
         return _remainingData;
@@ -344,6 +346,8 @@ public final class EscherBSERecord extends EscherRecord {
 
     /**
      * Any remaining data in this record.
+     * 
+     * @param remainingData the remaining bytes
      */
     public void setRemainingData(byte[] remainingData) {
         if (remainingData == null) {

src/java/org/apache/poi/ddf/EscherContainerRecord.java

@@ -129,6 +129,8 @@ public final class EscherContainerRecord extends EscherRecord {
     /**
      * Do any of our (top level) children have the given recordId?
      * 
+     * @param recordId the recordId of the child
+     * 
      * @return true, if any child has the given recordId
      */
     public boolean hasChildOfType(short recordId) {
@@ -187,8 +189,9 @@ public final class EscherContainerRecord extends EscherRecord {
 
     /**
      * Returns all of our children which are also
-     *  EscherContainers (may be 0, 1, or vary rarely
+     * EscherContainers (may be 0, 1, or vary rarely 2 or 3)
-     *   2 or 3)
+     * 
+     * @return EscherContainer children
      */
     public List<EscherContainerRecord> getChildContainers() {
         List<EscherContainerRecord> containers = new ArrayList<EscherContainerRecord>();

src/java/org/apache/poi/ddf/EscherDump.java

@@ -29,8 +29,6 @@ import java.util.zip.InflaterInputStream;
 
 /**
  * Used to dump the contents of escher records to a PrintStream.
- *
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class EscherDump {
 
@@ -66,6 +64,9 @@ public final class EscherDump {
      * @param maxLength The number of bytes to read
      * @param in        An input stream to read from.
      * @param out       An output stream to write to.
+     * 
+     * @throws IOException
+     * @throws LittleEndian.BufferUnderrunException
      */
     public void dumpOld(long maxLength, InputStream in, PrintStream out)
             throws IOException, LittleEndian.BufferUnderrunException {
@@ -775,6 +776,8 @@ public final class EscherDump {
 
     /**
      * A simple test stub.
+     * 
+     * @param args the args
      */
     public static void main( String[] args ) {
         main(args, System.out);

src/java/org/apache/poi/ddf/EscherProperty.java

@@ -21,8 +21,6 @@ package org.apache.poi.ddf;
  * This is the abstract base class for all escher properties.
  *
  * @see EscherOptRecord
- *
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public abstract class EscherProperty {
     private short  _id;
@@ -30,6 +28,8 @@ public abstract class EscherProperty {
     /**
      * The id is distinct from the actual property number.  The id includes the property number the blip id
      * flag and an indicator whether the property is complex or not.
+     * 
+     * @param id the combined id
      */
     public EscherProperty(short id) {
         _id   = id;
@@ -38,6 +38,10 @@ public abstract class EscherProperty {
     /**
      * Constructs a new escher property.  The three parameters are combined to form a property
      * id.
+     * 
+     * @param propertyNumber the property number
+     * @param isComplex true, if this is a complex property
+     * @param isBlipId true, if this property is a blip id
      */
     public EscherProperty(short propertyNumber, boolean isComplex, boolean isBlipId) {
         _id   = (short)(propertyNumber +
@@ -68,6 +72,8 @@ public abstract class EscherProperty {
     /**
      * Most properties are just 6 bytes in length.  Override this if we're
      * dealing with complex properties.
+     * 
+     * @return size of this property (in bytes)
      */
     public int getPropertySize() {
         return 6;
@@ -83,11 +89,22 @@ public abstract class EscherProperty {
     /**
      * Escher properties consist of a simple fixed length part and a complex variable length part.
      * The fixed length part is serialized first.
+     * 
+     * @param data the buffer to write to
+     * @param pos the starting position
+     * 
+     * @return the length of the part
      */
     abstract public int serializeSimplePart( byte[] data, int pos );
+    
     /**
      * Escher properties consist of a simple fixed length part and a complex variable length part.
      * The fixed length part is serialized first.
+     * 
+     * @param data the buffer to write to
+     * @param pos the starting position
+     * 
+     * @return the length of the part
      */
     abstract public int serializeComplexPart( byte[] data, int pos );
 }