javadoc fixes (jdk8)

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

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

@@ -45,14 +45,6 @@ public class DefaultEscherRecordFactory implements EscherRecordFactory {
         // no instance initialisation
     }
 
-    /**
-     * Generates an escher record including the any children contained under that record.
-     * An exception is thrown if the record could not be generated.
-     *
-     * @param data   The byte array containing the records
-     * @param offset The starting offset into the byte array
-     * @return The generated escher record
-     */
     @Override
     public EscherRecord createRecord(byte[] data, int offset) {
         short options = LittleEndian.getShort( data, offset );

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

@@ -65,8 +65,8 @@ public final class EscherDump {
      * @param in        An input stream to read from.
      * @param out       An output stream to write to.
      * 
-     * @throws IOException
+     * @throws IOException if the data can't be read or written 
-     * @throws LittleEndian.BufferUnderrunException
+     * @throws LittleEndian.BufferUnderrunException if an buffer underrun occurs  
      */
     public void dumpOld(long maxLength, InputStream in, PrintStream out)
             throws IOException, LittleEndian.BufferUnderrunException {

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

@@ -17,16 +17,14 @@
 
 package org.apache.poi.ddf;
 
-import org.apache.poi.util.LittleEndian;
-
 import java.util.ArrayList;
 import java.util.Iterator;
 import java.util.List;
 
+import org.apache.poi.util.LittleEndian;
+
 /**
  * Generates a property given a reference into the byte array storing that property.
- *
- * @author Glen Stampoultzis
  */
 public final class EscherPropertyFactory {
     /**
@@ -34,6 +32,7 @@ public final class EscherPropertyFactory {
      *
      * @param data              The byte array containing the property
      * @param offset            The starting offset into the byte array
+     * @param numProperties     The number of properties to be read
      * @return                  The new properties
      */
     public List<EscherProperty> createProperties(byte[] data, int offset, short numProperties) {
@@ -41,7 +40,6 @@ public final class EscherPropertyFactory {
 
         int pos = offset;
 
-//        while ( bytesRemaining >= 6 )
         for (int i = 0; i < numProperties; i++) {
             short propId;
             int propData;
@@ -49,7 +47,7 @@ public final class EscherPropertyFactory {
             propData = LittleEndian.getInt( data, pos + 2 );
             short propNumber = (short) ( propId & (short) 0x3FFF );
             boolean isComplex = ( propId & (short) 0x8000 ) != 0;
-            boolean isBlipId = ( propId & (short) 0x4000 ) != 0;
+            // boolean isBlipId = ( propId & (short) 0x4000 ) != 0;
 
             byte propertyType = EscherProperties.getPropertyType(propNumber);
             if ( propertyType == EscherPropertyMetaData.TYPE_BOOLEAN )
@@ -71,7 +69,6 @@ public final class EscherPropertyFactory {
                 }
             }
             pos += 6;
-//            bytesRemaining -= 6 + complexBytes;
         }
 
         // Get complex data

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

@@ -31,12 +31,10 @@ import org.apache.poi.util.LittleEndian;
 /**
  * The base abstract record from which all escher records are defined.  Subclasses will need
  * to define methods for serialization/deserialization and for determining the record size.
- *
- * @author Glen Stampoultzis
  */
-public abstract class EscherRecord {
+public abstract class EscherRecord implements Cloneable {
-    private static BitField fInstance = BitFieldFactory.getInstance(0xfff0);
+    private static final BitField fInstance = BitFieldFactory.getInstance(0xfff0);
-    private static BitField fVersion = BitFieldFactory.getInstance(0x000f);
+    private static final BitField fVersion = BitFieldFactory.getInstance(0x000f);
 
     private short _options;
     private short _recordId;
@@ -51,6 +49,10 @@ public abstract class EscherRecord {
     /**
      * Delegates to fillFields(byte[], int, EscherRecordFactory)
      * 
+     * @param data they bytes to serialize from
+     * @param f the escher record factory
+     * @return The number of bytes written.
+     * 
      * @see #fillFields(byte[], int, org.apache.poi.ddf.EscherRecordFactory)
      */
     protected int fillFields( byte[] data, EscherRecordFactory f )
@@ -79,8 +81,7 @@ public abstract class EscherRecord {
      * @return          the number of bytes remaining in this record.  This
      *                  may include the children if this is a container.
      */
-    protected int readHeader( byte[] data, int offset )
+    protected int readHeader( byte[] data, int offset ) {
-    {
         _options = LittleEndian.getShort( data, offset );
         _recordId = LittleEndian.getShort( data, offset + 2 );
         int remainingBytes = LittleEndian.getInt( data, offset + 4 );
@@ -93,15 +94,14 @@ public abstract class EscherRecord {
      * @param offset    the offset to start reading from
      * @return          value of instance part of options field
      */
-    protected static short readInstance( byte data[], int offset )
+    protected static short readInstance( byte data[], int offset ) {
-    {
         final short options = LittleEndian.getShort( data, offset );
         return fInstance.getShortValue( options );
     }
 
     /**
-     * Determine whether this is a container record by inspecting the option
+     * Determine whether this is a container record by inspecting the option field.
-     * field.
+     * 
      * @return  true is this is a container field.
      */
     public boolean isContainerRecord() {
@@ -109,10 +109,9 @@ public abstract class EscherRecord {
     }
 
     /**
-     * <p
+     * Note that <code>options</code> is an internal field.
-     * Note that <code>options</code> is an internal field. Use {@link #setInstance(short)} ()} and
+     * Use {@link #setInstance(short)} ()} and {@link #setVersion(short)} ()} to set the actual fields.
-     *             {@link #setVersion(short)} ()} to set the actual fields.
+     * 
-     * </p>
      * @return The options field for this record. All records have one.
      */
     @Internal
@@ -122,13 +121,13 @@ public abstract class EscherRecord {
     }
 
     /**
-     * Set the options this this record.  Container records should have the
+     * Set the options this this record. Container records should have the
-     * last nibble set to 0xF.
+     * last nibble set to 0xF.<p>
      * 
-     * <p
+     * Note that {@code options} is an internal field.
-     * Note that <code>options</code> is an internal field. Use {@link #getInstance()} and
+     * Use {@link #getInstance()} and {@link #getVersion()} to access actual fields.
-     *             {@link #getVersion()} to access actual fields.
+     * 
-     * </p>
+     * @param options the record options
      */
     @Internal
     public void setOptions( short options ) {
@@ -200,6 +199,8 @@ public abstract class EscherRecord {
 
     /**
      * Sets the record id for this record.
+     * 
+     * @param recordId the record id
      */
     public void setRecordId( short recordId ) {
         _recordId = recordId;
@@ -226,14 +227,21 @@ public abstract class EscherRecord {
 
     /**
      * Escher records may need to be clonable in the future.
+     * 
+     * @return the cloned object
+     * 
+     * @throws CloneNotSupportedException if the subclass hasn't implemented {@link Cloneable}
      */
     @Override
     public EscherRecord clone() throws CloneNotSupportedException {
-        throw new CloneNotSupportedException( "The class " + getClass().getName() + " needs to define a clone method" );
+        return (EscherRecord)super.clone();
     }
 
     /**
      * Returns the indexed child record.
+     * 
+     * @param index the index of the child within the child records
+     * @return the indexed child record
      */
     public EscherRecord getChild( int index ) {
         return getChildRecords().get(index);
@@ -254,6 +262,8 @@ public abstract class EscherRecord {
 
     /**
      * Subclasses should return the short name for this escher record.
+     * 
+     * @return the short name for this escher record
      */
     public abstract String getRecordName();
 
@@ -270,8 +280,7 @@ public abstract class EscherRecord {
     /**
      * Sets the instance part of record
      * 
-     * @param value
+     * @param value instance part value
-     *            instance part value
      */
     public void setInstance( short value )
     {
@@ -291,8 +300,7 @@ public abstract class EscherRecord {
     /**
      * Sets the version part of record
      * 
-     * @param value
+     * @param value version part value
-     *            version part value
      */
     public void setVersion( short value )
     {

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

@@ -20,13 +20,15 @@ package org.apache.poi.ddf;
 /**
  * The escher record factory interface allows for the creation of escher
  * records from a pointer into a data array.
- *
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public interface EscherRecordFactory {
     /**
-     * Create a new escher record from the data provided.  Does not attempt
+     * Generates an escher record including any children contained under that record.
-     * to fill the contents of the record however.
+     * An exception is thrown if the record could not be generated.
+     * 
+     * @param data   The byte array containing the records
+     * @param offset The starting offset into the byte array
+     * @return The generated escher record
      */
     EscherRecord createRecord( byte[] data, int offset );
 }

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

@@ -19,8 +19,6 @@ package org.apache.poi.ddf;
 
 /**
  * Interface for listening to escher serialization events.
- *
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public interface EscherSerializationListener
 {
@@ -29,6 +27,7 @@ public interface EscherSerializationListener
      *
      * @param offset    The position in the data array at which the record will be serialized.
      * @param recordId  The id of the record about to be serialized.
+     * @param record    The record to be serialized
      */
     void beforeRecordSerialize(int offset, short recordId, EscherRecord record);
 
@@ -39,6 +38,7 @@ public interface EscherSerializationListener
      * @param recordId  The id of the record about to be serialized
      * @param size      The number of bytes written for this record.  If it is a container
      *                  record then this will include the size of any included records.
+     * @param record    The record which was serialized
      */
     void afterRecordSerialize(int offset, short recordId, int size, EscherRecord record);
 }

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

@@ -32,6 +32,9 @@ public class EscherSimpleProperty extends 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 property id
+     * @param propertyValue the property value
      */
     public EscherSimpleProperty( short id, int propertyValue )
     {
@@ -40,8 +43,12 @@ public class EscherSimpleProperty extends EscherProperty
     }
 
     /**
-     * Constructs a new escher property.  The three parameters are combined to form a property
+     * Constructs a new escher property.  The three parameters are combined to form a property id.
-     * id.
+     * 
+     * @param propertyNumber the property number
+     * @param isComplex true, if its a complex property
+     * @param isBlipId true, if its a blip
+     * @param propertyValue the property value
      */
     public EscherSimpleProperty( short propertyNumber, boolean isComplex, boolean isBlipId, int propertyValue )
     {

src/java/org/apache/poi/hpsf/DocumentSummaryInformation.java

@@ -39,6 +39,7 @@ public class DocumentSummaryInformation extends SpecialPropertySet
     public static final String DEFAULT_STREAM_NAME =
         "\005DocumentSummaryInformation";
 
+    @Override
     public PropertyIDMap getPropertySetIDMap() {
     	return PropertyIDMap.getDocumentSummaryInformationProperties();
     }
@@ -64,7 +65,7 @@ public class DocumentSummaryInformation extends SpecialPropertySet
 
     
     /**
-     * <p>Returns the category (or <code>null</code>).</p>
+     * <p>Returns the category (or {@code null}).</p>
      *
      * @return The category value
      */
@@ -97,7 +98,7 @@ public class DocumentSummaryInformation extends SpecialPropertySet
 
     /**
      * <p>Returns the presentation format (or
-     * <code>null</code>).</p>
+     * {@code null}).</p>
      *
      * @return The presentation format value
      */
@@ -395,7 +396,7 @@ public class DocumentSummaryInformation extends SpecialPropertySet
 
 
     /**
-     * <p>Returns the heading pair (or <code>null</code>)
+     * <p>Returns the heading pair (or {@code null})
      * <strong>when this method is implemented. Please note that the
      * return type is likely to change!</strong>
      *
@@ -429,7 +430,7 @@ public class DocumentSummaryInformation extends SpecialPropertySet
 
 
     /**
-     * <p>Returns the doc parts (or <code>null</code>)
+     * <p>Returns the doc parts (or {@code null})
      * <strong>when this method is implemented. Please note that the
      * return type is likely to change!</strong>
      *
@@ -465,7 +466,7 @@ public class DocumentSummaryInformation extends SpecialPropertySet
 
 
     /**
-     * <p>Returns the manager (or <code>null</code>).</p>
+     * <p>Returns the manager (or {@code null}).</p>
      *
      * @return The manager value
      */
@@ -497,7 +498,7 @@ public class DocumentSummaryInformation extends SpecialPropertySet
 
 
     /**
-     * <p>Returns the company (or <code>null</code>).</p>
+     * <p>Returns the company (or {@code null}).</p>
      *
      * @return The company value
      */
@@ -563,7 +564,7 @@ public class DocumentSummaryInformation extends SpecialPropertySet
      *  {@link DocumentSummaryInformation} does not contain this char count.</p>
      * <p>This is the whitespace-including version of {@link SummaryInformation#getCharCount()}
      *
-     * @return The character count or <code>null</code>
+     * @return The character count or {@code null}
      */
     public int getCharCountWithSpaces()
     {
@@ -592,9 +593,11 @@ public class DocumentSummaryInformation extends SpecialPropertySet
     
     
     /**
-     * <p>Get if the User Defined Property Set has been updated outside of the 
+     * Get if the User Defined Property Set has been updated outside of the 
-     * Application.</p>
+     * Application.<p>
-     * <p>If it has (true), the hyperlinks should be updated on document load.</p>
+     * If it has (true), the hyperlinks should be updated on document load.
+     * 
+     * @return true, if the hyperlinks should be updated on document load
      */
     public boolean getHyperlinksChanged()
     {
@@ -604,6 +607,8 @@ public class DocumentSummaryInformation extends SpecialPropertySet
     /**
      * Set the flag for if the User Defined Property Set has been updated outside 
      *  of the Application.
+     *  
+     * @param changed true, if the User Defined Property Set has been updated
      */
     public void setHyperlinksChanged(boolean changed)
     {
@@ -623,10 +628,12 @@ public class DocumentSummaryInformation extends SpecialPropertySet
 
     
     /**
-     * <p>Gets the version of the Application which wrote the
+     * Gets the version of the Application which wrote the
      *  Property set, stored with the two high order bytes having the major
-     *  version number, and the two low order bytes the minor version number.</p>
+     *  version number, and the two low order bytes the minor version number.<p>
-     * <p>This will be 0 if no version is set.</p>
+     * This will be 0 if no version is set.
+     * 
+     * @return the Application version
      */
     public int getApplicationVersion()
     {
@@ -637,6 +644,8 @@ public class DocumentSummaryInformation extends SpecialPropertySet
      * Sets the Application version, which must be a 4 byte int with
      *  the  two high order bytes having the major version number, and the 
      *  two low order bytes the minor version number.
+     *  
+     * @param version the Application version
      */
     public void setApplicationVersion(int version)
     {
@@ -655,8 +664,10 @@ public class DocumentSummaryInformation extends SpecialPropertySet
 
     
     /**
-     * <p>Returns the VBA digital signature for the VBA project 
+     * Returns the VBA digital signature for the VBA project 
-     *  embedded in the document (or <code>null</code>).</p>
+     * embedded in the document (or {@code null}).
+     * 
+     * @return the VBA digital signature
      */
     public byte[] getVBADigitalSignature()
     {
@@ -690,7 +701,9 @@ public class DocumentSummaryInformation extends SpecialPropertySet
 
     
     /**
-     * <p>Gets the content type of the file (or <code>null</code>).</p>
+     * Gets the content type of the file (or {@code null}).
+     * 
+     * @return the content type of the file
      */
     public String getContentType()
     {
@@ -699,6 +712,8 @@ public class DocumentSummaryInformation extends SpecialPropertySet
     
     /**
      * Sets the content type of the file
+     * 
+     * @param type the content type of the file
      */
     public void setContentType(String type)
     {
@@ -717,7 +732,9 @@ public class DocumentSummaryInformation extends SpecialPropertySet
 
     
     /**
-     * <p>Gets the content status of the file (or <code>null</code>).</p>
+     * Gets the content status of the file (or {@code null}).
+     * 
+     * @return the content status of the file
      */
     public String getContentStatus()
     {
@@ -725,7 +742,9 @@ public class DocumentSummaryInformation extends SpecialPropertySet
     }
     
     /**
-     * Sets the content type of the file
+     * Sets the content status of the file
+     * 
+     * @param status the content status of the file
      */
     public void setContentStatus(String status)
     {
@@ -744,8 +763,9 @@ public class DocumentSummaryInformation extends SpecialPropertySet
 
     
     /**
-     * <p>Gets the document language, which is normally unset and empty
+     * Gets the document language, which is normally unset and empty (or {@code null}).
-     *  (or <code>null</code>).</p>
+     * 
+     * @return the document language
      */
     public String getLanguage()
     {
@@ -754,6 +774,8 @@ public class DocumentSummaryInformation extends SpecialPropertySet
     
     /**
      * Set the document language
+     * 
+     * @param language the document language
      */
     public void setLanguage(String language)
     {
@@ -773,7 +795,9 @@ public class DocumentSummaryInformation extends SpecialPropertySet
     
     /**
      * <p>Gets the document version as a string, which is normally unset and empty
-     *  (or <code>null</code>).</p>
+     *  (or {@code null}).</p>
+     *  
+     *  @return the document verion
      */
     public String getDocumentVersion()
     {
@@ -782,6 +806,8 @@ public class DocumentSummaryInformation extends SpecialPropertySet
     
     /**
      * Sets the document version string
+     * 
+     * @param version the document version string
      */
     public void setDocumentVersion(String version)
     {

src/java/org/apache/poi/hssf/record/chart/ChartEndObjectRecord.java

@@ -23,9 +23,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * ENDOBJECT - Chart Future Record Type End Object (0x0855)<br/>
+ * ENDOBJECT - Chart Future Record Type End Object (0x0855)
- * 
- * @author Patrick Cheng
  */
 public final class ChartEndObjectRecord extends StandardRecord {
 	public static final short sid = 0x0855;

src/java/org/apache/poi/hssf/record/chart/ChartFRTInfoRecord.java

@@ -24,9 +24,7 @@ import org.apache.poi.util.LittleEndianInput;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * CHARTFRTINFO - Chart Future Record Type Info (0x0850)<br/>
+ * CHARTFRTINFO - Chart Future Record Type Info (0x0850)
- * 
- * @author Patrick Cheng
  */
 public final class ChartFRTInfoRecord extends StandardRecord {
 	public static final short sid = 0x850;

src/java/org/apache/poi/hssf/record/chart/ChartFormatRecord.java

@@ -25,12 +25,10 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * Class ChartFormatRecord (0x1014)<p/>
+ * Class ChartFormatRecord (0x1014)<p>
  *
  * (As with all chart related records, documentation is lacking.
  * See {@link ChartRecord} for more details)
- *
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class ChartFormatRecord extends StandardRecord {
     public static final short sid = 0x1014;

src/java/org/apache/poi/hssf/record/chart/ChartRecord.java

@@ -22,9 +22,9 @@ import org.apache.poi.hssf.record.StandardRecord;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * CHART (0x1002) <p/>
+ * CHART (0x1002)<p>
  * 
- * The chart record is used to define the location and size of a chart.<p/>
+ * The chart record is used to define the location and size of a chart.<p>
  * 
  * Chart related records don't seem to be covered in either the 
  * <A HREF="http://sc.openoffice.org/excelfileformat.pdf">OOO</A> 
@@ -37,8 +37,6 @@ import org.apache.poi.util.LittleEndianOutput;
  * <A HREF="http://ooxmlisdefectivebydesign.blogspot.com/2008/03/bad-surprise-in-microsoft-office-binary.html">blog</A>
  *  suggests that some documentation for these records is available in "MSDN Library, Feb 1998",
  * but no later.
- *  
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class ChartRecord extends StandardRecord implements Cloneable {
     public final static short sid = 0x1002;

src/java/org/apache/poi/hssf/record/chart/ChartStartBlockRecord.java

@@ -23,9 +23,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * STARTBLOCK - Chart Future Record Type Start Block (0x0852)<br/>
+ * STARTBLOCK - Chart Future Record Type Start Block (0x0852)
- * 
- * @author Patrick Cheng
  */
 public final class ChartStartBlockRecord extends StandardRecord implements Cloneable {
 	public static final short sid = 0x0852;

src/java/org/apache/poi/hssf/record/chart/ChartStartObjectRecord.java

@@ -23,9 +23,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * STARTOBJECT - Chart Future Record Type Start Object (0x0854)<br/>
+ * STARTOBJECT - Chart Future Record Type Start Object (0x0854)
- * 
- * @author Patrick Cheng
  */
 public final class ChartStartObjectRecord extends StandardRecord {
 	public static final short sid = 0x0854;

src/java/org/apache/poi/hssf/record/chart/ChartTitleFormatRecord.java

@@ -25,7 +25,7 @@ import org.apache.poi.hssf.record.StandardRecord;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * CHARTTITLEFORMAT (0x1050)<p/>
+ * CHARTTITLEFORMAT (0x1050)<p>
  * Describes the formatting runs associated with a chart title.
  */
 public class ChartTitleFormatRecord extends StandardRecord {

src/java/org/apache/poi/hssf/record/chart/DatRecord.java

@@ -25,9 +25,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * The dat record is used to store options for the chart.<p/>
+ * The dat record is used to store options for the chart.
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class DatRecord extends StandardRecord implements Cloneable {
     public final static short sid = 0x1063;

src/java/org/apache/poi/hssf/record/chart/DataFormatRecord.java

@@ -25,9 +25,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * The data format record is used to index into a series.<p/>
+ * The data format record is used to index into a series.
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class DataFormatRecord extends StandardRecord implements Cloneable {
     public final static short sid = 0x1006;

src/java/org/apache/poi/hssf/record/chart/DataLabelExtensionRecord.java

@@ -23,9 +23,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * DATALABEXT - Chart Data Label Extension (0x086A) <br/>
+ * DATALABEXT - Chart Data Label Extension (0x086A)
- * 
- * @author Patrick Cheng
  */
 public final class DataLabelExtensionRecord extends StandardRecord {
 	public static final short sid = 0x086A;

src/java/org/apache/poi/hssf/record/chart/DefaultDataLabelTextPropertiesRecord.java

@@ -23,9 +23,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * The default data label text properties record identifies the text characteristics of the preceding text record.<p/>
+ * The default data label text properties record identifies the text characteristics of the preceding text record.
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class DefaultDataLabelTextPropertiesRecord extends StandardRecord implements Cloneable {
     public final static short      sid                             = 0x1024;

src/java/org/apache/poi/hssf/record/chart/FontBasisRecord.java

@@ -23,9 +23,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * The font basis record stores various font metrics.<p/>
+ * The font basis record stores various font metrics.
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class FontBasisRecord extends StandardRecord implements Cloneable {
     public final static short sid = 0x1060;

src/java/org/apache/poi/hssf/record/chart/FrameRecord.java

@@ -25,9 +25,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * The frame record indicates whether there is a border around the displayed text of a chart.<p/>
+ * The frame record indicates whether there is a border around the displayed text of a chart.
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class FrameRecord extends StandardRecord implements Cloneable {
     public final static short sid  = 0x1032;

src/java/org/apache/poi/hssf/record/chart/LegendRecord.java

@@ -25,9 +25,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * Defines a legend for a chart.<p/>
+ * Defines a legend for a chart.
- * 
- * @author Andrew C. Oliver (acoliver at apache.org)
  */
 public final class LegendRecord extends StandardRecord implements Cloneable {
     public final static short sid = 0x1015;

src/java/org/apache/poi/hssf/record/chart/LineFormatRecord.java

@@ -25,9 +25,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * Describes a line format record.  The line format record controls how a line on a chart appears.<p/>
+ * Describes a line format record.  The line format record controls how a line on a chart appears.
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class LineFormatRecord extends StandardRecord implements Cloneable {
     public final static short sid = 0x1007;

src/java/org/apache/poi/hssf/record/chart/LinkedDataRecord.java

@@ -27,9 +27,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * Describes a linked data record.  This record refers to the series data or text.<p/>
+ * Describes a linked data record.  This record refers to the series data or text.
- *
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class LinkedDataRecord extends StandardRecord implements Cloneable {
     public final static short sid  = 0x1051;

src/java/org/apache/poi/hssf/record/chart/NumberFormatIndexRecord.java

@@ -23,9 +23,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * The number format index record indexes format table.  This applies to an axis.<p/>
+ * The number format index record indexes format table. This applies to an axis.
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class NumberFormatIndexRecord extends StandardRecord implements Cloneable {
     public final static short      sid                             = 0x104E;

src/java/org/apache/poi/hssf/record/chart/ObjectLinkRecord.java

@@ -23,9 +23,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * Links text to an object on the chart or identifies it as the title.<p/>
+ * Links text to an object on the chart or identifies it as the title.
- * 
- * @author Andrew C. Oliver (acoliver at apache.org)
  */
 public final class ObjectLinkRecord extends StandardRecord implements Cloneable {
     public final static short      sid                             = 0x1027;

src/java/org/apache/poi/hssf/record/chart/PlotAreaRecord.java

@@ -22,9 +22,7 @@ import org.apache.poi.hssf.record.StandardRecord;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * preceeds and identifies a frame as belonging to the plot area.<p/>
+ * preceeds and identifies a frame as belonging to the plot area.
- * 
- * @author Andrew C. Oliver (acoliver at apache.org)
  */
 public final class PlotAreaRecord extends StandardRecord {
     public final static short      sid                             = 0x1035;

src/java/org/apache/poi/hssf/record/chart/PlotGrowthRecord.java

@@ -23,9 +23,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * The plot growth record specifies the scaling factors used when a font is scaled.<p/>
+ * The plot growth record specifies the scaling factors used when a font is scaled.
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class PlotGrowthRecord extends StandardRecord {
     public final static short      sid                             = 0x1064;

src/java/org/apache/poi/hssf/record/chart/SeriesChartGroupIndexRecord.java

@@ -23,9 +23,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * The series chart group index record stores the index to the CHARTFORMAT record (0 based).<p/>
+ * The series chart group index record stores the index to the CHARTFORMAT record (0 based).
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class SeriesChartGroupIndexRecord extends StandardRecord {
     public final static short      sid                             = 0x1045;

src/java/org/apache/poi/hssf/record/chart/SeriesIndexRecord.java

@@ -23,9 +23,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * links a series to its position in the series list.<p/>
+ * links a series to its position in the series list.
- * 
- * @author Andrew C. Oliver (acoliver at apache.org)
  */
 public final class SeriesIndexRecord extends StandardRecord {
     public final static short      sid                             = 0x1065;

src/java/org/apache/poi/hssf/record/chart/SeriesListRecord.java

@@ -24,14 +24,12 @@ import org.apache.poi.hssf.record.StandardRecord;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * SERIESLIST (0x1016)<p/>
+ * SERIESLIST (0x1016)<p>
  * 
- * The series list record defines the series displayed as an overlay to the main chart record.<br/>
+ * The series list record defines the series displayed as an overlay to the main chart record.<p>
  * 
  * (As with all chart related records, documentation is lacking.
  * See {@link ChartRecord} for more details)
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class SeriesListRecord extends StandardRecord {
     public final static short sid = 0x1016;

src/java/org/apache/poi/hssf/record/chart/SeriesRecord.java

@@ -23,9 +23,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * The series record describes the overall data for a series.<p/>
+ * The series record describes the overall data for a series.
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class SeriesRecord extends StandardRecord {
     public final static short      sid                             = 0x1003;

src/java/org/apache/poi/hssf/record/chart/SeriesTextRecord.java

@@ -24,10 +24,8 @@ import org.apache.poi.util.LittleEndianOutput;
 import org.apache.poi.util.StringUtil;
 
 /**
- * SERIESTEXT (0x100D)</p> 
+ * SERIESTEXT (0x100D)<p> 
- * Defines a series name</p>
+ * Defines a series name
- * 
- * @author Andrew C. Oliver (acoliver at apache.org)
  */
 public final class SeriesTextRecord extends StandardRecord {
 	public final static short sid = 0x100D;

src/java/org/apache/poi/hssf/record/chart/SeriesToChartGroupRecord.java

@@ -23,11 +23,9 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * Indicates the chart-group index for a series.  The order probably defines the mapping.  
+ * Indicates the chart-group index for a series. The order probably defines the mapping.  
- * So the 0th record probably means the 0th series.  The only field in this of course defines which chart 
+ * So the 0th record probably means the 0th series. The only field in this of course defines which chart 
- * group the 0th series (for instance) would map to.  Confusing?  Well thats because it is.  (p 522 BCG)<p/>
+ * group the 0th series (for instance) would map to. Confusing?  Well thats because it is.  (p 522 BCG)
- * 
- * @author Andrew C. Oliver (acoliver at apache.org)
  */
 public final class SeriesToChartGroupRecord extends StandardRecord {
     public final static short      sid                             = 0x1045;

src/java/org/apache/poi/hssf/record/chart/SheetPropertiesRecord.java

@@ -25,12 +25,10 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * Describes a chart sheet properties record. SHTPROPS (0x1044) <p/>
+ * Describes a chart sheet properties record. SHTPROPS (0x1044)<p>
  * 
  * (As with all chart related records, documentation is lacking.
  * See {@link ChartRecord} for more details)
- *
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class SheetPropertiesRecord extends StandardRecord {
     public final static short sid = 0x1044;

src/java/org/apache/poi/hssf/record/chart/TextRecord.java

@@ -25,9 +25,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * The text record is used to define text stored on a chart.<p/>
+ * The text record is used to define text stored on a chart.
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class TextRecord extends StandardRecord {
     public final static short      sid                             = 0x1025;

src/java/org/apache/poi/hssf/record/chart/UnitsRecord.java

@@ -23,9 +23,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * The units record describes units.<p/>
+ * The units record describes units.
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class UnitsRecord extends StandardRecord {
     public final static short      sid                             = 0x1001;

src/java/org/apache/poi/hssf/record/chart/ValueRangeRecord.java

@@ -25,9 +25,7 @@ import org.apache.poi.util.HexDump;
 import org.apache.poi.util.LittleEndianOutput;
 
 /**
- * The value range record defines the range of the value axis.<p/>
+ * The value range record defines the range of the value axis.
- * 
- * @author Glen Stampoultzis (glens at apache.org)
  */
 public final class ValueRangeRecord extends StandardRecord {
     public final static short sid = 0x101f;

src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java

@@ -490,32 +490,26 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
     }
 
     /**
-     * Set the width (in units of 1/256th of a character width)
+     * Set the width (in units of 1/256th of a character width)<p>
-     * <p/>
+     * 
-     * <p>
      * The maximum column width for an individual cell is 255 characters.
      * This value represents the number of characters that can be displayed
-     * in a cell that is formatted with the standard font (first font in the workbook).
+     * in a cell that is formatted with the standard font (first font in the workbook).<p>
-     * </p>
+     * 
-     * <p/>
-     * <p>
      * Character width is defined as the maximum digit width
      * of the numbers <code>0, 1, 2, ... 9</code> as rendered
-     * using the default font (first font in the workbook).
+     * using the default font (first font in the workbook).<p>
-     * <br/>
+     * 
      * Unless you are using a very special font, the default character is '0' (zero),
-     * this is true for Arial (default font font in HSSF) and Calibri (default font in XSSF)
+     * this is true for Arial (default font font in HSSF) and Calibri (default font in XSSF)<p>
-     * </p>
+     * 
-     * <p/>
-     * <p>
      * Please note, that the width set by this method includes 4 pixels of margin padding (two on each side),
      * plus 1 pixel padding for the gridlines (Section 3.3.1.12 of the OOXML spec).
-     * This results is a slightly less value of visible characters than passed to this method (approx. 1/2 of a character).
+     * This results is a slightly less value of visible characters than passed to this method (approx. 1/2 of a character).<p>
-     * </p>
+     * 
-     * <p>
      * To compute the actual number of visible characters,
-     * Excel uses the following formula (Section 3.3.1.12 of the OOXML spec):
+     * Excel uses the following formula (Section 3.3.1.12 of the OOXML spec):<p>
-     * </p>
+     * 
      * <code>
      * width = Truncate([{Number of Visible Characters} *
      * {Maximum Digit Width} + {5 pixel padding}]/{Maximum Digit Width}*256)/256
@@ -531,7 +525,7 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
      *
      * @param columnIndex - the column to set (0-based)
      * @param width       - the width in units of 1/256th of a character width
-     * @throws IllegalArgumentException if width > 255*256 (the maximum column width in Excel is 255 characters)
+     * @throws IllegalArgumentException if width &gt; 255*256 (the maximum column width in Excel is 255 characters)
      */
     @Override
     public void setColumnWidth(int columnIndex, int width) {
@@ -809,19 +803,15 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
 
     /**
      * Control if Excel should be asked to recalculate all formulas on this sheet
-     * when the workbook is opened.
+     * when the workbook is opened.<p>
-     * <p/>
+     * 
-     * <p>
      * Calculating the formula values with {@link org.apache.poi.ss.usermodel.FormulaEvaluator} is the
      * recommended solution, but this may be used for certain cases where
-     * evaluation in POI is not possible.
+     * evaluation in POI is not possible.<p>
-     * </p>
+     * 
-     * <p/>
-     * <p>
      * It is recommended to force recalcuation of formulas on workbook level using
      * {@link org.apache.poi.ss.usermodel.Workbook#setForceFormulaRecalculation(boolean)}
      * to ensure that all cross-worksheet formuals and external dependencies are updated.
-     * </p>
      *
      * @param value true if the application will perform a full recalculation of
      *              this worksheet values when the workbook is opened
@@ -1345,7 +1335,7 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
     /**
      * Answer whether protection is enabled or disabled
      *
-     * @return true => protection enabled; false => protection disabled
+     * @return true =&gt; protection enabled; false =&gt; protection disabled
      */
     @Override
     public boolean getProtect() {
@@ -1362,7 +1352,7 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
     /**
      * Answer whether object protection is enabled or disabled
      *
-     * @return true => protection enabled; false => protection disabled
+     * @return true =&gt; protection enabled; false =&gt; protection disabled
      */
     public boolean getObjectProtect() {
         return getProtectionBlock().isObjectProtected();
@@ -1371,7 +1361,7 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
     /**
      * Answer whether scenario protection is enabled or disabled
      *
-     * @return true => protection enabled; false => protection disabled
+     * @return true =&gt; protection enabled; false =&gt; protection disabled
      */
     @Override
     public boolean getScenarioProtect() {
@@ -1412,7 +1402,7 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
     
     /**
      * Window zoom magnification for current view representing percent values.
-     * Valid values range from 10 to 400. Horizontal & Vertical scale together.
+     * Valid values range from 10 to 400. Horizontal &amp; Vertical scale together.
      *
      * For example:
      * <pre>
@@ -1497,11 +1487,10 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
     /**
      * Shifts rows between startRow and endRow n number of rows.
      * If you use a negative number, it will shift rows up.
-     * Code ensures that rows don't wrap around.
+     * Code ensures that rows don't wrap around.<p>
-     * <p/>
+     * 
-     * Calls shiftRows(startRow, endRow, n, false, false);
+     * Calls {@code shiftRows(startRow, endRow, n, false, false);}<p>
-     * <p/>
+     * 
-     * <p/>
      * Additionally shifts merged regions that are completely defined in these
      * rows (ie. merged 2 cells on a row to be shifted).
      *
@@ -1517,12 +1506,11 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
     /**
      * Shifts rows between startRow and endRow n number of rows.
      * If you use a negative number, it will shift rows up.
-     * Code ensures that rows don't wrap around
+     * Code ensures that rows don't wrap around<p>
-     * <p/>
+     * 
-     * <p/>
      * Additionally shifts merged regions that are completely defined in these
-     * rows (ie. merged 2 cells on a row to be shifted).
+     * rows (ie. merged 2 cells on a row to be shifted).<p>
-     * <p/>
+     * 
      * TODO Might want to add bounds checking here
      *
      * @param startRow               the row to start shifting
@@ -1539,12 +1527,11 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
     /**
      * Shifts rows between startRow and endRow n number of rows.
      * If you use a negative number, it will shift rows up.
-     * Code ensures that rows don't wrap around
+     * Code ensures that rows don't wrap around<p>
-     * <p/>
+     * 
-     * <p/>
      * Additionally shifts merged regions that are completely defined in these
-     * rows (ie. merged 2 cells on a row to be shifted).
+     * rows (ie. merged 2 cells on a row to be shifted).<p>
-     * <p/>
+     * 
      * TODO Might want to add bounds checking here
      *
      * @param startRow               the row to start shifting
@@ -1738,11 +1725,9 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
     }
 
     /**
-     * Creates a split (freezepane). Any existing freezepane or split pane is overwritten.
+     * Creates a split (freezepane). Any existing freezepane or split pane is overwritten.<p>
-     * <p/>
+     * 
-     * <p>
      * If both colSplit and rowSplit are zero then the existing freeze pane is removed
-     * </p>
      *
      * @param colSplit       Horizonatal position of split.
      * @param rowSplit       Vertical position of split.
@@ -1761,11 +1746,9 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
     }
 
     /**
-     * Creates a split (freezepane). Any existing freezepane or split pane is overwritten.
+     * Creates a split (freezepane). Any existing freezepane or split pane is overwritten.<p>
-     * <p/>
+     * 
-     * <p>
      * If both colSplit and rowSplit are zero then the existing freeze pane is removed
-     * </p>
      *
      * @param colSplit Horizonatal position of split.
      * @param rowSplit Vertical position of split.
@@ -1866,8 +1849,8 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
 
     /**
      * Sets a page break at the indicated row
-     * Breaks occur above the specified row and left of the specified column inclusive.
+     * Breaks occur above the specified row and left of the specified column inclusive.<p>
-     * <p/>
+     * 
      * For example, <code>sheet.setColumnBreak(2);</code> breaks the sheet into two parts
      * with columns A,B,C in the first and D,E,... in the second. Simuilar, <code>sheet.setRowBreak(2);</code>
      * breaks the sheet into two parts with first three rows (rownum=1...3) in the first part
@@ -1918,10 +1901,10 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
 
     /**
      * Sets a page break at the indicated column.
-     * Breaks occur above the specified row and left of the specified column inclusive.
+     * Breaks occur above the specified row and left of the specified column inclusive.<p>
-     * <p/>
+     * 
      * For example, <code>sheet.setColumnBreak(2);</code> breaks the sheet into two parts
-     * with columns A,B,C in the first and D,E,... in the second. Simuilar, <code>sheet.setRowBreak(2);</code>
+     * with columns A,B,C in the first and D,E,... in the second. Simuilar, {@code sheet.setRowBreak(2);}
      * breaks the sheet into two parts with first three rows (rownum=1...3) in the first part
      * and rows starting with rownum=4 in the second.
      *
@@ -2141,8 +2124,8 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
     }
 
     /**
-     * Adjusts the column width to fit the contents.
+     * Adjusts the column width to fit the contents.<p>
-     * <p/>
+     * 
      * This process can be relatively slow on large sheets, so this should
      * normally only be called once per column, at the end of your
      * processing.
@@ -2155,12 +2138,12 @@ public final class HSSFSheet implements org.apache.poi.ss.usermodel.Sheet {
     }
 
     /**
-     * Adjusts the column width to fit the contents.
+     * Adjusts the column width to fit the contents.<p>
-     * <p/>
+     * 
      * This process can be relatively slow on large sheets, so this should
      * normally only be called once per column, at the end of your
-     * processing.
+     * processing.<p>
-     * <p/>
+     * 
      * You can specify whether the content of merged cells should be considered or ignored.
      * Default is to ignore merged cells.
      *

src/ooxml/java/org/apache/poi/POIXMLProperties.java

@@ -154,10 +154,11 @@ public class POIXMLProperties {
         return name.substring(name.lastIndexOf('/'));
     }
     /**
-     * Returns the Document thumbnail image data, or
+     * Returns the Document thumbnail image data, or {@code null} if there isn't one.
-     *  <code>null</code> if there isn't one.
      *
      * @return The thumbnail data, or null
+     * 
+     * @throws IOException if the thumbnail can't be read
      */
     public InputStream getThumbnailImage() throws IOException {
         PackagePart tPart = getThumbnailPart();
@@ -166,11 +167,12 @@ public class POIXMLProperties {
     }
 
     /**
-     * Sets the Thumbnail for the document, replacing any existing
+     * Sets the Thumbnail for the document, replacing any existing one.
-     *  one.
      *
-     * @param name The filename for the thumbnail image, eg <code>thumbnail.jpg</code>
+     * @param filename The filename for the thumbnail image, eg {@code thumbnail.jpg}
      * @param imageData The inputstream to read the thumbnail image from
+     * 
+     * @throws IOException if the thumbnail can't be written
      */
     public void setThumbnail(String filename, InputStream imageData) throws IOException {
         PackagePart tPart = getThumbnailPart();

src/ooxml/java/org/apache/poi/POIXMLPropertiesTextExtractor.java

@@ -38,8 +38,9 @@ public class POIXMLPropertiesTextExtractor extends POIXMLTextExtractor {
     private final DateFormat dateFormat;
     
 	/**
-	 * Creates a new POIXMLPropertiesTextExtractor for the
+	 * Creates a new POIXMLPropertiesTextExtractor for the given open document.
-	 *  given open document.
+	 * 
+	 * @param doc the given open document
 	 */
 	public POIXMLPropertiesTextExtractor(POIXMLDocument doc) {
 		super(doc);
@@ -52,6 +53,8 @@ public class POIXMLPropertiesTextExtractor extends POIXMLTextExtractor {
 	 * Creates a new POIXMLPropertiesTextExtractor, for the
 	 *  same file that another TextExtractor is already
 	 *  working on.
+	 * 
+	 * @param otherExtractor the extractor referencing the given file
 	 */
 	public POIXMLPropertiesTextExtractor(POIXMLTextExtractor otherExtractor) {
 		this(otherExtractor.getDocument());
@@ -77,6 +80,8 @@ public class POIXMLPropertiesTextExtractor extends POIXMLTextExtractor {
 
 	/**
 	 * Returns the core document properties, eg author
+	 * 
+	 * @return the core document properties
 	 */
 	@SuppressWarnings("resource")
     public String getCorePropertiesText() {
@@ -113,8 +118,9 @@ public class POIXMLPropertiesTextExtractor extends POIXMLTextExtractor {
 		return text.toString();
 	}
 	/**
-	 * Returns the extended document properties, eg
+	 * Returns the extended document properties, eg application
-	 *  application
+	 * 
+	 * @return the extended document properties
 	 */
 	@SuppressWarnings("resource")
     public String getExtendedPropertiesText() {
@@ -146,8 +152,9 @@ public class POIXMLPropertiesTextExtractor extends POIXMLTextExtractor {
 		return text.toString();
 	}
    /**
-    * Returns the custom document properties, if
+    * Returns the custom document properties, if there are any
-    *  there are any
+    * 
+    * @return the custom document properties
     */
    @SuppressWarnings({ "resource" })
    public String getCustomPropertiesText() {

src/ooxml/java/org/apache/poi/POIXMLRelation.java

@@ -18,8 +18,6 @@ package org.apache.poi;
 
 /**
  * Represents a descriptor of a OOXML relation.
- *
- * @author Yegor Kozlov
  */
 public abstract class POIXMLRelation {
 
@@ -100,8 +98,10 @@ public abstract class POIXMLRelation {
     }
 
     /**
-     * Returns the filename for the nth one of these,
+     * Returns the filename for the nth one of these, e.g. /xl/comments4.xml
-     *  e.g. /xl/comments4.xml
+     * 
+     * @param index the suffix for the document type
+     * @return the filename including the suffix
      */
     public String getFileName(int index) {
         if(_defaultName.indexOf("#") == -1) {
@@ -114,6 +114,9 @@ public abstract class POIXMLRelation {
     /**
      * Returns the index of the filename within the package for the given part.
      *  e.g. 4 for /xl/comments4.xml
+     *  
+     * @param part the part to read the suffix from
+     * @return the suffix
      */
     public Integer getFileNameIndex(POIXMLDocumentPart part) {
         String regex = _defaultName.replace("#", "(\\d+)");

src/ooxml/java/org/apache/poi/POIXMLTextExtractor.java

@@ -38,18 +38,24 @@ public abstract class POIXMLTextExtractor extends POITextExtractor {
 
 	/**
 	 * Returns the core document properties
+	 * 
+	 * @return the core document properties
 	 */
 	public CoreProperties getCoreProperties() {
 		 return _document.getProperties().getCoreProperties();
 	}
 	/**
 	 * Returns the extended document properties
+	 * 
+	 * @return the extended document properties
 	 */
 	public ExtendedProperties getExtendedProperties() {
 		return _document.getProperties().getExtendedProperties();
 	}
 	/**
 	 * Returns the custom document properties
+	 * 
+	 * @return the custom document properties
 	 */
 	public CustomProperties getCustomProperties() {
 		return _document.getProperties().getCustomProperties();
@@ -57,6 +63,8 @@ public abstract class POIXMLTextExtractor extends POITextExtractor {
 
 	/**
 	 * Returns opened document
+	 * 
+	 * @return the opened document
 	 */
 	public final POIXMLDocument getDocument() {
 		return _document;
@@ -64,6 +72,8 @@ public abstract class POIXMLTextExtractor extends POITextExtractor {
 
 	/**
 	 * Returns the opened OPCPackage that contains the document
+	 * 
+	 * @return the opened OPCPackage
 	 */
 	public OPCPackage getPackage() {
 	   return _document.getPackage();

src/ooxml/java/org/apache/poi/openxml4j/opc/OPCPackage.java

@@ -492,7 +492,8 @@ public abstract class OPCPackage implements RelationshipSource, Closeable {
      * the addition of a thumbnail in a package. You can do the same work by
      * using the traditionnal relationship and part mechanism.
      *
-     * @param path The full path to the image file.
+     * @param filename The full path to the image file.
+     * @param data the image data
      */
     public void addThumbnail(String filename, InputStream data) throws IOException {
         // Check parameter

src/scratchpad/src/org/apache/poi/hslf/record/HSLFEscherRecordFactory.java

@@ -40,14 +40,7 @@ public class HSLFEscherRecordFactory extends DefaultEscherRecordFactory {
         // no instance initialisation
     }
     
-    /**
+    @Override
-     * Generates an escher record including the any children contained under that record.
-     * An exception is thrown if the record could not be generated.
-     *
-     * @param data   The byte array containing the records
-     * @param offset The starting offset into the byte array
-     * @return The generated escher record
-     */
     public EscherRecord createRecord(byte[] data, int offset) {
         short options = LittleEndian.getShort( data, offset );
         short recordId = LittleEndian.getShort( data, offset + 2 );