Add/update some JavaDoc

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

18 files changed, 59 insertions, 56 deletions

diff --git a/poi-ooxml/src/main/java/org/apache/poi/ooxml/util/PackageHelper.java b/poi-ooxml/src/main/java/org/apache/poi/ooxml/util/PackageHelper.java
index 3463f255cf..aa175bde29 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/ooxml/util/PackageHelper.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/ooxml/util/PackageHelper.java
@@ -48,11 +48,11 @@ public final class PackageHelper {
     }
 
     /**
-     * @param stream
+     * @param stream The InputStream to read from
      * @param closeStream whether to close the stream (default is false)
      * @since POI 5.2.0
      * @return OPCPackage
-     * @throws IOException
+     * @throws IOException If reading data from the stream fails
      */
     public static OPCPackage open(InputStream stream, boolean closeStream) throws IOException {
         try {
diff --git a/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XMLSlideShow.java b/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XMLSlideShow.java
index f3867247dd..47542bd46c 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XMLSlideShow.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XMLSlideShow.java
@@ -128,7 +128,7 @@ public class XMLSlideShow extends POIXMLDocument
 
     /**
      * @param is InputStream
-     * @throws IOException
+     * @throws IOException If reading data from the stream fails
      * @throws POIXMLException a RuntimeException that can be caused by invalid OOXML data
      * @throws RuntimeException a number of other runtime exceptions can be thrown, especially if there are problems with the
      * input format
diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/eventusermodel/XSSFReader.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/eventusermodel/XSSFReader.java
index 64ed7297ee..404037fd08 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xssf/eventusermodel/XSSFReader.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/eventusermodel/XSSFReader.java
@@ -119,7 +119,9 @@ public class XSSFReader {
     /**
      * Controls whether {@link #getSharedStringsTable()} uses {@link SharedStringsTable}
      * or {@link ReadOnlySharedStringsTable}.
-     * @param useReadOnlySharedStringsTable
+     *
+     * @param useReadOnlySharedStringsTable if true, the ReadOnlySharedStringsTable is used,
+     *                                      SharedStringsTable otherwise
      * @since POI 5.2.0
      */
     public void setUseReadOnlySharedStringsTable(boolean useReadOnlySharedStringsTable) {
diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java
index 037531f3fb..bc678d2c8d 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java
@@ -244,7 +244,7 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su
      *  footprint than an InputStream backed one.
      *
      * @param pkg the OpenXML4J {@code OPC Package} object.
-     * @throws IOException
+     * @throws IOException If reading data from the package fails
      * @throws POIXMLException a RuntimeException that can be caused by invalid OOXML data
      * @throws RuntimeException a number of other runtime exceptions can be thrown, especially if there are problems with the
      * input format
@@ -276,7 +276,7 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su
      *       pkg.close(); // gracefully closes the underlying zip file
      *   }</pre>
      *
-     * @throws IOException
+     * @throws IOException If reading data from the stream fails
      * @throws POIXMLException a RuntimeException that can be caused by invalid OOXML data
      * @throws RuntimeException a number of other runtime exceptions can be thrown, especially if there are problems with the
      * input format
@@ -300,8 +300,8 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su
      *  than opening from an InputStream
      *
      * @param file   the file to open
-     * @throws IOException
-     * @throws InvalidFormatException
+     * @throws IOException If reading data from the file fails
+     * @throws InvalidFormatException If the file has a format that cannot be read or if the file is corrupted
      * @throws POIXMLException a RuntimeException that can be caused by invalid OOXML data
      * @throws RuntimeException a number of other runtime exceptions can be thrown, especially if there are problems with the
      * input format
@@ -322,7 +322,7 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su
      *  than opening from an InputStream
      *
      * @param path   the file name.
-     * @throws IOException
+     * @throws IOException If reading data from the file fails
      * @throws POIXMLException a RuntimeException that can be caused by invalid OOXML data
      * @throws RuntimeException a number of other runtime exceptions can be thrown, especially if there are problems with the
      * input format
@@ -335,7 +335,7 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su
     /**
      * Constructs a XSSFWorkbook object using Package Part.
      * @param part  package part
-     * @throws IOException
+     * @throws IOException If reading data from the Package Part fails
      * @throws POIXMLException a RuntimeException that can be caused by invalid OOXML data
      * @throws RuntimeException a number of other runtime exceptions can be thrown, especially if there are problems with the
      * input format
diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFDocument.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFDocument.java
index 1f3c1b899c..06a53322b2 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFDocument.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFDocument.java
@@ -133,7 +133,7 @@ public class XWPFDocument extends POIXMLDocument implements Document, IBody {
 
     /**
      * @param pkg OPC package
-     * @throws IOException
+     * @throws IOException If reading data from the package fails
      * @throws POIXMLException a RuntimeException that can be caused by invalid OOXML data
      * @throws RuntimeException a number of other runtime exceptions can be thrown, especially if there are problems with the
      * input format
@@ -146,8 +146,8 @@ public class XWPFDocument extends POIXMLDocument implements Document, IBody {
     }
 
     /**
-     * @param is InputStream
-     * @throws IOException
+     * @param is The InputStream to read data from
+     * @throws IOException If reading data from the stream fails
      * @throws POIXMLException a RuntimeException that can be caused by invalid OOXML data
      * @throws RuntimeException a number of other runtime exceptions can be thrown, especially if there are problems with the
      * input format
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hemf/usermodel/HemfPicture.java b/poi-scratchpad/src/main/java/org/apache/poi/hemf/usermodel/HemfPicture.java
index 899b053ddc..ffd51c65c4 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hemf/usermodel/HemfPicture.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hemf/usermodel/HemfPicture.java
@@ -208,8 +208,9 @@ public class HemfPicture implements Iterable<HemfRecord>, GenericRecord {
     }
 
     /**
-     * @param ctx
-     * @param graphicsBounds
+     * @param ctx The Graphics-context to draw on
+     * @param graphicsBounds A rectangle which describes the bounds
+     *                       for drawing
      * @throws IllegalStateException if the draw fails
      */
     public void draw(Graphics2D ctx, Rectangle2D graphicsBounds) {
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hmef/HMEFMessage.java b/poi-scratchpad/src/main/java/org/apache/poi/hmef/HMEFMessage.java
index f6e3b6c801..6788be2403 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hmef/HMEFMessage.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hmef/HMEFMessage.java
@@ -41,7 +41,7 @@ import org.apache.poi.util.LittleEndian;
  */
 public final class HMEFMessage {
     public static final int HEADER_SIGNATURE = 0x223e9f78;
-    
+
     @SuppressWarnings("unused")
     private int fileId;
     private final List<TNEFAttribute> messageAttributes = new ArrayList<>();
@@ -50,7 +50,7 @@ public final class HMEFMessage {
 
     /**
      * @param inp input stream
-     * @throws IOException
+     * @throws IOException If reading data from the stream fails
      * @throws RuntimeException a number of runtime exceptions can be thrown, especially if there are problems with the
      * input format
      */
@@ -64,17 +64,17 @@ public final class HMEFMessage {
                         "expected " + HEADER_SIGNATURE + " but got " + sig
                 );
             }
-            
+
             // Read the File ID
             fileId = LittleEndian.readUShort(inp);
-            
+
             // Now begin processing the contents
             process(inp);
         } finally {
             inp.close();
         }
     }
-    
+
     private void process(InputStream inp) throws IOException {
        int level;
        do {
@@ -126,16 +126,16 @@ public final class HMEFMessage {
         Attachment attach = attachments.get(attachments.size() - 1);
         attach.addAttribute(attr);
     }
-    
+
     /**
-     * Returns all HMEF/TNEF attributes of the message. 
+     * Returns all HMEF/TNEF attributes of the message.
      * Note - In a typical message, most of the interesting properties
-     *  are stored as {@link MAPIAttribute}s - see {@link #getMessageMAPIAttributes()} 
+     *  are stored as {@link MAPIAttribute}s - see {@link #getMessageMAPIAttributes()}
      */
     public List<TNEFAttribute> getMessageAttributes() {
         return Collections.unmodifiableList(messageAttributes);
     }
-    
+
     /**
      * Returns all MAPI attributes of the message.
      * Note - A small number of HMEF/TNEF specific attributes normally
@@ -144,17 +144,17 @@ public final class HMEFMessage {
     public List<MAPIAttribute> getMessageMAPIAttributes() {
         return Collections.unmodifiableList(mapiAttributes);
     }
-    
+
     /**
      * Returns all the Attachments of the message.
      */
     public List<Attachment> getAttachments() {
         return Collections.unmodifiableList(attachments);
     }
-    
+
     /**
      * Return the message attribute with the given ID,
-     *  or null if there isn't one. 
+     *  or null if there isn't one.
      */
     public TNEFAttribute getMessageAttribute(TNEFProperty id) {
         for (TNEFAttribute attr : messageAttributes) {
@@ -164,10 +164,10 @@ public final class HMEFMessage {
         }
         return null;
     }
-    
+
     /**
      * Return the message MAPI Attribute with the given ID,
-     *  or null if there isn't one. 
+     *  or null if there isn't one.
      */
     public MAPIAttribute getMessageMAPIAttribute(MAPIProperty id) {
         for (MAPIAttribute attr : mapiAttributes) {
@@ -178,7 +178,7 @@ public final class HMEFMessage {
         }
         return null;
     }
-    
+
     /**
      * Return the string value of the mapi property, or null
      *  if it isn't set
@@ -186,7 +186,7 @@ public final class HMEFMessage {
     private String getString(MAPIProperty id) {
         return MAPIStringAttribute.getAsString( getMessageMAPIAttribute(id) );
     }
-    
+
     /**
      * Returns the Message Subject, or null if the mapi property
      *  for this isn't set
@@ -194,7 +194,7 @@ public final class HMEFMessage {
     public String getSubject() {
         return getString(MAPIProperty.CONVERSATION_TOPIC);
     }
-    
+
     /**
      * Returns the Message Body, as RTF, or null if the mapi property
      *  for this isn't set
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/Bitmap.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/Bitmap.java
index d00ea092b2..9d6a3ba773 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/Bitmap.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/Bitmap.java
@@ -41,7 +41,7 @@ import org.apache.poi.util.Units;
 public abstract class Bitmap extends HSLFPictureData {
 
     /**
-     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], PictureType)} or one of its overloads to create new
+     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], org.apache.poi.sl.usermodel.PictureData.PictureType)} or one of its overloads to create new
      *             {@link Bitmap}. This API led to detached {@link Bitmap} instances (See Bugzilla
      *             46122) and prevented adding additional functionality.
      */
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/DIB.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/DIB.java
index 19e35497f5..b43b2e06d3 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/DIB.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/DIB.java
@@ -37,7 +37,7 @@ public final class DIB extends Bitmap {
     private static final int HEADER_SIZE = 14;
 
     /**
-     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], PictureType)} or one of its overloads to create new
+     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], org.apache.poi.sl.usermodel.PictureData.PictureType)} or one of its overloads to create new
      *             {@link DIB}. This API led to detached {@link DIB} instances (See Bugzilla
      *             46122) and prevented adding additional functionality.
      */
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/EMF.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/EMF.java
index 0c118e50b9..fd1df89ca6 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/EMF.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/EMF.java
@@ -40,7 +40,7 @@ import org.apache.poi.util.Units;
 public final class EMF extends Metafile {
 
     /**
-     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], PictureType)} or one of its overloads to create new
+     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], org.apache.poi.sl.usermodel.PictureData.PictureType)} or one of its overloads to create new
      *             EMF. This API led to detached EMF instances (See Bugzilla
      *             46122) and prevented adding additional functionality.
      */
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/JPEG.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/JPEG.java
index 236e895a2d..40f6a77a45 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/JPEG.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/JPEG.java
@@ -34,7 +34,7 @@ public final class JPEG extends Bitmap {
     private ColorSpace colorSpace = ColorSpace.rgb;
 
     /**
-     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], PictureType)} or one of its overloads to create new
+     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], org.apache.poi.sl.usermodel.PictureData.PictureType)} or one of its overloads to create new
      *             {@link JPEG}. This API led to detached {@link JPEG} instances (See Bugzilla
      *             46122) and prevented adding additional functionality.
      */
@@ -55,7 +55,7 @@ public final class JPEG extends Bitmap {
     public JPEG(EscherContainerRecord recordContainer, EscherBSERecord bse) {
         super(recordContainer, bse);
     }
-    
+
     @Override
     public PictureType getType(){
         return PictureType.JPEG;
@@ -64,13 +64,13 @@ public final class JPEG extends Bitmap {
     public ColorSpace getColorSpace() {
         return colorSpace;
     }
-    
+
     public void setColorSpace(ColorSpace colorSpace) {
         this.colorSpace = colorSpace;
     }
-    
+
     /**
-     * JPEG signature is one of {@code 0x46A0, 0x46B0, 0x6E20, 0x6E30} 
+     * JPEG signature is one of {@code 0x46A0, 0x46B0, 0x6E20, 0x6E30}
      *
      * @return JPEG signature ({@code 0x46A0, 0x46B0, 0x6E20, 0x6E30})
      */
@@ -79,7 +79,7 @@ public final class JPEG extends Bitmap {
             ? (getUIDInstanceCount() == 1 ? 0x46A0 :  0x46B0)
             : (getUIDInstanceCount() == 1 ? 0x6E20 :  0x6E30);
     }
-    
+
     /**
      * Sets the PICT signature - either {@code 0x5420} or {@code 0x5430}
      */
@@ -103,6 +103,6 @@ public final class JPEG extends Bitmap {
                 break;
             default:
                 throw new IllegalArgumentException(signature+" is not a valid instance/signature value for JPEG");
-        }        
+        }
     }
 }
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/PICT.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/PICT.java
index 041206fe7b..3e5042af46 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/PICT.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/PICT.java
@@ -47,7 +47,7 @@ public final class PICT extends Metafile {
     private static final Logger LOG = LogManager.getLogger(PICT.class);
 
     /**
-     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], PictureType)} or one of its overloads to create new
+     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], org.apache.poi.sl.usermodel.PictureData.PictureType)} or one of its overloads to create new
      *             PICT. This API led to detached PICT instances (See Bugzilla
      *             46122) and prevented adding additional functionality.
      */
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/PNG.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/PNG.java
index 43aebabeac..e08f2185d0 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/PNG.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/PNG.java
@@ -30,7 +30,7 @@ import org.apache.poi.util.Removal;
 public final class PNG extends Bitmap {
 
     /**
-     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], PictureType)} or one of its overloads to create new
+     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], org.apache.poi.sl.usermodel.PictureData.PictureType)} or one of its overloads to create new
      *             {@link PNG}. This API led to detached {@link PNG} instances (See Bugzilla
      *             46122) and prevented adding additional functionality.
      */
@@ -70,7 +70,7 @@ public final class PNG extends Bitmap {
     public int getSignature(){
         return (getUIDInstanceCount() == 1 ? 0x6E00 : 0x6E10);
     }
-    
+
     /**
      * Sets the PNG signature - either {@code 0x6E00} or {@code 0x6E10}
      */
@@ -84,6 +84,6 @@ public final class PNG extends Bitmap {
                 break;
             default:
                 throw new IllegalArgumentException(signature+" is not a valid instance/signature value for PNG");
-        }        
+        }
     }
 }
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/WMF.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/WMF.java
index 1e32de6d43..73da07c9b4 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/WMF.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/blip/WMF.java
@@ -40,7 +40,7 @@ import org.apache.poi.util.Units;
 public final class WMF extends Metafile {
 
     /**
-     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], PictureType)} or one of its overloads to create new
+     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], org.apache.poi.sl.usermodel.PictureData.PictureType)} or one of its overloads to create new
      *             WMF. This API led to detached WMF instances (See Bugzilla
      *             46122) and prevented adding additional functionality.
      */
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFPictureData.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFPictureData.java
index 2c01492bea..3a6d2ad879 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFPictureData.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFPictureData.java
@@ -110,7 +110,7 @@ public abstract class HSLFPictureData implements PictureData, GenericRecord {
     final EscherBSERecord bse;
 
     /**
-     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], PictureType)} or one of its overloads to create new
+     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], org.apache.poi.sl.usermodel.PictureData.PictureType)} or one of its overloads to create new
      *             {@link HSLFPictureData}. This API led to detached {@link HSLFPictureData} instances (See Bugzilla
      *             46122) and prevented adding additional functionality.
      */
@@ -252,7 +252,7 @@ public abstract class HSLFPictureData implements PictureData, GenericRecord {
      *
      * @param type type of picture.
      * @return concrete instance of {@link HSLFPictureData}.
-     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], PictureType)} or one of its overloads to create new
+     * @deprecated Use {@link HSLFSlideShow#addPicture(byte[], org.apache.poi.sl.usermodel.PictureData.PictureType)} or one of its overloads to create new
      *             {@link HSLFPictureData}. This API led to detached {@link HSLFPictureData} instances (See Bugzilla
      *             46122) and prevented adding additional functionality.
      */
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFSlideShow.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFSlideShow.java
index 736aae9d58..fa4cf6c795 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFSlideShow.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFSlideShow.java
@@ -166,7 +166,7 @@ public final class HSLFSlideShow extends POIDocument implements SlideShow<HSLFSh
 
     /**
      * Constructs a Powerpoint document from an input stream.
-     * @throws IOException
+     * @throws IOException If reading data from the stream fails
      * @throws RuntimeException a number of runtime exceptions can be thrown, especially if there are problems with the
      * input format
      */
@@ -177,7 +177,7 @@ public final class HSLFSlideShow extends POIDocument implements SlideShow<HSLFSh
 
     /**
      * Constructs a Powerpoint document from an POIFSFileSystem.
-     * @throws IOException
+     * @throws IOException If reading data from the file-system fails
      * @throws RuntimeException a number of runtime exceptions can be thrown, especially if there are problems with the
      * input format
      */
@@ -188,7 +188,7 @@ public final class HSLFSlideShow extends POIDocument implements SlideShow<HSLFSh
 
     /**
      * Constructs a Powerpoint document from an DirectoryNode.
-     * @throws IOException
+     * @throws IOException If reading data from the DirectoryNode fails
      * @throws RuntimeException a number of runtime exceptions can be thrown, especially if there are problems with the
      * input format
      */
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hwmf/usermodel/HwmfPicture.java b/poi-scratchpad/src/main/java/org/apache/poi/hwmf/usermodel/HwmfPicture.java
index ac57804945..89ccb35395 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hwmf/usermodel/HwmfPicture.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hwmf/usermodel/HwmfPicture.java
@@ -81,8 +81,8 @@ public class HwmfPicture implements Iterable<HwmfRecord>, GenericRecord {
     }
 
     /**
-     * @param inputStream
-     * @throws IOException
+     * @param inputStream The InputStream to read data from
+     * @throws IOException If reading data from the file fails
      * @throws RuntimeException a number of runtime exceptions can be thrown, especially if there are problems with the
      * input format
      */
diff --git a/poi/src/main/java/org/apache/poi/poifs/filesystem/POIFSFileSystem.java b/poi/src/main/java/org/apache/poi/poifs/filesystem/POIFSFileSystem.java
index 222752eb78..559045f522 100644
--- a/poi/src/main/java/org/apache/poi/poifs/filesystem/POIFSFileSystem.java
+++ b/poi/src/main/java/org/apache/poi/poifs/filesystem/POIFSFileSystem.java
@@ -195,7 +195,7 @@ public class POIFSFileSystem extends BlockStore
      *
      * @param channel the FileChannel from which to read the data
      * @throws IOException on errors reading, or on invalid data
-     * @see POIFSFileSystem(FileChannel, boolean, boolean) this constructor gives more control over whether to
+     * @see #POIFSFileSystem(FileChannel, boolean, boolean) this constructor gives more control over whether to
      * close the provided channel
      */
     public POIFSFileSystem(FileChannel channel)
@@ -215,7 +215,7 @@ public class POIFSFileSystem extends BlockStore
      * @param channel  the FileChannel from which to read or read/write the data
      * @param readOnly whether the POIFileSystem will only be used in read-only mode
      * @throws IOException on errors reading, or on invalid data
-     * @see POIFSFileSystem(FileChannel, boolean, boolean) this constructor gives more control over whether to
+     * @see #POIFSFileSystem(FileChannel, boolean, boolean) this constructor gives more control over whether to
      * close the provided channel
      */
     public POIFSFileSystem(FileChannel channel, boolean readOnly)