Improved javadoc comments.

git-svn-id: https://svn.apache.org/repos/asf/lucene/java/trunk@149828 13f79535-47bb-0310-9956-ffa450edef68

default.properties

@@ -29,7 +29,7 @@ dist-src.dir = ${final.name}-src
 packages=org.apache.lucene.*
 
 # javadoc link
-javadoc.link=http://java.sun.com/products/jdk/1.3/docs/api/
+javadoc.link=http://java.sun.com/j2se/1.4/docs/api/
 
 build.compiler.pedantic=false
 

src/java/org/apache/lucene/store/Directory.java

@@ -56,22 +56,19 @@ package org.apache.lucene.store;
 
 import java.io.IOException;
 
-/*
-  Java's filesystem API is not used directly, but rather through these
-  classes.  This permits:
-    . implementation of RAM-based indices, useful for summarization, etc.;
-    . implementation of an index as a single file.
-
-*/
-
-/**
-  A Directory is a flat list of files.  Files may be written once,
-  when they are created.  Once a file is created it may only be opened for
-  read, or deleted.  Random access is permitted when reading and writing.
-
-    @author Doug Cutting
-*/
-
+/** A Directory is a flat list of files.  Files may be written once, when they
+ * are created.  Once a file is created it may only be opened for read, or
+ * deleted.  Random access is permitted both when reading and writing.
+ *
+ * <p> Java's i/o APIs not used directly, but rather all i/o is
+ * through this API.  This permits things such as: <ul> 
+ * <li> implementation of RAM-based indices;
+ * <li> implementation indices stored in a database, via JDBC;
+ * <li> implementation of an index as a single file;
+ * </ul>
+ *
+ * @author Doug Cutting
+ */
 abstract public class Directory {
   /** Returns an array of strings, one for each file in the directory. */
   abstract public String[] list()

src/java/org/apache/lucene/store/FSDirectory.java

@@ -63,9 +63,9 @@ import java.util.Hashtable;
 import org.apache.lucene.util.Constants;
 
 /**
- * Straightforward implementation of Directory as a directory of files.
- * If the system property 'disableLuceneLocks' has the String value of "true",
- * lock creation will be disabled.
+ * Straightforward implementation of {@link Directory} as a directory of files.
+ * <p>If the system property 'disableLuceneLocks' has the String value of
+ * "true", lock creation will be disabled.
  *
  * @see Directory
  * @author Doug Cutting
@@ -217,14 +217,13 @@ final public class FSDirectory extends Directory {
     return new FSInputStream(new File(directory, name));
   }
 
-  /**
-   * Constructs a {@link Lock} with the specified name.
-   * If JDK 1.1 is used the lock file is not really made.
-   * If system property <I>disableLuceneLocks</I> has the value of 'true'
-   * the lock will not be created.  Assigning this property any other value
-   * will <B>not</B> prevent creation of locks.
-   * <BR>
-   * This is useful for using Lucene on read-only medium, such as CD-ROM.
+  /** Constructs a {@link Lock} with the specified name.  Locks are implemented
+   * with {@link File#createNewFile() }.
+   *
+   * <p>In JDK 1.1 or if system property <I>disableLuceneLocks</I> is the
+   * string "true", locks are disabled.  Assigning this property any other
+   * string will <B>not</B> prevent creation of lock files.  This is useful for
+   * using Lucene on read-only medium, such as CD-ROM.
    *
    * @param name the name of the lock file
    * @return an instance of <code>Lock</code> holding the lock

src/java/org/apache/lucene/store/InputStream.java

@@ -56,12 +56,11 @@ package org.apache.lucene.store;
 
 import java.io.IOException;
 
-/**
-  Abstract class for input from a file in a Directory.
-  @author Doug Cutting
-*/
-
-/** A random-access input stream */
+/** Abstract base class for input from a file in a {@link Directory}.  A
+ * random-access input stream.  Used for all Lucene index input operations.
+ * @see Directory
+ * @see OutputStream
+ */
 abstract public class InputStream implements Cloneable {
   final static int BUFFER_SIZE = OutputStream.BUFFER_SIZE;
 
@@ -74,13 +73,21 @@ abstract public class InputStream implements Cloneable {
 
   protected long length;			  // set by subclasses
 
-  /** InputStream-like methods @see java.io.InputStream */
+  /** Reads and returns a single byte.
+   * @see OutputStream#writeByte(byte)
+   */
   public final byte readByte() throws IOException {
     if (bufferPosition >= bufferLength)
       refill();
     return buffer[bufferPosition++];
   }
 
+  /** Reads a specified number of bytes into an array at the specified offset.
+   * @param b the array to read bytes into
+   * @param offset the offset in the array to start storing bytes
+   * @param len the number of bytes to read
+   * @see OutputStream#writeBytes(byte[],int)
+   */
   public final void readBytes(byte[] b, int offset, int len)
        throws IOException {
     if (len < BUFFER_SIZE) {
@@ -97,11 +104,19 @@ abstract public class InputStream implements Cloneable {
     }
   }
 
+  /** Reads four bytes and returns an int.
+   * @see OutputStream#writeInt(int)
+   */
   public final int readInt() throws IOException {
     return ((readByte() & 0xFF) << 24) | ((readByte() & 0xFF) << 16)
          | ((readByte() & 0xFF) <<  8) |  (readByte() & 0xFF);
   }
 
+  /** Reads an int stored in variable-length format.  Reads between one and
+   * five bytes.  Smaller values take fewer bytes.  Negative numbers are not
+   * supported.
+   * @see OutputStream#writeVInt(int)
+   */
   public final int readVInt() throws IOException {
     byte b = readByte();
     int i = b & 0x7F;
@@ -112,10 +127,16 @@ abstract public class InputStream implements Cloneable {
     return i;
   }
 
+  /** Reads eight bytes and returns a long.
+   * @see OutputStream#writeLong(long)
+   */
   public final long readLong() throws IOException {
     return (((long)readInt()) << 32) | (readInt() & 0xFFFFFFFFL);
   }
 
+  /** Reads a long stored in variable-length format.  Reads between one and
+   * nine bytes.  Smaller values take fewer bytes.  Negative numbers are not
+   * supported. */
   public final long readVLong() throws IOException {
     byte b = readByte();
     long i = b & 0x7F;
@@ -126,6 +147,9 @@ abstract public class InputStream implements Cloneable {
     return i;
   }
 
+  /** Reads a string.
+   * @see OutputStream#writeString(String)
+   */
   public final String readString() throws IOException {
     int length = readVInt();
     if (chars == null || length > chars.length)
@@ -134,6 +158,12 @@ abstract public class InputStream implements Cloneable {
     return new String(chars, 0, length);
   }
 
+  /** Reads UTF-8 encoded characters into an array.
+   * @param buffer the array to read characters into
+   * @param start the offset in the array to start storing characters
+   * @param length the number of characters to read
+   * @see OutputStream#writeChars(String,int,int)
+   */
   public final void readChars(char[] buffer, int start, int length)
        throws IOException {
     final int end = start + length;
@@ -152,7 +182,7 @@ abstract public class InputStream implements Cloneable {
   }
 
 
-  protected final void refill() throws IOException {
+  private void refill() throws IOException {
     long start = bufferStart + bufferPosition;
     long end = start + BUFFER_SIZE;
     if (end > length)				  // don't read past EOF
@@ -169,16 +199,29 @@ abstract public class InputStream implements Cloneable {
     bufferPosition = 0;
   }
 
+  /** Expert: implements buffer refill.  Reads bytes from the current position
+   * in the input.
+   * @param b the array to read bytes into
+   * @param offset the offset in the array to start storing bytes
+   * @param length the number of bytes to read
+   */
   abstract protected void readInternal(byte[] b, int offset, int length)
        throws IOException;
 
+  /** Closes the stream to futher operations. */
   abstract public void close() throws IOException;
 
-  /** RandomAccessFile-like methods @see java.io.RandomAccessFile */
+  /** Returns the current position in this file, where the next read will
+   * occur.
+   * @see #seek(long)
+   */
   public final long getFilePointer() {
     return bufferStart + bufferPosition;
   }
 
+  /** Sets current position in this file, where the next read will occur.
+   * @see #getFilePointer()
+   */
   public final void seek(long pos) throws IOException {
     if (pos >= bufferStart && pos < (bufferStart + bufferLength))
       bufferPosition = (int)(pos - bufferStart);  // seek within buffer
@@ -189,12 +232,27 @@ abstract public class InputStream implements Cloneable {
       seekInternal(pos);
     }
   }
+
+  /** Expert: implements seek.  Sets current position in this file, where the
+   * next {@link #readInternal(byte[],int,int)} will occur.
+   * @see #readInternal(byte[],int,int)
+   */
   abstract protected void seekInternal(long pos) throws IOException;
 
+  /** The number of bytes in the file. */
   public final long length() {
     return length;
   }
 
+  /** Returns a clone of this stream.
+   *
+   * <p>Clones of a stream access the same data, and are positioned at the same
+   * point as the stream they were cloned from.
+   *
+   * <p>Expert: Subclasses must ensure that clones may be positioned at
+   * different points in the input from each other and from the stream they
+   * were cloned from.
+   */
   public Object clone() {
     InputStream clone = null;
     try {

src/java/org/apache/lucene/store/OutputStream.java

@@ -56,12 +56,11 @@ package org.apache.lucene.store;
 
 import java.io.IOException;
 
-/**
-  Abstract class for output from a file in a Directory.
-  @author Doug Cutting
-*/
-
-/** A random-access output stream */
+/** Abstract class for output to a file in a Directory.  A random-access output
+ * stream.  Used for all Lucene index output operations.
+ * @see Directory
+ * @see InputStream
+ */ 
 abstract public class OutputStream {
   final static int BUFFER_SIZE = 1024;
 
@@ -69,18 +68,28 @@ abstract public class OutputStream {
   private long bufferStart = 0;			  // position in file of buffer
   private int bufferPosition = 0;		  // position in buffer
 
-  /** OutputStream-like methods @see java.io.InputStream */
+  /** Writes a single byte.
+   * @see InputStream#readByte()
+   */
   public final void writeByte(byte b) throws IOException {
     if (bufferPosition >= BUFFER_SIZE)
       flush();
     buffer[bufferPosition++] = b;
   }
 
+  /** Writes an array of bytes.
+   * @param b the bytes to write
+   * @param length the number of bytes to write
+   * @see InputStream#readBytes(byte[],int,int)
+   */
   public final void writeBytes(byte[] b, int length) throws IOException {
     for (int i = 0; i < length; i++)
       writeByte(b[i]);
   }
 
+  /** Writes an int as four bytes.
+   * @see InputStream#readInt()
+   */
   public final void writeInt(int i) throws IOException {
     writeByte((byte)(i >> 24));
     writeByte((byte)(i >> 16));
@@ -88,6 +97,11 @@ abstract public class OutputStream {
     writeByte((byte) i);
   }
 
+  /** Writes an int in a variable-length format.  Writes between one and
+   * five bytes.  Smaller values take fewer bytes.  Negative numbers are not
+   * supported.
+   * @see InputStream#readVInt()
+   */
   public final void writeVInt(int i) throws IOException {
     while ((i & ~0x7F) != 0) {
       writeByte((byte)((i & 0x7f) | 0x80));
@@ -96,11 +110,19 @@ abstract public class OutputStream {
     writeByte((byte)i);
   }
 
+  /** Writes a long as eight bytes.
+   * @see InputStream#readLong()
+   */
   public final void writeLong(long i) throws IOException {
     writeInt((int) (i >> 32));
     writeInt((int) i);
   }
 
+  /** Writes an long in a variable-length format.  Writes between one and five
+   * bytes.  Smaller values take fewer bytes.  Negative numbers are not
+   * supported.
+   * @see InputStream#readVLong()
+   */
   public final void writeVLong(long i) throws IOException {
     while ((i & ~0x7F) != 0) {
       writeByte((byte)((i & 0x7f) | 0x80));
@@ -109,12 +131,21 @@ abstract public class OutputStream {
     writeByte((byte)i);
   }
 
+  /** Writes a string.
+   * @see InputStream#readString()
+   */
   public final void writeString(String s) throws IOException {
     int length = s.length();
     writeVInt(length);
     writeChars(s, 0, length);
   }
 
+  /** Writes a sequence of UTF-8 encoded characters from a string.
+   * @param s the source of the characters
+   * @param start the first character in the sequence
+   * @param length the number of characters in the sequence
+   * @see InputStream#readChars(char[],int,int)
+   */
   public final void writeChars(String s, int start, int length)
        throws IOException {
     final int end = start + length;
@@ -133,28 +164,42 @@ abstract public class OutputStream {
     }
   }
 
+  /** Forces any buffered output to be written. */
   protected final void flush() throws IOException {
     flushBuffer(buffer, bufferPosition);
     bufferStart += bufferPosition;
     bufferPosition = 0;
   }
 
+  /** Expert: implements buffer write.  Writes bytes at the current position in
+   * the output.
+   * @param b the bytes to write
+   * @param len the number of bytes to write
+   */
   abstract protected void flushBuffer(byte[] b, int len) throws IOException;
 
+  /** Closes this stream to further operations. */
   public void close() throws IOException {
     flush();
   }
 
-  /** RandomAccessFile-like methods @see java.io.RandomAccessFile */
+  /** Returns the current position in this file, where the next write will
+   * occur.
+   * @see #seek(long)
+   */
   public final long getFilePointer() throws IOException {
     return bufferStart + bufferPosition;
   }
 
+  /** Sets current position in this file, where the next write will occur.
+   * @see #getFilePointer()
+   */
   public void seek(long pos) throws IOException {
     flush();
     bufferStart = pos;
   }
 
+  /** The number of bytes in the file. */
   abstract public long length() throws IOException;
 
 

src/java/org/apache/lucene/store/RAMDirectory.java

@@ -63,9 +63,11 @@ import org.apache.lucene.store.Directory;
 import org.apache.lucene.store.InputStream;
 import org.apache.lucene.store.OutputStream;
 
+/** A memory-resident {@link Directory} implementation. */
 final public class RAMDirectory extends Directory {
   Hashtable files = new Hashtable();
 
+  /** Constructs an empty {@link Directory}. */
   public RAMDirectory() {
   }
 

src/java/org/apache/lucene/store/package.html

@@ -5,6 +5,6 @@
    <meta name="Author" content="Doug Cutting">
 </head>
 <body>
-Binary i/o API, for storing index data.
+Binary i/o API, used for all index data.
 </body>
 </html>