Remove JavaDoc warnings

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

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

@@ -33,6 +33,7 @@ import org.apache.poi.hpsf.DocumentSummaryInformation;
 import org.apache.poi.hpsf.PropertySet;
 import org.apache.poi.hpsf.PropertySetFactory;
 import org.apache.poi.hpsf.SummaryInformation;
+import org.apache.poi.hpsf.WritingNotSupportedException;
 import org.apache.poi.poifs.crypt.EncryptionInfo;
 import org.apache.poi.poifs.crypt.Encryptor;
 import org.apache.poi.poifs.crypt.cryptoapi.CryptoAPIDecryptor;
@@ -176,6 +177,8 @@ public abstract class POIDocument implements Closeable {
      *  
      *  @param setName The property to read
      *  @return The value of the given property or null if it wasn't found.
+     *
+     * @throws IOException If retrieving properties fails
      */
     @SuppressWarnings("WeakerAccess")
     protected PropertySet getPropertySet(String setName) throws IOException {
@@ -189,6 +192,8 @@ public abstract class POIDocument implements Closeable {
      *  @param setName The property to read
      *  @param encryptionInfo the encryption descriptor in case of cryptoAPI encryption
      *  @return The value of the given property or null if it wasn't found.
+     *
+     * @throws IOException If retrieving properties fails
      */
     @SuppressWarnings("WeakerAccess")
     protected PropertySet getPropertySet(String setName, EncryptionInfo encryptionInfo) throws IOException {
@@ -305,7 +310,8 @@ public abstract class POIDocument implements Closeable {
     }
 	
     /**
-     * Writes out a given ProperySet
+     * Writes out a given PropertySet
+     *
      * @param name the (POIFS Level) name of the property to write
      * @param set the PropertySet to write out 
      * @param outFS the NPOIFSFileSystem to write the property into
@@ -326,7 +332,7 @@ public abstract class POIDocument implements Closeable {
             outFS.createOrUpdateDocument(bIn, name);
 
             logger.log(POILogger.INFO, "Wrote property set " + name + " of size " + data.length);
-        } catch(org.apache.poi.hpsf.WritingNotSupportedException wnse) {
+        } catch(WritingNotSupportedException ignored) {
             logger.log( POILogger.ERROR, "Couldn't write property set with name " + name + " as not supported by HPSF yet");
         }
     }
@@ -468,6 +474,8 @@ public abstract class POIDocument implements Closeable {
 
     /**
      * @return the encryption info if the document is encrypted, otherwise {@code null}
+     *
+     * @throws IOException If retrieving the encryption information fails
      */
     public EncryptionInfo getEncryptionInfo() throws IOException {
         return null;

src/java/org/apache/poi/common/usermodel/fonts/FontFamily.java

@@ -68,13 +68,15 @@ public enum FontFamily {
         }
         return null;
     }
-    
 
     /**
      * Get FontFamily from combined native id
+     *
+     * @param pitchAndFamily The PitchFamily to decode.
+     *
+     * @return The resulting FontFamily
      */
     public static FontFamily valueOfPitchFamily(byte pitchAndFamily) {
         return valueOf(pitchAndFamily >>> 4);
     }
-
+}
-}

src/java/org/apache/poi/common/usermodel/fonts/FontPitch.java

@@ -59,6 +59,11 @@ public enum FontPitch {
      * Combine pitch and family to native id
      * 
      * @see <a href="https://msdn.microsoft.com/en-us/library/dd145037.aspx">LOGFONT structure</a>
+     *
+     * @param pitch The pitch-value, cannot be null
+     * @param family The family-value, cannot be null
+     *
+     * @return The resulting combined byte-value with pitch and family encoded into one byte
      */
     public static byte getNativeId(FontPitch pitch, FontFamily family) {
         return (byte)(pitch.getNativeId() | (family.getFlag() << 4));
@@ -66,9 +71,12 @@ public enum FontPitch {
 
     /**
      * Get FontPitch from native id
+     *
+     * @param pitchAndFamily The combined byte value for pitch and family
+     *
+     * @return The resulting FontPitch enumeration value
      */
     public static FontPitch valueOfPitchFamily(byte pitchAndFamily) {
         return valueOf(pitchAndFamily & 0x3);
     }
 }
-

src/java/org/apache/poi/extractor/OLE2ExtractorFactory.java

@@ -65,6 +65,8 @@ public final class OLE2ExtractorFactory {
      * Should this thread prefer event based over usermodel based extractors?
      * (usermodel extractors tend to be more accurate, but use more memory)
      * Default is false.
+     *
+     * @return true if event extractors should be preferred in the current thread, fals otherwise.
      */
     public static boolean getThreadPrefersEventExtractors() {
         return threadPreferEventExtractors.get();
@@ -74,6 +76,8 @@ public final class OLE2ExtractorFactory {
      * Should all threads prefer event based over usermodel based extractors?
      * (usermodel extractors tend to be more accurate, but use more memory)
      * Default is to use the thread level setting, which defaults to false.
+     *
+     * @return true if event extractors should be preferred in all threads, fals otherwise.
      */
     public static Boolean getAllThreadsPreferEventExtractors() {
         return allPreferEventExtractors;
@@ -82,6 +86,8 @@ public final class OLE2ExtractorFactory {
     /**
      * Should this thread prefer event based over usermodel based extractors?
      * Will only be used if the All Threads setting is null.
+     *
+     * @param preferEventExtractors If this threads should prefer event based extractors.
      */
     public static void setThreadPrefersEventExtractors(boolean preferEventExtractors) {
         threadPreferEventExtractors.set(preferEventExtractors);
@@ -90,6 +96,8 @@ public final class OLE2ExtractorFactory {
     /**
      * Should all threads prefer event based over usermodel based extractors?
      * If set, will take preference over the Thread level setting.
+     *
+     * @param preferEventExtractors If all threads should prefer event based extractors.
      */
     public static void setAllThreadsPreferEventExtractors(Boolean preferEventExtractors) {
         allPreferEventExtractors = preferEventExtractors;
@@ -98,6 +106,8 @@ public final class OLE2ExtractorFactory {
     /**
      * Should this thread use event based extractors is available?
      * Checks the all-threads one first, then thread specific.
+     *
+     * @return If the current thread should use event based extractors.
      */
     public static boolean getPreferEventExtractor() {
         if(allPreferEventExtractors != null) {
@@ -155,6 +165,16 @@ public final class OLE2ExtractorFactory {
      * Create the Extractor, if possible. Generally needs the Scratchpad jar.
      * Note that this won't check for embedded OOXML resources either, use
      *  {@link org.apache.poi.ooxml.extractor.ExtractorFactory} for that.
+     *
+     * @param poifsDir The {@link DirectoryNode} pointing to a document.
+     *
+     * @return The resulting {@link POITextExtractor}, an exception is thrown if
+     *      no TextExtractor can be created for some reason.
+     *
+     * @throws IOException If converting the {@link DirectoryNode} into a HSSFWorkbook fails
+     * @throws OldFileFormatException If the {@link DirectoryNode} points to a format of
+     *      an unsupported version of Excel.
+     * @throws IllegalArgumentException If creating the Extractor fails
      */
     public static POITextExtractor createExtractor(DirectoryNode poifsDir) throws IOException {
         // Look for certain entries in the stream, to figure it
@@ -193,11 +213,17 @@ public final class OLE2ExtractorFactory {
      * If there are no embedded documents, you'll get back an
      *  empty array. Otherwise, you'll get one open
      *  {@link POITextExtractor} for each embedded file.
+     *
+     * @param ext The extractor to look at for embedded documents
+     *
+     * @return An array of resulting extractors. Empty if no embedded documents are found.
+     *
+     * @throws IOException If converting the {@link DirectoryNode} into a HSSFWorkbook fails
+     * @throws OldFileFormatException If the {@link DirectoryNode} points to a format of
+     *      an unsupported version of Excel.
+     * @throws IllegalArgumentException If creating the Extractor fails
      */
-    @SuppressWarnings("unused")
+    public static POITextExtractor[] getEmbededDocsTextExtractors(POIOLE2TextExtractor ext) throws IOException {
-    public static POITextExtractor[] getEmbededDocsTextExtractors(POIOLE2TextExtractor ext)
-            throws IOException
-    {
         // All the embedded directories we spotted
         List<Entry> dirs = new ArrayList<>();
         // For anything else not directly held in as a POIFS directory
@@ -237,13 +263,12 @@ public final class OLE2ExtractorFactory {
 
         ArrayList<POITextExtractor> e = new ArrayList<>();
         for (Entry dir : dirs) {
-            e.add(createExtractor(
+            e.add(createExtractor((DirectoryNode) dir
-                    (DirectoryNode) dir
             ));
         }
-        for (InputStream nonPOIF : nonPOIFS) {
+        for (InputStream stream : nonPOIFS) {
             try {
-                e.add(createExtractor(nonPOIF));
+                e.add(createExtractor(stream));
             } catch (Exception xe) {
                 // Ignore, invalid format
                 LOGGER.log(POILogger.WARN, xe);

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

@@ -248,12 +248,14 @@ public class Property {
     /**
      * Returns the property's size in bytes. This is always a multiple of 4.
      *
+     * @param property The integer property to check
+     *
      * @return the property's size in bytes
      *
      * @exception WritingNotSupportedException if HPSF does not yet support the
      * property's variant type.
      */
-    protected int getSize(int codepage) throws WritingNotSupportedException
+    protected int getSize(int property) throws WritingNotSupportedException
     {
         int length = Variant.getVariantLength(type);
         if (length >= 0  || type == Variant.VT_EMPTY) {
@@ -269,16 +271,16 @@ public class Property {
         if (type == Variant.VT_LPSTR || type == Variant.VT_LPWSTR) {
             ByteArrayOutputStream bos = new ByteArrayOutputStream();
             try {
-                length = write(bos, codepage) - 2*LittleEndianConsts.INT_SIZE;
+                length = write(bos, property) - 2*LittleEndianConsts.INT_SIZE;
                 /* Pad to multiples of 4. */
                 length += (4 - (length & 0x3)) & 0x3;
                 return length;
             } catch (IOException e) {
-                throw new WritingNotSupportedException(type, value);
+                throw new WritingNotSupportedException(type, this.value);
             }
         }
 
-        throw new WritingNotSupportedException(type, value);
+        throw new WritingNotSupportedException(type, this.value);
     }