Add/update some JavaDoc

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

12 files changed, 42 insertions, 41 deletions

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
      */