From: Dominik Stadler Date: Sun, 27 Jul 2014 18:32:24 +0000 (+0000) Subject: Add/Fix some Javadoc X-Git-Tag: REL_3_11_BETA1~30 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=15476cd981a3dc964e959cdebc2b49eff7d66a92;p=poi.git Add/Fix some Javadoc git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1613826 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/src/java/org/apache/poi/POIDocument.java b/src/java/org/apache/poi/POIDocument.java index a1a8fe1c80..e61366b451 100644 --- a/src/java/org/apache/poi/POIDocument.java +++ b/src/java/org/apache/poi/POIDocument.java @@ -60,10 +60,15 @@ public abstract class POIDocument { /* Have the property streams been read yet? (Only done on-demand) */ private boolean initialized = false; - + /** + * Constructs a POIDocument with the given directory node. + * + * @param dir The {@link DirectoryNode} where information is read from. + */ protected POIDocument(DirectoryNode dir) { this.directory = dir; } + /** * @deprecated use {@link POIDocument#POIDocument(DirectoryNode)} instead */ @@ -71,15 +76,20 @@ public abstract class POIDocument { protected POIDocument(DirectoryNode dir, POIFSFileSystem fs) { this.directory = dir; } + protected POIDocument(POIFSFileSystem fs) { this(fs.getRoot()); } + protected POIDocument(NPOIFSFileSystem fs) { this(fs.getRoot()); } /** * Fetch the Document Summary Information of the document + * + * @return The Document Summary Information or null + * if it could not be read for this document. */ public DocumentSummaryInformation getDocumentSummaryInformation() { if(!initialized) readProperties(); @@ -88,6 +98,9 @@ public abstract class POIDocument { /** * Fetch the Summary Information of the document + * + * @return The Summary information for the document or null + * if it could not be read for this document. */ public SummaryInformation getSummaryInformation() { if(!initialized) readProperties(); @@ -115,7 +128,7 @@ public abstract class POIDocument { /** * Find, and create objects for, the standard - * Documment Information Properties (HPSF). + * Document Information Properties (HPSF). * If a given property set is missing or corrupt, * it will remain null; */ @@ -145,6 +158,9 @@ public abstract class POIDocument { /** * For a given named property entry, either return it or null if * if it wasn't found + * + * @param setName The property to read + * @return The value of the given property or null if it wasn't found. */ protected PropertySet getPropertySet(String setName) { //directory can be null when creating new documents @@ -178,6 +194,9 @@ public abstract class POIDocument { /** * Writes out the standard Documment Information Properties (HPSF) * @param outFS the POIFSFileSystem to write the properties into + * + * @throws IOException if an error when writing to the + * {@link POIFSFileSystem} occurs */ protected void writeProperties(POIFSFileSystem outFS) throws IOException { writeProperties(outFS, null); @@ -186,6 +205,9 @@ public abstract class POIDocument { * Writes out the standard Documment Information Properties (HPSF) * @param outFS the POIFSFileSystem to write the properties into * @param writtenEntries a list of POIFS entries to add the property names too + * + * @throws IOException if an error when writing to the + * {@link POIFSFileSystem} occurs */ protected void writeProperties(POIFSFileSystem outFS, List writtenEntries) throws IOException { SummaryInformation si = getSummaryInformation(); @@ -209,6 +231,9 @@ public abstract class POIDocument { * @param name the (POIFS Level) name of the property to write * @param set the PropertySet to write out * @param outFS the POIFSFileSystem to write the property into + * + * @throws IOException if an error when writing to the + * {@link POIFSFileSystem} occurs */ protected void writePropertySet(String name, PropertySet set, POIFSFileSystem outFS) throws IOException { try { @@ -227,7 +252,12 @@ public abstract class POIDocument { } /** - * Writes the document out to the specified output stream + * Writes the document out to the specified output stream. The + * stream is not closed as part of this operation. + * + * @param out The stream to write to. + * + * @throws IOException thrown on errors writing to the stream */ public abstract void write(OutputStream out) throws IOException; @@ -236,6 +266,9 @@ public abstract class POIDocument { * @param source is the source POIFS to copy from * @param target is the target POIFS to copy to * @param excepts is a list of Strings specifying what nodes NOT to copy + * + * @throws IOException thrown on errors writing to the target file system. + * * @deprecated Use {@link EntryUtils#copyNodes(DirectoryEntry, DirectoryEntry, List)} instead */ @Deprecated @@ -249,6 +282,9 @@ public abstract class POIDocument { * @param sourceRoot is the source POIFS to copy from * @param targetRoot is the target POIFS to copy to * @param excepts is a list of Strings specifying what nodes NOT to copy + * + * @throws IOException thrown on errors writing to the target directory node. + * * @deprecated Use {@link EntryUtils#copyNodes(DirectoryEntry, DirectoryEntry, List)} instead */ @Deprecated @@ -260,6 +296,12 @@ public abstract class POIDocument { /** * Copies an Entry into a target POIFS directory, recursively + * + * @param entry the entry to copy from + * @param target the entry to write to + * + * @throws IOException thrown on errors writing to the target directory entry. + * * @deprecated Use {@link EntryUtils#copyNodeRecursively(Entry, DirectoryEntry)} instead */ @Internal diff --git a/src/java/org/apache/poi/POIOLE2TextExtractor.java b/src/java/org/apache/poi/POIOLE2TextExtractor.java index 00930c3fdd..f5cbd95f1d 100644 --- a/src/java/org/apache/poi/POIOLE2TextExtractor.java +++ b/src/java/org/apache/poi/POIOLE2TextExtractor.java @@ -36,6 +36,8 @@ import org.apache.poi.poifs.filesystem.POIFSFileSystem; public abstract class POIOLE2TextExtractor extends POITextExtractor { /** * Creates a new text extractor for the given document + * + * @param The POIDocument to use in this extractor. */ public POIOLE2TextExtractor(POIDocument document) { super(document); @@ -43,12 +45,18 @@ public abstract class POIOLE2TextExtractor extends POITextExtractor { /** * Returns the document information metadata for the document + * + * @return The Document Summary Information or null + * if it could not be read for this document. */ public DocumentSummaryInformation getDocSummaryInformation() { return document.getDocumentSummaryInformation(); } /** - * Returns the summary information metadata for the document + * Returns the summary information metadata for the document. + * + * @return The Summary information for the document or null + * if it could not be read for this document. */ public SummaryInformation getSummaryInformation() { return document.getSummaryInformation(); @@ -57,11 +65,18 @@ public abstract class POIOLE2TextExtractor extends POITextExtractor { /** * Returns an HPSF powered text extractor for the * document properties metadata, such as title and author. + * + * @return an instance of POIExtractor that can extract meta-data. */ public POITextExtractor getMetadataTextExtractor() { return new HPSFPropertiesExtractor(this); } + /** + * Return the underlying DirectoryEntry of this document. + * + * @return the DirectoryEntry that is associated with the POIDocument of this extractor. + */ public DirectoryEntry getRoot() { return document.directory; @@ -69,6 +84,8 @@ public abstract class POIOLE2TextExtractor extends POITextExtractor { /** * Return the underlying POIFS FileSystem of this document. + * + * @return the POIFSFileSystem that is associated with the POIDocument of this extractor. * * @deprecated Use {@link #getRoot()} instead */ diff --git a/src/java/org/apache/poi/hssf/model/InternalWorkbook.java b/src/java/org/apache/poi/hssf/model/InternalWorkbook.java index 1e88e94b07..580d48d025 100644 --- a/src/java/org/apache/poi/hssf/model/InternalWorkbook.java +++ b/src/java/org/apache/poi/hssf/model/InternalWorkbook.java @@ -568,7 +568,7 @@ public final class InternalWorkbook { /** * sets the name for a given sheet. If the boundsheet record doesn't exist and - * its only one more than we have, go ahead and create it. If it's > 1 more than + * its only one more than we have, go ahead and create it. If it's > 1 more than * we have, except * * @param sheetnum the sheet number (0 based)