Improve the docs for XZInputStream and SingleXZInputStream.
diff --git a/src/org/tukaani/xz/SingleXZInputStream.java b/src/org/tukaani/xz/SingleXZInputStream.java
index ffac554..58552f8 100644
--- a/src/org/tukaani/xz/SingleXZInputStream.java
+++ b/src/org/tukaani/xz/SingleXZInputStream.java
@@ -28,6 +28,15 @@
* Unless you know what you are doing, don't use this class to decompress
* standalone .xz files. For that purpose, use <code>XZInputStream</code>.
*
+ * <h4>When uncompressed size is known beforehand</h4>
+ * <p>
+ * If you are decompressing complete XZ streams and your application knows
+ * exactly how much uncompressed data there should be, it is good to try
+ * reading one more byte by calling <code>read()</code> and checking
+ * that it returns <code>-1</code>. This way the decompressor will parse the
+ * file footers and verify the integrity checks, giving the caller more
+ * confidence that the uncompressed data is valid.
+ *
* @see XZInputStream
*/
public class SingleXZInputStream extends InputStream {
@@ -41,8 +50,8 @@
private IOException exception = null;
/**
- * Creates a new input stream that decompresses exactly one XZ Stream
- * from <code>in</code>.
+ * Creates a new XZ decompressor that decompresses exactly one
+ * XZ Stream from <code>in</code> without a memory usage limit.
* <p>
* This constructor reads and parses the XZ Stream Header (12 bytes)
* from <code>in</code>. The header of the first Block is not read
@@ -72,8 +81,8 @@
}
/**
- * Creates a new single-stream XZ decompressor with optional
- * memory usage limit.
+ * Creates a new XZ decompressor that decompresses exactly one
+ * XZ Stream from <code>in</code> with an optional memory usage limit.
* <p>
* This is identical to <code>SingleXZInputStream(InputStream)</code>
* except that this takes also the <code>memoryLimit</code> argument.
diff --git a/src/org/tukaani/xz/XZInputStream.java b/src/org/tukaani/xz/XZInputStream.java
index ac4fca7..404c70c 100644
--- a/src/org/tukaani/xz/XZInputStream.java
+++ b/src/org/tukaani/xz/XZInputStream.java
@@ -23,6 +23,41 @@
* its input stream until the end of the input or until an error occurs.
* This supports decompressing concatenated .xz files.
*
+ * <h4>Typical use cases</h4>
+ * <p>
+ * Getting an input stream to decompress a .xz file:
+ * <p><blockquote><pre>
+ * InputStream infile = new FileInputStream("foo.xz");
+ * XZInputStream inxz = new XZInputStream(infile);
+ * </pre></blockquote>
+ * <p>
+ * It's important to keep in mind that decompressor memory usage depends
+ * on the settings used to compress the file. The worst-case memory usage
+ * of XZInputStream is currently 1.5 GiB. Still, very few files will
+ * require more than about 65 MiB because that's how much decompressing
+ * a file created with the highest preset level will need, and only a few
+ * people use settings other than the predefined presets.
+ * <p>
+ * It is possible to specify a memory usage limit for
+ * <code>XZInputStream</code>. If decompression requires more memory than
+ * the specified limit, MemoryLimitException will be thrown when reading
+ * from the stream. For example, the following sets the memory usage limit
+ * to 100 MiB:
+ * <p><blockquote><pre>
+ * InputStream infile = new FileInputStream("foo.xz");
+ * XZInputStream inxz = new XZInputStream(infile, 100 * 1024);
+ * </pre></blockquote>
+ *
+ * <h4>When uncompressed size is known beforehand</h4>
+ * <p>
+ * If you are decompressing complete files and your application knows
+ * exactly how much uncompressed data there should be, it is good to try
+ * reading one more byte by calling <code>read()</code> and checking
+ * that it returns <code>-1</code>. This way the decompressor will parse the
+ * file footers and verify the integrity checks, giving the caller more
+ * confidence that the uncompressed data is valid. (This advice seems to
+ * apply to <code>java.util.zip.GZIPInputStream</code> too.)
+ *
* @see SingleXZInputStream
*/
public class XZInputStream extends InputStream {
@@ -33,8 +68,7 @@
private IOException exception = null;
/**
- * Creates a new input stream that decompresses XZ-compressed data
- * from <code>in</code>.
+ * Creates a new XZ decompressor without a memory usage limit.
* <p>
* This constructor reads and parses the XZ Stream Header (12 bytes)
* from <code>in</code>. The header of the first Block is not read
@@ -66,8 +100,7 @@
}
/**
- * Creates a new input stream that decompresses XZ-compressed data
- * from <code>in</code>.
+ * Creates a new XZ decompressor with an optional memory usage limit.
* <p>
* This is identical to <code>XZInputStream(InputStream)</code> except
* that this takes also the <code>memoryLimit</code> argument.