From f539222425ccf07c85a528628cb7b5a1c44c09db Mon Sep 17 00:00:00 2001 From: Dominik Stadler Date: Thu, 1 Nov 2018 10:30:16 +0000 Subject: [PATCH] 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 | 12 +++++- .../common/usermodel/fonts/FontFamily.java | 8 ++-- .../poi/common/usermodel/fonts/FontPitch.java | 10 ++++- .../poi/extractor/OLE2ExtractorFactory.java | 41 +++++++++++++++---- src/java/org/apache/poi/hpsf/Property.java | 10 +++-- 5 files changed, 63 insertions(+), 18 deletions(-) diff --git a/src/java/org/apache/poi/POIDocument.java b/src/java/org/apache/poi/POIDocument.java index 7c1d4779b5..69033a3f5f 100644 --- a/src/java/org/apache/poi/POIDocument.java +++ b/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; diff --git a/src/java/org/apache/poi/common/usermodel/fonts/FontFamily.java b/src/java/org/apache/poi/common/usermodel/fonts/FontFamily.java index 8faa788f58..b627e10af8 100644 --- a/src/java/org/apache/poi/common/usermodel/fonts/FontFamily.java +++ b/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); } - -} \ No newline at end of file +} diff --git a/src/java/org/apache/poi/common/usermodel/fonts/FontPitch.java b/src/java/org/apache/poi/common/usermodel/fonts/FontPitch.java index 78c6533944..5d1d48e63e 100644 --- a/src/java/org/apache/poi/common/usermodel/fonts/FontPitch.java +++ b/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 LOGFONT structure + * + * @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); } } - diff --git a/src/java/org/apache/poi/extractor/OLE2ExtractorFactory.java b/src/java/org/apache/poi/extractor/OLE2ExtractorFactory.java index 145d4d56ae..1f5eee039d 100644 --- a/src/java/org/apache/poi/extractor/OLE2ExtractorFactory.java +++ b/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 dirs = new ArrayList<>(); // For anything else not directly held in as a POIFS directory @@ -237,13 +263,12 @@ public final class OLE2ExtractorFactory { ArrayList e = new ArrayList<>(); for (Entry dir : dirs) { - e.add(createExtractor( - (DirectoryNode) dir + e.add(createExtractor((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); diff --git a/src/java/org/apache/poi/hpsf/Property.java b/src/java/org/apache/poi/hpsf/Property.java index 8878497dc3..56f9ac2175 100644 --- a/src/java/org/apache/poi/hpsf/Property.java +++ b/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); }