[FOray-commit] SF.net SVN: foray: [8130] trunk/foray

[<vic...@us...>]

Revision: 8130
          http://svn.sourceforge.net/foray/?rev=8130&view=rev
Author:   victormote
Date:     2006-09-15 17:20:00 -0700 (Fri, 15 Sep 2006)

Log Message:
-----------
Add some javadoc.

Modified Paths:
--------------
    trunk/foray/foray-common/src/java/org/foray/common/RandomReader.java
    trunk/foray/scripts/checkstyle-suppressions.xml

Modified: trunk/foray/foray-common/src/java/org/foray/common/RandomReader.java
===================================================================
--- trunk/foray/foray-common/src/java/org/foray/common/RandomReader.java	2006-09-15 23:52:41 UTC (rev 8129)
+++ trunk/foray/foray-common/src/java/org/foray/common/RandomReader.java	2006-09-16 00:20:00 UTC (rev 8130)
@@ -277,8 +277,11 @@
     }
 
     /**
-     * Read 4 unsigned bytes. Returns a long because int is signed,
-     * and therefore can't hold 32 unsigned bits.
+     * Read 4 unsigned bytes.
+     * @return A long containing the unsigned 32-bit value.
+     * Returns a long because int is signed, and therefore can't hold 32
+     * unsigned bits.
+     * @throws IOException For I/O error.
      */
     public final long readUnsignedInt() throws IOException {
         long ret = readUnsignedByte();
@@ -293,6 +296,7 @@
      * lowest-order byte first and the highest-order byte last.
      *
      * @return The unsigned integral.
+     * @throws IOException For I/O error.
      */
     public long readUnsignedIntLoHi() throws IOException {
         final int byte1 = readUnsignedByte();
@@ -309,8 +313,8 @@
     /**
      * Read an unsigned 2-byte short, and reverse the byte order, making the
      * low-order byte first and the high-order byte last.
-     *
      * @return The unsigned integral.
+     * @throws IOException For I/O error.
      */
     public int readUnsignedShortLoHi() throws IOException {
         final int byte1 = readUnsignedByte();
@@ -322,6 +326,7 @@
      * Read a signed 2-byte short in little-endian order, that is, making the
      * first byte the low-order byte and the second byte the high-order byte.
      * @return The unsigned integral.
+     * @throws IOException For I/O error.
      */
     public int readShortLoHi() throws IOException {
         final short beShort = readShort();
@@ -333,6 +338,8 @@
      * @param stringSize The length, in bytes, of the String to be read.
      * @param charEncoding The encoding scheme to be used for interpreting the
      * characters in the string.
+     * @return The read String.
+     * @throws IOException For I/O error.
      */
     public String readString(final int stringSize, String charEncoding)
             throws IOException {
@@ -351,8 +358,12 @@
     /**
      * Reads a string terminated by a specific character, usually the null
      * character, 0x00.
-     *
+     * @param terminatingChar The value to be used as the terminator for the
+     * read String.
+     * @param charEncoding The name of the character encoding to use when
+     * converting the read bytes to chars.
      * @return The string read.
+     * @throws IOException For I/O error.
      */
     public String readTerminatedString(final byte terminatingChar,
             final String charEncoding) throws IOException {
@@ -372,6 +383,11 @@
         return readString(stringSize, charEncoding);
     }
 
+    /**
+     * Reads a null-terminated String.
+     * @return The read String.
+     * @throws IOException For I/O error.
+     */
     public String readNullTerminatedString() throws IOException {
         return readTerminatedString((byte) 0x00, CHAR_ENCODE_ISO_8859_1);
     }
@@ -582,6 +598,11 @@
 
         /**
          * Constructor.
+         * @param bytesToFind The bytes which are sought in the input.
+         * @param startRange Index to the first byte which should be searched.
+         * @param endRange Index to the last byte which should be searched.
+         * @param readBackward True if we are searching backward, false if we
+         * are searching forward.
          */
         ByteSearcher(final byte[] bytesToFind, final long startRange,
                 final long endRange, final boolean readBackward) {
@@ -591,6 +612,12 @@
             this.readBackward = readBackward;
         }
 
+        /**
+         * Searches the content for the sought byte sequence.
+         * @return The index to the beginning of the sought byte sequence, or
+         * -1 if the sought byte sequence is not in the input.
+         * @throws IOException For I/O error.
+         */
         private long searchBytes() throws IOException {
             if (! isInputValid()) {
                 return -1;
@@ -609,7 +636,8 @@
             readNextChunk();
             readNextChunk();
 
-            while (offsetToContent < 0 && ! endOfFile) {
+            while (offsetToContent < 0
+                    && ! endOfFile) {
                 searchForMatch();
                 if (endOfFile) {
                     return -1;
@@ -619,6 +647,9 @@
             return offsetToContent;
         }
 
+        /**
+         * Searches the current viewbox for the sought byte sequence.
+         */
         private void searchForMatch() {
             if (readBackward) {
                 while (viewboxPointer >= IDEAL_READ_SIZE) {
@@ -641,10 +672,18 @@
             }
         }
 
+        /**
+         * Computes the offset to the sought content.
+         * @param i The current viewbox index.
+         */
         private void computeOffsetToContent(final int i) {
             offsetToContent = lastReadStart - lastViewboxTarget + i;
         }
 
+        /**
+         * Reads another chunk of the input for processing.
+         * @throws IOException For I/O error.
+         */
         private void readNextChunk() throws IOException {
             if (endOfFile) {
                 return;
@@ -699,6 +738,10 @@
             lastViewboxTarget = viewboxTarget;
         }
 
+        /**
+         * Computes the read start value.
+         * @return The read start value.
+         */
         private long computeReadStart() {
             long value;
             if (lastReadStart == -1) {
@@ -720,6 +763,10 @@
             return value;
         }
 
+        /**
+         * Computes the read end value.
+         * @return The read end value.
+         */
         private long computeReadEnd() {
             long value;
             if (lastReadStart == -1) {
@@ -741,6 +788,10 @@
             return value;
         }
 
+        /**
+         * Computes the viewbox target.
+         * @return The new viewbox target.
+         */
         private int computeViewboxTarget() {
             if (readBackward) {
                 return 0;
@@ -748,6 +799,11 @@
             return VIEWBOX_SIZE - actualReadSize;
         }
 
+        /**
+         * Indicates whether the input is valid.
+         * @return True iff the input is valid.
+         * @throws IOException For I/O error.
+         */
         private boolean isInputValid() throws IOException {
             if (startRange < 0) {
                 return false;

Modified: trunk/foray/scripts/checkstyle-suppressions.xml
===================================================================
--- trunk/foray/scripts/checkstyle-suppressions.xml	2006-09-15 23:52:41 UTC (rev 8129)
+++ trunk/foray/scripts/checkstyle-suppressions.xml	2006-09-16 00:20:00 UTC (rev 8130)
@@ -26,8 +26,6 @@
       files="org.foray.demo.*"/>
   <suppress checks="Javadoc[MVS].*"
       files="org.foray.area.*"/>
-  <suppress checks="Javadoc[M].*"
-      files="org.foray.common.*"/>
   <suppress checks="Javadoc[MVS].*"
       files="org.foray.core.*"/>
   <suppress checks="Javadoc[MVS].*"


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.