javadocs fixes (jdk8)

(eclipse) source clean ups

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

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

@@ -29,16 +29,16 @@ import org.apache.poi.util.StringUtil;
 public class ClassID
 {
     public static final ClassID OLE10_PACKAGE = new ClassID("{0003000C-0000-0000-C000-000000000046}");
-    public static final ClassID PPT_SHOW = new ClassID("{64818D10-4F9B-11CF-86EA-00AA00B929E8}");
-    public static final ClassID XLS_WORKBOOK = new ClassID("{00020841-0000-0000-C000-000000000046}");
-    public static final ClassID TXT_ONLY = new ClassID("{5e941d80-bf96-11cd-b579-08002b30bfeb}"); // ???
-    public static final ClassID EXCEL97      = new ClassID("{00020820-0000-0000-C000-000000000046}");
-    public static final ClassID EXCEL95      = new ClassID("{00020810-0000-0000-C000-000000000046}");
-    public static final ClassID WORD97       = new ClassID("{00020906-0000-0000-C000-000000000046}");
-    public static final ClassID WORD95       = new ClassID("{00020900-0000-0000-C000-000000000046}");
-    public static final ClassID POWERPOINT97 = new ClassID("{64818D10-4F9B-11CF-86EA-00AA00B929E8}");
-    public static final ClassID POWERPOINT95 = new ClassID("{EA7BAE70-FB3B-11CD-A903-00AA00510EA3}");
-    public static final ClassID EQUATION30   = new ClassID("{0002CE02-0000-0000-C000-000000000046}");
+    public static final ClassID PPT_SHOW      = new ClassID("{64818D10-4F9B-11CF-86EA-00AA00B929E8}");
+    public static final ClassID XLS_WORKBOOK  = new ClassID("{00020841-0000-0000-C000-000000000046}");
+    public static final ClassID TXT_ONLY      = new ClassID("{5e941d80-bf96-11cd-b579-08002b30bfeb}");
+    public static final ClassID EXCEL97       = new ClassID("{00020820-0000-0000-C000-000000000046}");
+    public static final ClassID EXCEL95       = new ClassID("{00020810-0000-0000-C000-000000000046}");
+    public static final ClassID WORD97        = new ClassID("{00020906-0000-0000-C000-000000000046}");
+    public static final ClassID WORD95        = new ClassID("{00020900-0000-0000-C000-000000000046}");
+    public static final ClassID POWERPOINT97  = new ClassID("{64818D10-4F9B-11CF-86EA-00AA00B929E8}");
+    public static final ClassID POWERPOINT95  = new ClassID("{EA7BAE70-FB3B-11CD-A903-00AA00510EA3}");
+    public static final ClassID EQUATION30    = new ClassID("{0002CE02-0000-0000-C000-000000000046}");
 	
 	
     /**
@@ -214,8 +214,9 @@ public class ClassID
      *
      * @param o the object to compare this <code>PropertySet</code> with
      * @return <code>true</code> if the objects are equal, else
-     * <code>false</code>.</p>
+     * <code>false</code>.
      */
+    @Override
     public boolean equals(final Object o)
     {
         if (o == null || !(o instanceof ClassID))
@@ -234,6 +235,7 @@ public class ClassID
     /**
      * @see Object#hashCode()
      */
+    @Override
     public int hashCode()
     {
         return new String(bytes, StringUtil.UTF8).hashCode();
@@ -245,6 +247,7 @@ public class ClassID
      * 
      * @return String representation of the Class ID represented by this object.
      */
+    @Override
     public String toString()
     {
         StringBuffer sbClassId = new StringBuffer(38);

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

@@ -49,9 +49,9 @@ import org.apache.poi.hpsf.wellknown.PropertyIDMap;
  * <p>This class is not thread-safe; concurrent access to instances of this
  * class must be synchronized.</p>
  *
- * <p>While this class is roughly HashMap<Long,CustomProperty>, that's the
+ * <p>While this class is roughly HashMap&lt;Long,CustomProperty&gt;, that's the
  *  internal representation. To external calls, it should appear as
- *  HashMap<String,Object> mapping between Names and Custom Property Values.</p>
+ *  HashMap&lt;String,Object&gt; mapping between Names and Custom Property Values.</p>
  */
 @SuppressWarnings("serial")
 public class CustomProperties extends HashMap<Object,CustomProperty>
@@ -60,12 +60,12 @@ public class CustomProperties extends HashMap<Object,CustomProperty>
     /**
      * <p>Maps property IDs to property names.</p>
      */
-    private Map<Long,String> dictionaryIDToName = new HashMap<Long,String>();
+    private final Map<Long,String> dictionaryIDToName = new HashMap<Long,String>();
 
     /**
      * <p>Maps property names to property IDs.</p>
      */
-    private Map<String,Long> dictionaryNameToID = new HashMap<String,Long>();
+    private final Map<String,Long> dictionaryNameToID = new HashMap<String,Long>();
 
     /**
      * <p>Tells whether this object is pure or not.</p>
@@ -77,6 +77,11 @@ public class CustomProperties extends HashMap<Object,CustomProperty>
      * <p>Puts a {@link CustomProperty} into this map. It is assumed that the
      * {@link CustomProperty} already has a valid ID. Otherwise use
      * {@link #put(CustomProperty)}.</p>
+     * 
+     * @param name the property name
+     * @param cp the property
+     * 
+     * @return the previous property stored under this name
      */
     public CustomProperty put(final String name, final CustomProperty cp)
     {
@@ -134,9 +139,8 @@ public class CustomProperties extends HashMap<Object,CustomProperty>
         else
         {
             long max = 1;
-            for (final Iterator<Long> i = dictionaryIDToName.keySet().iterator(); i.hasNext();)
-            {
-                final long id = i.next().longValue();
+            for (Long long1 : dictionaryIDToName.keySet()) {
+                final long id = long1.longValue();
                 if (id > max)
                     max = id;
             }
@@ -290,25 +294,30 @@ public class CustomProperties extends HashMap<Object,CustomProperty>
     }
 
     /**
-     * Returns a set of all the names of our
-     *  custom properties. Equivalent to 
-     *  {@link #nameSet()}
+     * Returns a set of all the names of our custom properties.
+     * Equivalent to {@link #nameSet()}
+     * 
+     * @return a set of all the names of our custom properties
      */
+    @Override
+    @SuppressWarnings({ "rawtypes", "unchecked" })
     public Set keySet() {
         return dictionaryNameToID.keySet();
     }
 
     /**
-     * Returns a set of all the names of our
-     *  custom properties
+     * Returns a set of all the names of our custom properties
+     * 
+     * @return a set of all the names of our custom properties
      */
     public Set<String> nameSet() {
         return dictionaryNameToID.keySet();
     }
 
     /**
-     * Returns a set of all the IDs of our
-     *  custom properties
+     * Returns a set of all the IDs of our custom properties
+     * 
+     * @return a set of all the IDs of our custom properties
      */
     public Set<String> idSet() {
         return dictionaryNameToID.keySet();
@@ -346,6 +355,7 @@ public class CustomProperties extends HashMap<Object,CustomProperty>
     /**
      * Checks against both String Name and Long ID
      */
+   @Override
    public boolean containsKey(Object key) {
       if(key instanceof Long) {
          return super.containsKey(key);
@@ -359,6 +369,7 @@ public class CustomProperties extends HashMap<Object,CustomProperty>
    /**
     * Checks against both the property, and its values. 
     */
+   @Override
    public boolean containsValue(Object value) {
       if(value instanceof CustomProperty) {
          return super.containsValue(value);

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

@@ -210,7 +210,7 @@ public class MutablePropertySet extends PropertySet
         /* Write the section list, i.e. the references to the sections. Each
          * entry in the section list consist of the section's class ID and the
          * section's offset relative to the beginning of the stream. */
-        offset += nrSections * (ClassID.LENGTH + LittleEndian.INT_SIZE);
+        offset += nrSections * (ClassID.LENGTH + LittleEndianConsts.INT_SIZE);
         final int sectionsBegin = offset;
         for (final Section section : sections)
         {
@@ -282,8 +282,8 @@ public class MutablePropertySet extends PropertySet
      * @param name The document's name. If there is already a document with the
      * same name in the directory the latter will be overwritten.
      *
-     * @throws WritingNotSupportedException
-     * @throws IOException
+     * @throws WritingNotSupportedException if the filesystem doesn't support writing
+     * @throws IOException if the old entry can't be deleted or the new entry be written
      */
     public void write(final DirectoryEntry dir, final String name)
     throws WritingNotSupportedException, IOException

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

@@ -56,8 +56,9 @@ import org.apache.poi.util.LittleEndian;
 public abstract class SpecialPropertySet extends MutablePropertySet
 {
     /**
-     * The id to name mapping of the properties
-     *  in this set.
+     * The id to name mapping of the properties in this set.
+     * 
+     * @return the id to name mapping of the properties in this set
      */
     public abstract PropertyIDMap getPropertySetIDMap();
 
@@ -65,7 +66,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
      * <p>The "real" property set <code>SpecialPropertySet</code>
      * delegates to.</p>
      */
-    private MutablePropertySet delegate;
+    private final MutablePropertySet delegate;
 
 
 
@@ -98,6 +99,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see PropertySet#getByteOrder
      */
+    @Override
     public int getByteOrder()
     {
         return delegate.getByteOrder();
@@ -108,6 +110,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see PropertySet#getFormat
      */
+    @Override
     public int getFormat()
     {
         return delegate.getFormat();
@@ -118,6 +121,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see PropertySet#getOSVersion
      */
+    @Override
     public int getOSVersion()
     {
         return delegate.getOSVersion();
@@ -128,6 +132,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see PropertySet#getClassID
      */
+    @Override
     public ClassID getClassID()
     {
         return delegate.getClassID();
@@ -138,6 +143,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see PropertySet#getSectionCount
      */
+    @Override
     public int getSectionCount()
     {
         return delegate.getSectionCount();
@@ -148,6 +154,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see PropertySet#getSections
      */
+    @Override
     public List<Section> getSections()
     {
         return delegate.getSections();
@@ -158,6 +165,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see PropertySet#isSummaryInformation
      */
+    @Override
     public boolean isSummaryInformation()
     {
         return delegate.isSummaryInformation();
@@ -168,6 +176,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see PropertySet#isDocumentSummaryInformation
      */
+    @Override
     public boolean isDocumentSummaryInformation()
     {
         return delegate.isDocumentSummaryInformation();
@@ -178,6 +187,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see PropertySet#getSingleSection
      */
+    @Override
     public Section getFirstSection()
     {
         return delegate.getFirstSection();
@@ -187,6 +197,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.MutablePropertySet#addSection(org.apache.poi.hpsf.Section)
      */
+    @Override
     public void addSection(final Section section)
     {
         delegate.addSection(section);
@@ -197,6 +208,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.MutablePropertySet#clearSections()
      */
+    @Override
     public void clearSections()
     {
         delegate.clearSections();
@@ -207,6 +219,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.MutablePropertySet#setByteOrder(int)
      */
+    @Override
     public void setByteOrder(final int byteOrder)
     {
         delegate.setByteOrder(byteOrder);
@@ -217,6 +230,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.MutablePropertySet#setClassID(org.apache.poi.hpsf.ClassID)
      */
+    @Override
     public void setClassID(final ClassID classID)
     {
         delegate.setClassID(classID);
@@ -227,6 +241,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.MutablePropertySet#setFormat(int)
      */
+    @Override
     public void setFormat(final int format)
     {
         delegate.setFormat(format);
@@ -237,6 +252,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.MutablePropertySet#setOSVersion(int)
      */
+    @Override
     public void setOSVersion(final int osVersion)
     {
         delegate.setOSVersion(osVersion);
@@ -247,6 +263,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.MutablePropertySet#toInputStream()
      */
+    @Override
     public InputStream toInputStream() throws IOException, WritingNotSupportedException
     {
         return delegate.toInputStream();
@@ -257,6 +274,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.MutablePropertySet#write(org.apache.poi.poifs.filesystem.DirectoryEntry, java.lang.String)
      */
+    @Override
     public void write(final DirectoryEntry dir, final String name) throws WritingNotSupportedException, IOException
     {
         delegate.write(dir, name);
@@ -265,6 +283,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.MutablePropertySet#write(java.io.OutputStream)
      */
+    @Override
     public void write(final OutputStream out) throws WritingNotSupportedException, IOException
     {
         delegate.write(out);
@@ -273,6 +292,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.PropertySet#equals(java.lang.Object)
      */
+    @Override
     public boolean equals(final Object o)
     {
         return delegate.equals(o);
@@ -281,6 +301,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.PropertySet#getProperties()
      */
+    @Override
     public Property[] getProperties() throws NoSingleSectionException
     {
         return delegate.getProperties();
@@ -289,6 +310,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.PropertySet#getProperty(int)
      */
+    @Override
     protected Object getProperty(final int id) throws NoSingleSectionException
     {
         return delegate.getProperty(id);
@@ -299,6 +321,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.PropertySet#getPropertyBooleanValue(int)
      */
+    @Override
     protected boolean getPropertyBooleanValue(final int id) throws NoSingleSectionException
     {
         return delegate.getPropertyBooleanValue(id);
@@ -309,6 +332,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.PropertySet#getPropertyIntValue(int)
      */
+    @Override
     protected int getPropertyIntValue(final int id) throws NoSingleSectionException
     {
         return delegate.getPropertyIntValue(id);
@@ -319,6 +343,9 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * Fetches the property with the given ID, then does its
      *  best to return it as a String
+     * 
+     * @param propertyId the property id
+     *  
      * @return The property as a String, or null if unavailable
      */
     protected String getPropertyStringValue(final int propertyId) {
@@ -355,6 +382,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.PropertySet#hashCode()
      */
+    @Override
     public int hashCode()
     {
         return delegate.hashCode();
@@ -365,6 +393,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.PropertySet#toString()
      */
+    @Override
     public String toString()
     {
         return delegate.toString();
@@ -375,6 +404,7 @@ public abstract class SpecialPropertySet extends MutablePropertySet
     /**
      * @see org.apache.poi.hpsf.PropertySet#wasNull()
      */
+    @Override
     public boolean wasNull() throws NoSingleSectionException
     {
         return delegate.wasNull();

src/java/org/apache/poi/hpsf/wellknown/SectionIDMap.java

@@ -161,6 +161,11 @@ public class SectionIDMap extends HashMap {
     /**
      * Associates the string representation of a section
      *  format ID with a {@link PropertyIDMap}
+     * 
+     * @param key the key of the PropertyIDMap
+     * @param value the PropertyIDMap itself
+     * 
+     * @return the previous PropertyIDMap stored under this key, or {@code null} if there wasn't one
      */
     protected PropertyIDMap put(String key, PropertyIDMap value) {
         return (PropertyIDMap)super.put(key, value);

src/java/org/apache/poi/hssf/dev/BiffViewer.java

@@ -214,9 +214,13 @@ public final class BiffViewer {
     /**
      *  Create an array of records from an input stream
      *
-     *@param  is the InputStream from which the records will be obtained
-     *@return an array of Records created from the InputStream
-     *@exception  org.apache.poi.util.RecordFormatException  on error processing the InputStream
+     * @param is the InputStream from which the records will be obtained
+     * @param ps the PrintWriter to output the record data
+     * @param recListener the record listener to notify about read records
+     * @param dumpInterpretedRecords if {@code true}, the read records will be written to the PrintWriter
+     *
+     * @return an array of Records created from the InputStream
+     * @exception  org.apache.poi.util.RecordFormatException  on error processing the InputStream
      */
     public static Record[] createRecords(InputStream is, PrintWriter ps, BiffRecordListener recListener, boolean dumpInterpretedRecords)
             throws org.apache.poi.util.RecordFormatException {
@@ -527,8 +531,7 @@ public final class BiffViewer {
 	 * <b>Usage</b>:<p>
 	 *
 	 * BiffViewer [--biffhex] [--noint] [--noescher] [--out] &lt;fileName&gt;<p>
-	 * BiffViewer --rawhex  [--out] &lt;fileName&gt;<p>
-	 * <p>
+	 * BiffViewer --rawhex  [--out] &lt;fileName&gt;
 	 *
 	 * <table summary="BiffViewer options">
 	 * <tr><td>--biffhex</td><td>show hex dump of each BIFF record</td></tr>
@@ -538,7 +541,11 @@ public final class BiffViewer {
 	 * <tr><td>--escher</td><td>turn on deserialization of escher records (default is off)</td></tr>
 	 * <tr><td>--noheader</td><td>do not print record header (default is on)</td></tr>
 	 * </table>
+	 * 
+	 * @param args the command line arguments 
 	 *
+	 * @throws IOException if the file doesn't exist or contained errors
+	 * @throws CommandParseException if the command line contained errors
 	 */
 	public static void main(String[] args) throws IOException, CommandParseException {
 		// args = new String[] { "--out", "", };
@@ -609,7 +616,8 @@ public final class BiffViewer {
 			_headers = new ArrayList<String>();
 		}
 
-		public void processRecord(int globalOffset, int recordCounter, int sid, int dataSize,
+		@Override
+        public void processRecord(int globalOffset, int recordCounter, int sid, int dataSize,
 				byte[] data) {
 			String header = formatRecordDetails(globalOffset, sid, dataSize, recordCounter);
 			if(!_noHeader) _headers.add(header);

src/java/org/apache/poi/hssf/dev/FormulaViewer.java

@@ -30,7 +30,6 @@ import org.apache.poi.hssf.usermodel.HSSFWorkbook;
 import org.apache.poi.poifs.filesystem.NPOIFSFileSystem;
 import org.apache.poi.ss.formula.ptg.ExpPtg;
 import org.apache.poi.ss.formula.ptg.FuncPtg;
-import org.apache.poi.ss.formula.ptg.OperationPtg;
 import org.apache.poi.ss.formula.ptg.Ptg;
 
 /**
@@ -53,13 +52,9 @@ public class FormulaViewer
 
     /**
      * Method run
-     * @throws IOException 
-     *
-     *
-     * @exception Exception
-     *
+     * 
+     * @throws IOException if the file contained errors 
      */
-
     public void run() throws IOException {
         NPOIFSFileSystem fs  = new NPOIFSFileSystem(new File(file), true);
         InputStream is = BiffViewer.getPOIFSInputStream(fs);
@@ -141,11 +136,8 @@ public class FormulaViewer
     /**
      * Method parseFormulaRecord
      *
-     *
-     * @param record
-     *
+     * @param record the record to be parsed
      */
-
     public void parseFormulaRecord(FormulaRecord record)
     {
         System.out.println("==============================");
@@ -164,9 +156,8 @@ public class FormulaViewer
 
         StringBuffer buf = new StringBuffer();
 		Ptg[] tokens = record.getParsedExpression();
-		for (int i = 0; i < tokens.length; i++) {
-			Ptg token = tokens[i];
-            buf.append( token.toFormulaString());
+		for (Ptg token : tokens) {
+			buf.append( token.toFormulaString());
             switch (token.getPtgClass()) {
                 case Ptg.CLASS_REF :
                     buf.append("(R)");
@@ -198,9 +189,7 @@ public class FormulaViewer
     /**
      * Method setFile
      *
-     *
-     * @param file
-     *
+     * @param file the file to process
      */
 
     public void setFile(String file)
@@ -218,11 +207,8 @@ public class FormulaViewer
      * pass me a filename and I'll try and parse the formulas from it
      *
      * @param args pass one argument with the filename or --help
-     * @throws IOException 
-     * @throws Exception 
-     *
+     * @throws IOException if the file can't be read or contained errors
      */
-
     public static void main(String args[]) throws IOException
     {
         if ((args == null) || (args.length >2 )

src/java/org/apache/poi/hssf/eventmodel/ERFListener.java

@@ -31,6 +31,9 @@ public interface ERFListener
     /**
      * Process a Record.  This method is called by the 
      * EventRecordFactory when a record is returned.
+     * 
+     * @param rec the record to be processed
+     * 
      * @return boolean specifying whether the effort was a success.
      */
     public boolean processRecord(Record rec);

src/java/org/apache/poi/hssf/eventmodel/EventRecordFactory.java

@@ -27,11 +27,6 @@ import org.apache.poi.hssf.record.*;
  * this version sends {@link ERFListener#processRecord(Record) } messages to
  * the supplied listener.  Record notifications are sent one record behind
  * to ensure that {@link ContinueRecord}s are processed first.
- *
- * @author Andrew C. Oliver (acoliver@apache.org) - probably to blame for the bugs (so yank his chain on the list)
- * @author Marc Johnson (mjohnson at apache dot org) - methods taken from RecordFactory
- * @author Glen Stampoultzis (glens at apache.org) - methods taken from RecordFactory
- * @author Csaba Nagy (ncsaba at yahoo dot com)
  */
 public final class EventRecordFactory {
 
@@ -39,7 +34,9 @@ public final class EventRecordFactory {
 	private final short[] _sids;
 
 	/**
+	 * Create an EventRecordFactory
 	 *
+	 * @param listener the listener to be informed about events
 	 * @param sids an array of Record.sid values identifying the records
 	 * the listener will work with.  Alternatively if this is "null" then
 	 * all records are passed. For all 'known' record types use {@link RecordFactory#getAllKnownRecordSIDs()}
@@ -92,13 +89,13 @@ public final class EventRecordFactory {
 			recStream.nextRecord();
 			Record[] recs = RecordFactory.createRecord(recStream);   // handle MulRK records
 			if (recs.length > 1) {
-				for (int k = 0; k < recs.length; k++) {
+				for (Record rec : recs) {
 					if ( last_record != null ) {
 						if (!processRecord(last_record)) {
 							return;
 						}
 					}
-					last_record = recs[ k ]; // do to keep the algorithm homogeneous...you can't
+					last_record = rec; // do to keep the algorithm homogeneous...you can't
 				}							// actually continue a number record anyhow.
 			} else {
 				Record record = recs[ 0 ];

src/java/org/apache/poi/hssf/eventusermodel/AbortableHSSFListener.java

@@ -42,7 +42,8 @@ public abstract class AbortableHSSFListener implements HSSFListener
      * It is never called by HSSFEventFactory or HSSFRequest.
      * You should implement #abortableProcessRecord instead
      */
-	public void processRecord(Record record)
+	@Override
+    public void processRecord(Record record)
 	{
 	}
 
@@ -60,6 +61,8 @@ public abstract class AbortableHSSFListener implements HSSFListener
 	 *
 	 * Note that HSSFEventFactory will not call the inherited process 
 	 *
+	 * @param record the record to be processed
+	 *
      * @return result code of zero for continued processing.
      *
 	 * @throws HSSFUserException User code can throw this to abort 

src/java/org/apache/poi/hssf/eventusermodel/EventWorkbookBuilder.java

@@ -69,8 +69,8 @@ public class EventWorkbookBuilder {
 
 		// Core Workbook records go first
 		if(bounds != null) {
-			for(int i=0; i<bounds.length; i++) {
-				wbRecords.add(bounds[i]);
+			for (BoundSheetRecord bound : bounds) {
+				wbRecords.add(bound);
 			}
 		}
 		if(sst != null) {
@@ -82,8 +82,8 @@ public class EventWorkbookBuilder {
 		if(externs != null) {
 			wbRecords.add(SupBookRecord.createInternalReferences(
 					(short)externs.length));
-			for(int i=0; i<externs.length; i++) {
-				wbRecords.add(externs[i]);
+			for (ExternSheetRecord extern : externs) {
+				wbRecords.add(extern);
 			}
 		}
 
@@ -113,9 +113,9 @@ public class EventWorkbookBuilder {
 	 *  them once required.
 	 */
 	public static class SheetRecordCollectingListener implements HSSFListener {
-		private HSSFListener childListener;
-		private List<BoundSheetRecord> boundSheetRecords = new ArrayList<BoundSheetRecord>();
-		private List<ExternSheetRecord> externSheetRecords = new ArrayList<ExternSheetRecord>();
+		private final HSSFListener childListener;
+		private final List<BoundSheetRecord> boundSheetRecords = new ArrayList<BoundSheetRecord>();
+		private final List<ExternSheetRecord> externSheetRecords = new ArrayList<ExternSheetRecord>();
 		private SSTRecord sstRecord = null;
 
 		public SheetRecordCollectingListener(HSSFListener childListener) {
@@ -159,7 +159,8 @@ public class EventWorkbookBuilder {
 		 * Process this record ourselves, and then
 		 *  pass it on to our child listener
 		 */
-		public void processRecord(Record record) {
+		@Override
+        public void processRecord(Record record) {
 			// Handle it ourselves
 			processRecordInternally(record);
 
@@ -170,6 +171,8 @@ public class EventWorkbookBuilder {
 		/**
 		 * Process the record ourselves, but do not
 		 *  pass it on to the child Listener.
+		 *  
+		 * @param record the record to be processed
 		 */
 		public void processRecordInternally(Record record) {
 			if(record instanceof BoundSheetRecord) {

src/java/org/apache/poi/hssf/eventusermodel/FormatTrackingHSSFListener.java

@@ -51,6 +51,8 @@ public class FormatTrackingHSSFListener implements HSSFListener {
 	/**
 	 * Creates a format tracking wrapper around the given listener, using
 	 * the {@link Locale#getDefault() default locale} for the formats.
+	 * 
+	 * @param childListener the listener to be wrapped
 	 */
 	public FormatTrackingHSSFListener(HSSFListener childListener) {
 		this(childListener, LocaleUtil.getUserLocale());
@@ -59,6 +61,9 @@ public class FormatTrackingHSSFListener implements HSSFListener {
 	/**
 	 * Creates a format tracking wrapper around the given listener, using
 	 * the given locale for the formats.
+     * 
+     * @param childListener the listener to be wrapped
+     * @param locale the locale for the formats
 	 */
 	public FormatTrackingHSSFListener(
 			HSSFListener childListener, Locale locale) {
@@ -78,7 +83,8 @@ public class FormatTrackingHSSFListener implements HSSFListener {
 	/**
 	 * Process this record ourselves, and then pass it on to our child listener
 	 */
-	public void processRecord(Record record) {
+	@Override
+    public void processRecord(Record record) {
 		// Handle it ourselves
 		processRecordInternally(record);
 
@@ -90,7 +96,7 @@ public class FormatTrackingHSSFListener implements HSSFListener {
 	 * Process the record ourselves, but do not pass it on to the child
 	 * Listener.
 	 *
-	 * @param record
+	 * @param record the record to be processed
 	 */
 	public void processRecordInternally(Record record) {
 		if (record instanceof FormatRecord) {
@@ -104,12 +110,16 @@ public class FormatTrackingHSSFListener implements HSSFListener {
 	}
 
 	/**
-	 * Formats the given numeric of date Cell's contents as a String, in as
+	 * Formats the given numeric of date cells contents as a String, in as
 	 * close as we can to the way that Excel would do so. Uses the various
 	 * format records to manage this.
 	 *
 	 * TODO - move this to a central class in such a way that hssf.usermodel can
 	 * make use of it too
+	 * 
+	 * @param cell the cell
+	 * 
+	 * @return the given numeric of date cells contents as a String
 	 */
 	public String formatNumberDateCell(CellValueRecordInterface cell) {
 		double value;
@@ -135,6 +145,10 @@ public class FormatTrackingHSSFListener implements HSSFListener {
 
 	/**
 	 * Returns the format string, eg $##.##, for the given number format index.
+	 * 
+	 * @param formatIndex the format index
+	 * 
+	 * @return the format string
 	 */
 	public String getFormatString(int formatIndex) {
 		String format = null;
@@ -154,6 +168,10 @@ public class FormatTrackingHSSFListener implements HSSFListener {
 
 	/**
 	 * Returns the format string, eg $##.##, used by your cell
+	 * 
+	 * @param cell the cell
+	 * 
+	 * @return the format string
 	 */
 	public String getFormatString(CellValueRecordInterface cell) {
 		int formatIndex = getFormatIndex(cell);
@@ -165,8 +183,11 @@ public class FormatTrackingHSSFListener implements HSSFListener {
 	}
 
 	/**
-	 * Returns the index of the format string, used by your cell, or -1 if none
-	 * found
+	 * Returns the index of the format string, used by your cell, or -1 if none found
+	 * 
+	 * @param cell the cell
+	 * 
+	 * @return the index of the format string
 	 */
 	public int getFormatIndex(CellValueRecordInterface cell) {
 		ExtendedFormatRecord xfr = _xfRecords.get(cell.getXFIndex());

src/java/org/apache/poi/hssf/eventusermodel/HSSFEventFactory.java

@@ -47,6 +47,8 @@ public class HSSFEventFactory {
 	 *
 	 * @param req an Instance of HSSFRequest which has your registered listeners
 	 * @param fs  a POIFS filesystem containing your workbook
+     * 
+     * @throws IOException if the workbook contained errors 
 	 */
 	public void processWorkbookEvents(HSSFRequest req, POIFSFileSystem fs) throws IOException {
 	   processWorkbookEvents(req, fs.getRoot());
@@ -57,6 +59,8 @@ public class HSSFEventFactory {
     *
     * @param req an Instance of HSSFRequest which has your registered listeners
     * @param dir  a DirectoryNode containing your workbook
+    * 
+    * @throws IOException if the workbook contained errors 
     */
     public void processWorkbookEvents(HSSFRequest req, DirectoryNode dir) throws IOException {
         // some old documents have "WORKBOOK" or "BOOK"
@@ -74,7 +78,11 @@ public class HSSFEventFactory {
         }
 
         InputStream in = dir.createDocumentInputStream(name);
-        processEvents(req, in);
+        try {
+            processEvents(req, in);
+        } finally {
+            in.close();
+        }
     }
 
    /**
@@ -83,6 +91,9 @@ public class HSSFEventFactory {
     * @param req an Instance of HSSFRequest which has your registered listeners
     * @param fs  a POIFS filesystem containing your workbook
     * @return    numeric user-specified result code.
+    * 
+    * @throws HSSFUserException if the processing should be aborted
+    * @throws IOException if the workbook contained errors 
     */
    public short abortableProcessWorkbookEvents(HSSFRequest req, POIFSFileSystem fs)
       throws IOException, HSSFUserException {
@@ -95,11 +106,18 @@ public class HSSFEventFactory {
 	 * @param req an Instance of HSSFRequest which has your registered listeners
 	 * @param dir  a DirectoryNode containing your workbook
 	 * @return    numeric user-specified result code.
+	 * 
+	 * @throws HSSFUserException if the processing should be aborted
+	 * @throws IOException if the workbook contained errors 
 	 */
 	public short abortableProcessWorkbookEvents(HSSFRequest req, DirectoryNode dir)
 		throws IOException, HSSFUserException {
 		InputStream in = dir.createDocumentInputStream("Workbook");
-		return abortableProcessEvents(req, in);
+		try {
+		    return abortableProcessEvents(req, in);
+		} finally {
+		    in.close();
+		}
 	}
 
 	/**
@@ -129,6 +147,8 @@ public class HSSFEventFactory {
 	 * @param req an Instance of HSSFRequest which has your registered listeners
 	 * @param in  a DocumentInputStream obtained from POIFS's POIFSFileSystem object
 	 * @return    numeric user-specified result code.
+	 * 
+	 * @throws HSSFUserException if the processing should be aborted 
 	 */
 	public short abortableProcessEvents(HSSFRequest req, InputStream in)
 		throws HSSFUserException {

src/java/org/apache/poi/hssf/eventusermodel/HSSFListener.java

@@ -34,7 +34,8 @@ public interface HSSFListener
 
     /**
      * process an HSSF Record. Called when a record occurs in an HSSF file.
+     * 
+     * @param record the record to be processed
      */
-
     public void processRecord(Record record);
 }

src/java/org/apache/poi/hssf/eventusermodel/HSSFRequest.java

@@ -77,16 +77,16 @@ public class HSSFRequest {
 	public void addListenerForAllRecords(HSSFListener lsnr) {
 		short[] rectypes = RecordFactory.getAllKnownRecordSIDs();
 
-		for (int k = 0; k < rectypes.length; k++) {
-			addListener(lsnr, rectypes[k]);
+		for (short rectype : rectypes) {
+			addListener(lsnr, rectype);
 		}
 	}
 
 	/**
 	 * Called by HSSFEventFactory, passes the Record to each listener associated with
 	 * a record.sid.
-	 *
-	 * Exception and return value added 2002-04-19 by Carey Sublette
+	 * 
+	 * @param rec the record to be processed
 	 *
 	 * @return numeric user-specified result code. If zero continue processing.
 	 * @throws HSSFUserException User exception condition

src/java/org/apache/poi/hssf/eventusermodel/HSSFUserException.java

@@ -54,6 +54,8 @@ public class HSSFUserException extends Exception
     /**
      * <p>Creates a new {@link HSSFUserException} with a message
      * string.</p>
+     * 
+     * @param msg the error message
      */
     public HSSFUserException(final String msg)
     {
@@ -64,6 +66,8 @@ public class HSSFUserException extends Exception
 
     /**
      * <p>Creates a new {@link HSSFUserException} with a reason.</p>
+     * 
+     * @param reason the causing exception
      */
     public HSSFUserException(final Throwable reason)
     {
@@ -76,6 +80,9 @@ public class HSSFUserException extends Exception
     /**
      * <p>Creates a new {@link HSSFUserException} with a message string
      * and a reason.</p>
+     * 
+     * @param msg the error message
+     * @param reason the causing exception
      */
     public HSSFUserException(final String msg, final Throwable reason)
     {
@@ -89,6 +96,8 @@ public class HSSFUserException extends Exception
      * <p>Returns the {@link Throwable} that caused this exception to
      * be thrown or <code>null</code> if there was no such {@link
      * Throwable}.</p>
+     * 
+     * @return the reason
      */
     public Throwable getReason()
     {

src/java/org/apache/poi/hssf/eventusermodel/dummyrecord/LastCellOfRowDummyRecord.java

@@ -23,8 +23,8 @@ package org.apache.poi.hssf.eventusermodel.dummyrecord;
  *  cell record for this row.
  */
 public final class LastCellOfRowDummyRecord extends DummyRecordBase {
-	private int row;
-	private int lastColumnNumber;
+	private final int row;
+	private final int lastColumnNumber;
 	
 	public LastCellOfRowDummyRecord(int row, int lastColumnNumber) {
 		this.row = row;
@@ -34,17 +34,27 @@ public final class LastCellOfRowDummyRecord extends DummyRecordBase {
 	/**
 	 * Returns the (0 based) number of the row we are
 	 *  currently working on.
+	 *  
+	 * @return the (0 based) number of the row
 	 */
-	public int getRow() { return row; }
+	public int getRow() {
+	    return row;
+    }
+	
 	/**
 	 * Returns the (0 based) number of the last column
 	 *  seen for this row. You should have already been
 	 *  called with that record.
 	 * This is -1 in the case of there being no columns
 	 *  for the row.
+	 *  
+	 * @return the (0 based) number of the last column
 	 */
-	public int getLastColumnNumber() { return lastColumnNumber; }
+	public int getLastColumnNumber() {
+	    return lastColumnNumber;
+    }
 	
+	@Override
 	public String toString() {
 	    return "End-of-Row for Row=" + row + " at Column=" + lastColumnNumber;
 	}

src/java/org/apache/poi/hssf/extractor/ExcelExtractor.java

@@ -36,6 +36,7 @@ import org.apache.poi.hssf.usermodel.HSSFWorkbook;
 import org.apache.poi.poifs.filesystem.DirectoryNode;
 import org.apache.poi.poifs.filesystem.POIFSFileSystem;
 import org.apache.poi.ss.formula.eval.ErrorEval;
+import org.apache.poi.ss.usermodel.Cell;
 import org.apache.poi.ss.usermodel.HeaderFooter;
 import org.apache.poi.ss.usermodel.Row.MissingCellPolicy;
 
@@ -54,8 +55,8 @@ import org.apache.poi.ss.usermodel.Row.MissingCellPolicy;
  * @see <a href="http://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/hssf/eventusermodel/examples/XLS2CSVmra.java">XLS2CSVmra</a>
  */
 public class ExcelExtractor extends POIOLE2TextExtractor implements org.apache.poi.ss.extractor.ExcelExtractor {
-	private HSSFWorkbook _wb;
-	private HSSFDataFormatter _formatter;
+	private final HSSFWorkbook _wb;
+	private final HSSFDataFormatter _formatter;
 	private boolean _includeSheetNames = true;
 	private boolean _shouldEvaluateFormulas = true;
 	private boolean _includeCellComments = false;
@@ -201,7 +202,10 @@ public class ExcelExtractor extends POIOLE2TextExtractor implements org.apache.p
 
 	/**
 	 * Command line extractor.
-	 * @throws IOException 
+	 * 
+	 * @param args the command line parameters
+	 * 
+	 * @throws IOException if the file can't be read or contains errors
 	 */
 	public static void main(String[] args) throws IOException {
 
@@ -239,45 +243,40 @@ public class ExcelExtractor extends POIOLE2TextExtractor implements org.apache.p
 		extractor.close();
 		wb.close();
 	}
-	/**
-	 * Should sheet names be included? Default is true
-	 */
-	public void setIncludeSheetNames(boolean includeSheetNames) {
+
+	@Override
+    public void setIncludeSheetNames(boolean includeSheetNames) {
 		_includeSheetNames = includeSheetNames;
 	}
-	/**
-	 * Should we return the formula itself, and not
-	 *  the result it produces? Default is false
-	 */
-	public void setFormulasNotResults(boolean formulasNotResults) {
+
+	@Override
+    public void setFormulasNotResults(boolean formulasNotResults) {
 		_shouldEvaluateFormulas = !formulasNotResults;
 	}
-	/**
-	 * Should cell comments be included? Default is false
-	 */
-	public void setIncludeCellComments(boolean includeCellComments) {
+
+	@Override
+    public void setIncludeCellComments(boolean includeCellComments) {
 		_includeCellComments = includeCellComments;
 	}
+
 	/**
 	 * Should blank cells be output? Default is to only
 	 *  output cells that are present in the file and are
 	 *  non-blank.
+	 * 
+	 * @param includeBlankCells {@code true} if blank cells should be included
 	 */
 	public void setIncludeBlankCells(boolean includeBlankCells) {
 		_includeBlankCells = includeBlankCells;
 	}
-	/**
-	 * Should headers and footers be included in the output?
-	 * Default is to include them.
-	 */
-	public void setIncludeHeadersFooters(boolean includeHeadersFooters) {
+
+	@Override
+    public void setIncludeHeadersFooters(boolean includeHeadersFooters) {
 		_includeHeadersFooters = includeHeadersFooters;
 	}
 
-	/**
-	 * Retrieves the text contents of the file
-	 */
-	public String getText() {
+	@Override
+    public String getText() {
 		StringBuffer text = new StringBuffer();
 
 		// We don't care about the difference between
@@ -324,42 +323,42 @@ public class ExcelExtractor extends POIOLE2TextExtractor implements org.apache.p
 						outputContents = _includeBlankCells;
 					} else {
 						switch(cell.getCellType()) {
-							case HSSFCell.CELL_TYPE_STRING:
+							case Cell.CELL_TYPE_STRING:
 								text.append(cell.getRichStringCellValue().getString());
 								break;
-							case HSSFCell.CELL_TYPE_NUMERIC:
+							case Cell.CELL_TYPE_NUMERIC:
 								text.append(
 								      _formatter.formatCellValue(cell)
 								);
 								break;
-							case HSSFCell.CELL_TYPE_BOOLEAN:
+							case Cell.CELL_TYPE_BOOLEAN:
 								text.append(cell.getBooleanCellValue());
 								break;
-							case HSSFCell.CELL_TYPE_ERROR:
+							case Cell.CELL_TYPE_ERROR:
 								text.append(ErrorEval.getText(cell.getErrorCellValue()));
 								break;
-							case HSSFCell.CELL_TYPE_FORMULA:
+							case Cell.CELL_TYPE_FORMULA:
 								if(!_shouldEvaluateFormulas) {
 									text.append(cell.getCellFormula());
 								} else {
 									switch(cell.getCachedFormulaResultType()) {
-										case HSSFCell.CELL_TYPE_STRING:
+										case Cell.CELL_TYPE_STRING:
 											HSSFRichTextString str = cell.getRichStringCellValue();
 											if(str != null && str.length() > 0) {
 												text.append(str.toString());
 											}
 											break;
-										case HSSFCell.CELL_TYPE_NUMERIC:
+										case Cell.CELL_TYPE_NUMERIC:
 											HSSFCellStyle style = cell.getCellStyle();
 											double nVal = cell.getNumericCellValue();
 											short df = style.getDataFormat();
 											String dfs = style.getDataFormatString();
 											text.append(_formatter.formatRawCellContents(nVal, df, dfs));
 											break;
-										case HSSFCell.CELL_TYPE_BOOLEAN:
+										case Cell.CELL_TYPE_BOOLEAN:
 											text.append(cell.getBooleanCellValue());
 											break;
-										case HSSFCell.CELL_TYPE_ERROR:
+										case Cell.CELL_TYPE_ERROR:
 											text.append(ErrorEval.getText(cell.getErrorCellValue()));
 											break;
 										default:

src/java/org/apache/poi/hssf/extractor/OldExcelExtractor.java

@@ -195,14 +195,19 @@ public class OldExcelExtractor implements Closeable {
 
     /**
      * The Biff version, largely corresponding to the Excel version
+     * 
+     * @return the Biff version
      */
     public int getBiffVersion() {
         return biffVersion;
     }
+    
     /**
      * The kind of the file, one of {@link BOFRecord#TYPE_WORKSHEET},
      *  {@link BOFRecord#TYPE_CHART}, {@link BOFRecord#TYPE_EXCEL_4_MACRO}
      *  or {@link BOFRecord#TYPE_WORKSPACE_FILE}
+     * 
+     * @return the file type
      */
     public int getFileType() {
         return fileType;
@@ -211,6 +216,8 @@ public class OldExcelExtractor implements Closeable {
     /**
      * Retrieves the text contents of the file, as best we can
      *  for these old file formats
+     * 
+     * @return the text contents of the file
      */
     public String getText() {
         StringBuffer text = new StringBuffer();

src/java/org/apache/poi/hssf/record/Record.java

@@ -20,11 +20,7 @@ package org.apache.poi.hssf.record;
 import java.io.ByteArrayInputStream;
 
 /**
- * Title: Record
- * Description: All HSSF Records inherit from this class.
- * @author Andrew C. Oliver
- * @author Marc Johnson (mjohnson at apache dot org)
- * @author Jason Height (jheight at chariot dot net dot au)
+ * All HSSF Records inherit from this class.
  */
 public abstract class Record extends RecordBase {
 
@@ -56,8 +52,9 @@ public abstract class Record extends RecordBase {
 
     /**
      * return the non static version of the id for this record.
+     * 
+     * @return he id for this record
      */
-
     public abstract short getSid();
 
     @Override
@@ -73,6 +70,8 @@ public abstract class Record extends RecordBase {
      *  internal counts / ids in them. For those which
      *  do, a full model-aware cloning is needed, which
      *  allocates new ids / counts as needed.
+     * 
+     * @return the cloned current record
      */
     public Record cloneViaReserialise() {
         // Do it via a re-serialization

src/java/org/apache/poi/hssf/record/RecordBase.java

@@ -19,8 +19,6 @@ package org.apache.poi.hssf.record;
 
 /**
  * Common base class of {@link Record} and {@link org.apache.poi.hssf.record.aggregates.RecordAggregate}
- * 
- * @author Josh Micich
  */
 public abstract class RecordBase {
 	/**
@@ -37,6 +35,8 @@ public abstract class RecordBase {
 	/**
 	 * gives the current serialized size of the record. Should include the sid
 	 * and reclength (4 bytes).
+	 * 
+	 * @return the record size
 	 */
 	public abstract int getRecordSize();
 }

src/java/org/apache/poi/ss/extractor/ExcelExtractor.java

@@ -22,29 +22,41 @@ package org.apache.poi.ss.extractor;
  */
 public interface ExcelExtractor {
     /**
-     * Should sheet names be included? Default is true
+     * Should sheet names be included?
+     * Default is true
+     * 
+     * @param includeSheetNames {@code true} if the sheet names should be included
      */
     public void setIncludeSheetNames(boolean includeSheetNames);
 
     /**
-     * Should we return the formula itself, and not
-     *  the result it produces? Default is false
+     * Should we return the formula itself, and not the result it produces?
+     * Default is false
+     * 
+     * @param formulasNotResults {@code true} if the formula itself is returned
      */
     public void setFormulasNotResults(boolean formulasNotResults);
 
     /**
      * Should headers and footers be included in the output?
      * Default is true
+     * 
+     * @param includeHeadersFooters {@code true} if headers and footers should be included
      */
     public void setIncludeHeadersFooters(boolean includeHeadersFooters);
 
     /**
-     * Should cell comments be included? Default is false
+     * Should cell comments be included?
+     * Default is false
+     * 
+     * @param includeCellComments {@code true} if cell comments should be included
      */
     public void setIncludeCellComments(boolean includeCellComments);
 
     /**
-     * Retreives the text contents of the file
+     * Retrieves the text contents of the file
+     * 
+     * @return the text contents of the file
      */
     public String getText();
 }

src/ooxml/java/org/apache/poi/dev/OOXMLLister.java

@@ -35,8 +35,8 @@ import org.apache.poi.openxml4j.opc.PackageRelationshipCollection;
  *  they're all related to each other.
  */
 public class OOXMLLister {
-	private OPCPackage container;
-	private PrintStream disp;
+	private final OPCPackage container;
+	private final PrintStream disp;
 	
 	public OOXMLLister(OPCPackage container) {
 		this(container, System.out);
@@ -51,6 +51,8 @@ public class OOXMLLister {
 	 * 
 	 * @param part the PackagePart
 	 * @return the size of the PackagePart
+	 * 
+	 * @throws IOException if the part can't be read
 	 */
 	public static long getSize(PackagePart part) throws IOException {
 		InputStream in = part.getInputStream();