You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@poi.apache.org by ce...@apache.org on 2014/07/27 20:32:24 UTC
svn commit: r1613826 - in /poi/trunk/src/java/org/apache/poi:
POIDocument.java POIOLE2TextExtractor.java hssf/model/InternalWorkbook.java
Author: centic
Date: Sun Jul 27 18:32:24 2014
New Revision: 1613826
URL: http://svn.apache.org/r1613826
Log:
Add/Fix some Javadoc
Modified:
poi/trunk/src/java/org/apache/poi/POIDocument.java
poi/trunk/src/java/org/apache/poi/POIOLE2TextExtractor.java
poi/trunk/src/java/org/apache/poi/hssf/model/InternalWorkbook.java
Modified: poi/trunk/src/java/org/apache/poi/POIDocument.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/java/org/apache/poi/POIDocument.java?rev=1613826&r1=1613825&r2=1613826&view=diff
==============================================================================
--- poi/trunk/src/java/org/apache/poi/POIDocument.java (original)
+++ poi/trunk/src/java/org/apache/poi/POIDocument.java Sun Jul 27 18:32:24 2014
@@ -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<String> 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
Modified: poi/trunk/src/java/org/apache/poi/POIOLE2TextExtractor.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/java/org/apache/poi/POIOLE2TextExtractor.java?rev=1613826&r1=1613825&r2=1613826&view=diff
==============================================================================
--- poi/trunk/src/java/org/apache/poi/POIOLE2TextExtractor.java (original)
+++ poi/trunk/src/java/org/apache/poi/POIOLE2TextExtractor.java Sun Jul 27 18:32:24 2014
@@ -36,6 +36,8 @@ import org.apache.poi.poifs.filesystem.P
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 POIOLE2TextExtract
/**
* 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 POIOLE2TextExtract
/**
* 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 POIOLE2TextExtract
/**
* 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
*/
Modified: poi/trunk/src/java/org/apache/poi/hssf/model/InternalWorkbook.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/java/org/apache/poi/hssf/model/InternalWorkbook.java?rev=1613826&r1=1613825&r2=1613826&view=diff
==============================================================================
--- poi/trunk/src/java/org/apache/poi/hssf/model/InternalWorkbook.java (original)
+++ poi/trunk/src/java/org/apache/poi/hssf/model/InternalWorkbook.java Sun Jul 27 18:32:24 2014
@@ -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)
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@poi.apache.org
For additional commands, e-mail: commits-help@poi.apache.org