From: Dominik Stadler Date: Thu, 24 Feb 2022 18:12:39 +0000 (+0000) Subject: Add/update some JavaDoc X-Git-Tag: REL_5_2_1~6 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=116c3e91ad195ef11fd09ec5d56895bf73a6b0f1;p=poi.git Add/update some JavaDoc git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1898385 13f79535-47bb-0310-9956-ffa450edef68 --- 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 * } * - * @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, 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 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 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 getMessageMAPIAttributes() { return Collections.unmodifiableList(mapiAttributes); } - + /** * Returns all the Attachments of the message. */ public List 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, 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)