fixed javadoc warnings

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

src/java/org/apache/poi/POIDocument.java

@@ -245,8 +245,8 @@ public abstract class POIDocument {
 
    /**
     * Copies nodes from one POIFS to the other minus the excepts
-    * @param source is the source POIFS to copy from
-    * @param target is the target POIFS to copy to
+    * @param sourceRoot is the source POIFS to copy from
+    * @param targetRoot is the target POIFS to copy to
     * @param excepts is a list of Strings specifying what nodes NOT to copy
     */
     @Deprecated

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

@@ -547,9 +547,8 @@ public final class HSSFWorkbook extends POIDocument implements org.apache.poi.ss
      * @param sheetIx number (0 based)
      * @throws IllegalArgumentException if the name is null or invalid
      *  or workbook already contains a sheet with this name
-     * @see {@link #createSheet(String)}
-     * @see {@link org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)}
-     *      for a safe way to create valid names
+     * @see #createSheet(String)
+     * @see org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)
      */
     public void setSheetName(int sheetIx, String name) {
         if (name == null) {
@@ -781,8 +780,7 @@ public final class HSSFWorkbook extends POIDocument implements org.apache.poi.ss
      * @return Sheet representing the new sheet.
      * @throws IllegalArgumentException if the name is null or invalid
      *  or workbook already contains a sheet with this name
-     * @see {@link org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)}
-     *      for a safe way to create valid names
+     * @see org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)
      */
     public HSSFSheet createSheet(String sheetname)
     {

src/java/org/apache/poi/poifs/filesystem/EntryUtils.java

@@ -61,12 +61,10 @@ public class EntryUtils
     /**
      * Copies all the nodes from one POIFS Directory to another
      * 
-     * @param source
+     * @param sourceRoot
      *            is the source Directory to copy from
-     * @param target
+     * @param targetRoot
      *            is the target Directory to copy to
-     * @param excepts
-     *            is a list of Strings specifying what nodes NOT to copy
      */
     public static void copyNodes(DirectoryEntry sourceRoot,
             DirectoryEntry targetRoot) throws IOException
@@ -79,8 +77,8 @@ public class EntryUtils
     /**
      * Copies nodes from one Directory to the other minus the excepts
      * 
-     * @param source The filtering source Directory to copy from
-     * @param target The filtering target Directory to copy to
+     * @param filteredSource The filtering source Directory to copy from
+     * @param filteredTarget The filtering target Directory to copy to
      */
     public static void copyNodes( FilteringDirectoryNode filteredSource,
             FilteringDirectoryNode filteredTarget ) throws IOException
@@ -93,9 +91,9 @@ public class EntryUtils
     /**
      * Copies nodes from one Directory to the other minus the excepts
      * 
-     * @param source
+     * @param sourceRoot
      *            is the source Directory to copy from
-     * @param target
+     * @param targetRoot
      *            is the target Directory to copy to
      * @param excepts
      *            is a list of Strings specifying what nodes NOT to copy

src/java/org/apache/poi/poifs/filesystem/FilteringDirectoryNode.java

@@ -57,7 +57,7 @@ public class FilteringDirectoryNode implements DirectoryEntry
     *  will exclude entries such as "MyNode" and "MyDir/IgnoreNode".
     * The excludes can stretch into children, if they contain a /.
     *  
-    * @param entry The Directory to filter
+    * @param directory The Directory to filter
     * @param excludes The Entries to exclude
     */
    public FilteringDirectoryNode(DirectoryEntry directory, Collection<String> excludes) {

src/java/org/apache/poi/poifs/filesystem/Ole10Native.java

@@ -66,7 +66,7 @@ public class Ole10Native {
    * to include a stream "{01}Ole10Native" which contains the actual
    * data relevant for this class.
    *
-   * @param poifs POI Filesystem object
+   * @param directory POI Filesystem object
    * @return Returns an instance of this class
    * @throws IOException on IO error
    * @throws Ole10NativeException on invalid or unexcepted data format

src/java/org/apache/poi/ss/usermodel/ConditionalFormatting.java

@@ -44,7 +44,8 @@ import org.apache.poi.ss.util.CellRangeAddress;
  *  </LI>
  *  </UL>
  *
- * Use {@link org.apache.poi.hssf.usermodel.Sheet#getSheetConditionalFormatting()} to get access to an instance of this class.
+ * Use {@link org.apache.poi.ss.usermodel.Sheet#getSheetConditionalFormatting()}
+ * to get access to an instance of this class.
  * <P>
  * To create a new Conditional Formatting set use the following approach:
  *

src/java/org/apache/poi/ss/usermodel/SheetConditionalFormatting.java

@@ -46,7 +46,7 @@ public interface SheetConditionalFormatting {
      *
      * @param regions - list of rectangular regions to apply conditional formatting rules
      * @param rule1 -  the first rule
-     * @param rule1 -  the second rule
+     * @param rule2 -  the second rule
      *
      * @return index of the newly created Conditional Formatting object
      */

src/java/org/apache/poi/ss/usermodel/Workbook.java

@@ -129,13 +129,15 @@ public interface Workbook {
 
     /**
      * Set the sheet name.
-     *
+     * <p>
+     * See {@link org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)}
+     *      for a safe way to create valid names
+     * </p>
      * @param sheet number (0 based)
      * @throws IllegalArgumentException if the name is null or invalid
      *  or workbook already contains a sheet with this name
-     * @see {@link #createSheet(String)}
-     * @see {@link org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)}
-     *      for a safe way to create valid names
+     * @see #createSheet(String)
+     * @see org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)
      */
     void setSheetName(int sheet, String name);
 
@@ -208,12 +210,15 @@ public interface Workbook {
      * The string MUST NOT begin or end with the single quote (') character.
      * </p>
      *
+     * <p>
+     * See {@link org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)}
+     *      for a safe way to create valid names
+     * </p>
      * @param sheetname  sheetname to set for the sheet.
      * @return Sheet representing the new sheet.
      * @throws IllegalArgumentException if the name is null or invalid
      *  or workbook already contains a sheet with this name
-     * @see {@link org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)}
-     *      for a safe way to create valid names
+     * @see org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)
      */
     Sheet createSheet(String sheetname);
 

src/java/org/apache/poi/util/LittleEndian.java

@@ -573,7 +573,7 @@ public class LittleEndian implements LittleEndianConsts
      * 
      * @param data
      *            the byte array
-     * @param offset
+     * @param startOffset
      *            a starting offset into the byte array
      * @param value
      *            the short (16-bit) values

src/ooxml/java/org/apache/poi/xslf/usermodel/RenderableShape.java

@@ -65,7 +65,6 @@ import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.Comparator;
-import java.util.List;
 
 /**
  * Encapsulates logic to translate DrawingML objects to Java2D
@@ -142,10 +141,10 @@ class RenderableShape {
         String blipId = blip.getEmbed();
         PackageRelationship rel = parentPart.getRelationship(blipId);
         if (rel != null) {
-            XSLFImageRendener renderer = null;
+            XSLFImageRenderer renderer = null;
             if (graphics != null)
-                renderer = (XSLFImageRendener) graphics.getRenderingHint(XSLFRenderingHint.IMAGE_RENDERER);
-            if (renderer == null) renderer = new XSLFImageRendener();
+                renderer = (XSLFImageRenderer) graphics.getRenderingHint(XSLFRenderingHint.IMAGE_RENDERER);
+            if (renderer == null) renderer = new XSLFImageRenderer();
 
             try {
                 BufferedImage img = renderer.readImage(parentPart.getRelatedPart(rel));

src/ooxml/java/org/apache/poi/xslf/usermodel/XSLFConnectorShape.java

@@ -77,8 +77,7 @@ public class XSLFConnectorShape extends XSLFSimpleShape {
 
 
     /**
-     * YK: dashing of lines is suppressed for now.
-     * @return
+     * YK: shadows of lines are suppressed for now.
      */
     @Override
     public XSLFShadow getShadow() {

src/ooxml/java/org/apache/poi/xslf/usermodel/XSLFFontManager.java

@@ -29,7 +29,7 @@ public interface XSLFFontManager {
     /**
      * select a font to be used to paint text
      *
-     * @param family the font family as defined in the .pptx file.
+     * @param typeface the font family as defined in the .pptx file.
      * This can be unknown or missing in the graphic environment.
      *
      * @return the font to be used to paint text

src/ooxml/java/org/apache/poi/xslf/usermodel/XSLFImageRendener.java → src/ooxml/java/org/apache/poi/xslf/usermodel/XSLFImageRenderer.java

@@ -39,7 +39,6 @@ import java.io.InputStream;
  * 
  * <pre>
  * <code>
- * @Override
  * public class MyImageRendener extends XSLFImageRendener{
  * public boolean drawImage(Graphics2D graphics, XSLFPictureData data, Rectangle2D anchor){
  * 	boolean ok = super.drawImage(graphics, data, anchor);
@@ -69,12 +68,12 @@ import java.io.InputStream;
  * @author Yegor Kozlov
  */
 @Beta
-public class XSLFImageRendener {
+public class XSLFImageRenderer {
 
 	/**
 	 * Render picture data into the supplied graphics
 	 * 
-	 * @return true if the picture data was succesfully renderered
+	 * @return true if the picture data was successfully rendered
 	 */
 	public boolean drawImage(Graphics2D graphics, XSLFPictureData data,
 			Rectangle2D anchor) {

src/ooxml/java/org/apache/poi/xslf/usermodel/XSLFPictureShape.java

@@ -22,7 +22,6 @@ package org.apache.poi.xslf.usermodel;
 import org.apache.poi.POIXMLException;
 import org.apache.poi.openxml4j.opc.PackagePart;
 import org.apache.poi.openxml4j.opc.PackageRelationship;
-import org.apache.poi.openxml4j.opc.TargetMode;
 import org.apache.poi.util.Beta;
 import org.openxmlformats.schemas.drawingml.x2006.main.CTBlip;
 import org.openxmlformats.schemas.drawingml.x2006.main.CTBlipFillProperties;
@@ -126,8 +125,8 @@ public class XSLFPictureShape extends XSLFSimpleShape {
         XSLFPictureData data = getPictureData();
     	if(data == null) return;
 
-        XSLFImageRendener renderer = (XSLFImageRendener)graphics.getRenderingHint(XSLFRenderingHint.IMAGE_RENDERER);
-        if(renderer == null) renderer = new XSLFImageRendener();
+        XSLFImageRenderer renderer = (XSLFImageRenderer)graphics.getRenderingHint(XSLFRenderingHint.IMAGE_RENDERER);
+        if(renderer == null) renderer = new XSLFImageRenderer();
 
         RenderableShape rShape = new RenderableShape(this);
         Rectangle2D anchor = rShape.getAnchor(graphics);

src/ooxml/java/org/apache/poi/xslf/usermodel/XSLFRenderingHint.java

@@ -44,7 +44,7 @@ public class XSLFRenderingHint extends RenderingHints.Key {
     /**
      * Use a custom image rendener
      *
-     * @see XSLFImageRendener
+     * @see XSLFImageRenderer
      */
     public static final XSLFRenderingHint IMAGE_RENDERER = new XSLFRenderingHint(3);
 

src/ooxml/java/org/apache/poi/xssf/streaming/SheetDataWriter.java

@@ -65,7 +65,6 @@ public class SheetDataWriter {
      * Create a writer for the sheet data.
      * 
      * @param  fd the file to write to
-     * @return
      */
     public Writer createWriter(File fd)throws IOException {
         return new BufferedWriter(new FileWriter(fd));

src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java

@@ -558,12 +558,15 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Iterable<X
      * The string MUST NOT begin or end with the single quote (') character.
      * </p>
      *
+     * <p>
+     * See {@link org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)}
+     *      for a safe way to create valid names
+     * </p>
      * @param sheetname  sheetname to set for the sheet.
      * @return Sheet representing the new sheet.
      * @throws IllegalArgumentException if the name is null or invalid
      *  or workbook already contains a sheet with this name
-     * @see {@link org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)}
-     *      for a safe way to create valid names
+     * @see org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)
      */
     public XSSFSheet createSheet(String sheetname) {
         if (sheetname == null) {
@@ -1190,9 +1193,8 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Iterable<X
      * @param sheetname  the new sheet name
      * @throws IllegalArgumentException if the name is null or invalid
      *  or workbook already contains a sheet with this name
-     * @see {@link #createSheet(String)}
-     * @see {@link org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)}
-     *      for a safe way to create valid names
+     * @see #createSheet(String)
+     * @see org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)
      */
     public void setSheetName(int sheetIndex, String sheetname) {
         validateSheetIndex(sheetIndex);

src/ooxml/java/org/apache/poi/xssf/usermodel/charts/XSSFManualLayout.java

@@ -49,7 +49,7 @@ public final class XSSFManualLayout implements ManualLayout {
 
 	/**
 	 * Create a new SpreadsheetML manual layout.
-	 * @param layout a Spreadsheet ML layout that should be used as base.
+	 * @param ctLayout a Spreadsheet ML layout that should be used as base.
 	 */
 	public XSSFManualLayout(CTLayout ctLayout) {
 		initLayout(ctLayout);

src/ooxml/java/org/apache/poi/xwpf/usermodel/XWPFDocument.java

@@ -505,9 +505,10 @@ public class XWPFDocument extends POIXMLDocument implements Document, IBody {
 
     /**
      * Add a new paragraph at position of the cursor. The cursor must be on the
-     * {@link TokenType#START} tag of an subelement of the documents body. When
-     * this method is done, the cursor passed as parameter points to the
-     * {@link TokenType#END} of the newly inserted paragraph.
+     * {@link org.apache.xmlbeans.XmlCursor.TokenType#START} tag of an subelement
+     * of the documents body. When this method is done, the cursor passed as
+     * parameter points to the {@link org.apache.xmlbeans.XmlCursor.TokenType#END}
+     * of the newly inserted paragraph.
      * 
      * @param cursor
      * @return the {@link XWPFParagraph} object representing the newly inserted

src/ooxml/java/org/apache/poi/xwpf/usermodel/XWPFFootnote.java

@@ -81,7 +81,7 @@ public class XWPFFootnote implements Iterable<XWPFParagraph>,IBody {
     }
 
     /**
-     * @param position in table array
+     * @param pos in table array
      * @return The table at position pos
      * @see org.apache.poi.xwpf.usermodel.IBody#getTableArray(int)
      */

src/ooxml/java/org/apache/poi/xwpf/usermodel/XWPFFootnotes.java

@@ -132,7 +132,7 @@ public class XWPFFootnotes extends POIXMLDocumentPart {
 
 	/**
 	 * add a footnote to the document
-	 * @param footnote
+	 * @param note
 	 * @throws IOException		 
 	 */
 	public XWPFFootnote addFootnote(CTFtnEdn note){

src/scratchpad/src/org/apache/poi/hssf/converter/AbstractExcelUtils.java

@@ -165,7 +165,7 @@ public class AbstractExcelUtils
     /**
      * @param mergedRanges
      *            map of sheet merged ranges built with
-     *            {@link #buildMergedRangesMap(HSSFSheet)}
+     *            {@link ExcelToHtmlUtils#buildMergedRangesMap(HSSFSheet)}
      * @return {@link CellRangeAddress} from map if cell with specified row and
      *         column numbers contained in found range, <tt>null</tt> otherwise
      */

src/scratchpad/src/org/apache/poi/hwpf/model/CHPBinTable.java

@@ -64,7 +64,7 @@ public class CHPBinTable
      * Constructor used to read a binTable in from a Word document.
      * 
      * @deprecated Use
-     *             {@link #CHPBinTable(byte[],byte[],int,int,TextPieceTable)}
+     *             {@link #CHPBinTable(byte[], byte[], int, int, CharIndexTranslator)}
      *             instead
      */
     public CHPBinTable( byte[] documentStream, byte[] tableStream, int offset,

src/scratchpad/src/org/apache/poi/hwpf/model/CHPFormattedDiskPage.java

@@ -59,7 +59,7 @@ public final class CHPFormattedDiskPage extends FormattedDiskPage
      * read from a Word file).
      * 
      * @deprecated Use
-     *             {@link #CHPFormattedDiskPage(byte[],int,TextPieceTable)}
+     *             {@link #CHPFormattedDiskPage(byte[], int, CharIndexTranslator)}
      *             instead
      */
     @SuppressWarnings( "unused" )

src/scratchpad/src/org/apache/poi/hwpf/model/FileInformationBlock.java

@@ -38,9 +38,9 @@ import org.apache.poi.util.POILogger;
  * The {@link FibBase} class, holds the
  *  first 32 bytes.
  * The next part, the fibRgW / FibRgW97, is handled
- *  by {@link FIBShortHandler}.
+ *  by {@link FibRgW97}.
  * The next part, the fibRgLw / The FibRgLw97, is
- *  handled by the {@link FIBLongHandler}.
+ *  handled by the {@link FibRgLw}.
  * Finally, the rest of the fields are handled by
  *  the {@link FIBFieldHandler}.
  *

src/scratchpad/src/org/apache/poi/hwpf/model/PAPBinTable.java

@@ -59,7 +59,7 @@ public class PAPBinTable
 
     /**
      * @deprecated Use
-     *             {@link #PAPBinTable(byte[],byte[],byte[],int,int,int,TextPieceTable,boolean)}
+     *             {@link #PAPBinTable(byte[], byte[], byte[], int, int, CharIndexTranslator)}
      *             instead
      */
     @SuppressWarnings( "unused" )

src/scratchpad/src/org/apache/poi/hwpf/model/PAPFormattedDiskPage.java

@@ -69,7 +69,7 @@ public final class PAPFormattedDiskPage extends FormattedDiskPage {
      * Creates a PAPFormattedDiskPage from a 512 byte array
      * 
      * @deprecated Use
-     *             {@link #PAPFormattedDiskPage(byte[],byte[],int,int,TextPieceTable,boolean)}
+     *             {@link #PAPFormattedDiskPage(byte[], byte[], int, CharIndexTranslator)}
      *             instead
      */
     public PAPFormattedDiskPage( byte[] documentStream, byte[] dataStream,

src/scratchpad/src/org/apache/poi/hwpf/model/SectionDescriptor.java

@@ -23,7 +23,7 @@ import org.apache.poi.util.LittleEndian;
 /**
  * Section Descriptor (SED)
  * 
- * @see page 186 for details
+ * See page 186 for details.
  */
 @Internal
 public final class SectionDescriptor

src/scratchpad/src/org/apache/poi/hwpf/usermodel/Picture.java

@@ -298,7 +298,7 @@ public final class Picture
     }
 
     /**
-     * @retrn the vertical aspect ratio for picture provided by user
+     * @return the vertical aspect ratio for picture provided by user
      * @deprecated use more precise {@link #getVerticalScalingFactor()}
      */
     @Deprecated