From fc2998c82e81cb5920d2ad04e7fa8725d901b6e1 Mon Sep 17 00:00:00 2001 From: Andreas Beeker Date: Tue, 5 Jun 2018 22:44:18 +0000 Subject: [PATCH] javadoc fixes git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1832978 13f79535-47bb-0310-9956-ffa450edef68 --- .../ole2/OLE2ScratchpadExtractorFactory.java | 11 +++++++++ .../src/org/apache/poi/hdgf/HDGFDiagram.java | 17 +++++-------- .../src/org/apache/poi/hdgf/HDGFLZW.java | 11 +++++++++ .../src/org/apache/poi/hdgf/chunks/Chunk.java | 24 +++++++++++++++++-- .../apache/poi/hdgf/chunks/ChunkFactory.java | 7 ++++-- .../apache/poi/hdgf/chunks/ChunkHeader.java | 15 +++++++++++- 6 files changed, 69 insertions(+), 16 deletions(-) diff --git a/src/scratchpad/src/org/apache/poi/extractor/ole2/OLE2ScratchpadExtractorFactory.java b/src/scratchpad/src/org/apache/poi/extractor/ole2/OLE2ScratchpadExtractorFactory.java index 1e3ebdc74..3201f633e 100644 --- a/src/scratchpad/src/org/apache/poi/extractor/ole2/OLE2ScratchpadExtractorFactory.java +++ b/src/scratchpad/src/org/apache/poi/extractor/ole2/OLE2ScratchpadExtractorFactory.java @@ -55,6 +55,11 @@ public class OLE2ScratchpadExtractorFactory { * out what format is desired * Note - doesn't check for core-supported formats! * Note - doesn't check for OOXML-supported formats + * + * @param poifsDir the directory node to be inspected + * @return the format specific text extractor + * + * @throws IOException when the format specific extraction fails because of invalid entires */ public static POITextExtractor createExtractor(DirectoryNode poifsDir) throws IOException { if (poifsDir.hasEntry("WordDocument")) { @@ -106,6 +111,12 @@ public class OLE2ScratchpadExtractorFactory { * 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 holding the directory to start parsing + * @param dirs a list to be filled with directory references holding embedded + * @param nonPOIFS a list to be filled with streams which aren't based on POIFS entries + * + * @throws IOException when the format specific extraction fails because of invalid entires */ public static void identifyEmbeddedResources(POIOLE2TextExtractor ext, List dirs, List nonPOIFS) throws IOException { // Find all the embedded directories diff --git a/src/scratchpad/src/org/apache/poi/hdgf/HDGFDiagram.java b/src/scratchpad/src/org/apache/poi/hdgf/HDGFDiagram.java index c85278882..63c371127 100644 --- a/src/scratchpad/src/org/apache/poi/hdgf/HDGFDiagram.java +++ b/src/scratchpad/src/org/apache/poi/hdgf/HDGFDiagram.java @@ -101,13 +101,19 @@ public final class HDGFDiagram extends POIReadOnlyDocument { /** * Returns the TrailerStream, which is at the root of the * tree of Streams. + * + * @return the TrailerStream */ public TrailerStream getTrailerStream() { return trailer; } + /** * Returns all the top level streams, which are the streams * pointed to by the TrailerStream. + * + * @return the top level streams */ public Stream[] getTopLevelStreams() { return trailer.getPointedToStreams(); } + public long getDocumentSize() { return docSize; } /** @@ -154,15 +160,4 @@ public final class HDGFDiagram extends POIReadOnlyDocument { } } } - - /** - * For testing only - */ - public static void main(String args[]) throws Exception { - NPOIFSFileSystem pfs = new NPOIFSFileSystem(new File(args[0])); - HDGFDiagram hdgf = new HDGFDiagram(pfs); - hdgf.debug(); - hdgf.close(); - pfs.close(); - } } diff --git a/src/scratchpad/src/org/apache/poi/hdgf/HDGFLZW.java b/src/scratchpad/src/org/apache/poi/hdgf/HDGFLZW.java index e6d4aa2e6..3d3a5cf1f 100644 --- a/src/scratchpad/src/org/apache/poi/hdgf/HDGFLZW.java +++ b/src/scratchpad/src/org/apache/poi/hdgf/HDGFLZW.java @@ -46,6 +46,11 @@ public class HDGFLZW extends LZWDecompresser { /** * Compress the given input stream, returning the array of bytes * of the compressed input + * + * @param src the compression source byte + * @return the compressed stream as bytes + * + * @throws IOException when the InputStream can't be read */ public byte[] compress(InputStream src) throws IOException { ByteArrayOutputStream res = new ByteArrayOutputStream(); @@ -76,6 +81,12 @@ public class HDGFLZW extends LZWDecompresser { /** * Performs the Visio compatible streaming LZW compression. + * + * @param src the input bytes for the compression + * @param res the OutputStream which receives the compressed bytes + * + * @throws IOException when the InputStream can't be read + * or the OutputStream can't be written to */ public void compress(InputStream src, OutputStream res) throws IOException { HDGFLZWCompressor c = new HDGFLZWCompressor(); diff --git a/src/scratchpad/src/org/apache/poi/hdgf/chunks/Chunk.java b/src/scratchpad/src/org/apache/poi/hdgf/chunks/Chunk.java index dd345e159..c63a0493a 100644 --- a/src/scratchpad/src/org/apache/poi/hdgf/chunks/Chunk.java +++ b/src/scratchpad/src/org/apache/poi/hdgf/chunks/Chunk.java @@ -60,29 +60,47 @@ public final class Chunk { public byte[] _getContents() { return contents; } + public ChunkHeader getHeader() { return header; } - /** Gets the separator between this chunk and the next, if it exists */ + + /** + * Gets the separator between this chunk and the next, if it exists + * + * @return the separator + */ public ChunkSeparator getSeparator() { return separator; } - /** Gets the trailer for this chunk, if it exists */ + + /** + * Gets the trailer for this chunk, if it exists + * + * @return the trailer + */ public ChunkTrailer getTrailer() { return trailer; } + /** * Gets the command definitions, which define and describe much * of the data held by the chunk. + * + * @return the command definitions */ public CommandDefinition[] getCommandDefinitions() { return commandDefinitions; } + public Command[] getCommands() { return commands; } + /** * Get the name of the chunk, as found from the CommandDefinitions + * + * @return the name of the chunk */ public String getName() { return name; @@ -91,6 +109,8 @@ public final class Chunk { /** * Returns the size of the chunk, including any * headers, trailers and separators. + * + * @return the size of the chunk */ public int getOnDiskSize() { int size = header.getSizeInBytes() + contents.length; diff --git a/src/scratchpad/src/org/apache/poi/hdgf/chunks/ChunkFactory.java b/src/scratchpad/src/org/apache/poi/hdgf/chunks/ChunkFactory.java index b83979e14..e1ac0e8ad 100644 --- a/src/scratchpad/src/org/apache/poi/hdgf/chunks/ChunkFactory.java +++ b/src/scratchpad/src/org/apache/poi/hdgf/chunks/ChunkFactory.java @@ -128,8 +128,11 @@ public final class ChunkFactory { /** * Creates the appropriate chunk at the given location. - * @param data - * @param offset + * + * @param data the chunk bytes + * @param offset the offset into the chunk bytes array to start reading from + * + * @return the new Chunk */ public Chunk createChunk(byte[] data, int offset) { // Create the header diff --git a/src/scratchpad/src/org/apache/poi/hdgf/chunks/ChunkHeader.java b/src/scratchpad/src/org/apache/poi/hdgf/chunks/ChunkHeader.java index df7c9940b..d8c1d7a44 100644 --- a/src/scratchpad/src/org/apache/poi/hdgf/chunks/ChunkHeader.java +++ b/src/scratchpad/src/org/apache/poi/hdgf/chunks/ChunkHeader.java @@ -33,6 +33,11 @@ public abstract class ChunkHeader { /** * Creates the appropriate ChunkHeader for the Chunk Header at * the given location, for the given document version. + * + * @param documentVersion the documentVersion - 4 and higher is supported + * @param data the chunk data + * @param offset the start offset in the chunk data + * @return the ChunkHeader */ public static ChunkHeader createChunkHeader(int documentVersion, byte[] data, int offset) { if(documentVersion >= 6) { @@ -68,6 +73,10 @@ public abstract class ChunkHeader { /** * Returns the size of a chunk header for the given document version. + * + * @param documentVersion the documentVersion - 4 and higher is supported + * + * @return the header size */ public static int getHeaderSize(int documentVersion) { if(documentVersion > 6) { @@ -85,7 +94,7 @@ public abstract class ChunkHeader { public abstract Charset getChunkCharset(); /** - * Returns the ID/IX of the chunk + * @return the ID/IX of the chunk */ public int getId() { return id; @@ -94,6 +103,8 @@ public abstract class ChunkHeader { /** * Returns the length of the trunk, excluding the length * of the header, trailer or separator. + * + * @return the length of the trunk */ public int getLength() { return length; @@ -102,6 +113,8 @@ public abstract class ChunkHeader { /** * Returns the type of the chunk, which affects the * mandatory information + * + * @return the type of the chunk */ public int getType() { return type;