javadoc and a minor fix

git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@353537 13f79535-47bb-0310-9956-ffa450edef68

src/scratchpad/src/org/apache/poi/hwpf/HWPFDocument.java

@@ -392,7 +392,7 @@ public class HWPFDocument
     return _dataStream;
   }
 
-  public int registerList(List list)
+  public int registerList(HWPFList list)
   {
     if (_lt == null)
     {

src/scratchpad/src/org/apache/poi/hwpf/QuickTest.java

@@ -0,0 +1,72 @@
+package org.apache.poi.hwpf;
+
+import java.io.*;
+
+import org.apache.poi.hwpf.usermodel.*;
+
+public class QuickTest
+{
+  public QuickTest()
+  {
+  }
+
+  public static void main(String[] args)
+  {
+    try
+    {
+      HWPFDocument doc = new HWPFDocument (new FileInputStream (args[0]));
+      Range r = doc.getRange();
+
+      System.out.println("Example you supplied:");
+      System.out.println("---------------------");
+      for (int x = 0; x < r.numSections(); x++)
+      {
+        Section s = r.getSection(x);
+        for (int y = 0; y < s.numParagraphs(); y++)
+        {
+          Paragraph p = s.getParagraph(y);
+          for (int z = 0; z < p.numCharacterRuns(); z++)
+          {
+            //character run
+            CharacterRun run = p.getCharacterRun(z);
+            //character run text
+            String text = run.text();
+            // show us the text
+            System.out.print(text);
+          }
+          // use a new line at the paragraph break
+          System.out.println();
+        }
+      }
+
+
+//      System.out.println("\n\nExample using new method:");
+//      System.out.println("-------------------------");
+//      for (int x = 0; x < r.numSections(); x++)
+//      {
+//        Section s = r.getSection(x);
+//        for (int y = 0; y < s.numParagraphs(); y++)
+//        {
+//          Paragraph p = s.getParagraph(y);
+//          for (int z = 0; z < p.numCharacterRuns(); z++)
+//          {
+//             //character run
+//             CharacterRun run = p.getCharacterRun(z);
+//             //** get character run/paragraph common text **
+//             String text = run.commonText(p);
+//             // show us the text
+//             System.out.print(text);
+//          }
+//          // use a new line at the paragraph break
+//          System.out.println();
+//        }
+//      }
+
+    }
+    catch (Throwable t)
+    {
+      t.printStackTrace();
+    }
+  }
+
+}

src/scratchpad/src/org/apache/poi/hwpf/model/CHPX.java

@@ -65,7 +65,7 @@ import org.apache.poi.hwpf.sprm.CharacterSprmUncompressor;
  * @author Ryan Ackley
  */
 
-public class CHPX extends CachedPropertyNode
+public class CHPX extends PropertyNode
 {
 
   public CHPX(int fcStart, int fcEnd, byte[] grpprl)
@@ -84,17 +84,15 @@ public class CHPX extends CachedPropertyNode
     return ((SprmBuffer)_buf).toByteArray();
   }
 
+  public SprmBuffer getSprmBuf()
+  {
+    return (SprmBuffer)_buf;
+  }
+
   public CharacterProperties getCharacterProperties(StyleSheet ss, short istd)
-  {
-    CharacterProperties props = (CharacterProperties)super.getCacheContents();
-    if (props == null)
   {
     CharacterProperties baseStyle = ss.getCharacterStyle(istd);
-      props = CharacterSprmUncompressor.uncompressCHP(baseStyle, getGrpprl(), 0);
+    CharacterProperties props = CharacterSprmUncompressor.uncompressCHP(baseStyle, getGrpprl(), 0);
-      super.fillCache(props);
-    }
     return props;
   }
-
-
 }

src/scratchpad/src/org/apache/poi/hwpf/model/PAPX.java

@@ -69,7 +69,7 @@ import org.apache.poi.hwpf.sprm.SprmOperation;
  * @author Ryan Ackley
  */
 
-public class PAPX extends CachedPropertyNode
+public class PAPX extends PropertyNode
 {
 
   private ParagraphHeight _phe;
@@ -153,19 +153,17 @@ public class PAPX extends CachedPropertyNode
     }
   }
 
-  public ParagraphProperties getParagraphProperties(StyleSheet ss)
+  public SprmBuffer getSprmBuf()
   {
+    return (SprmBuffer)_buf;
+  }
 
-    ParagraphProperties props = (ParagraphProperties)super.getCacheContents();
+  public ParagraphProperties getParagraphProperties(StyleSheet ss)
-    if (props == null)
   {
     short istd = getIstd();
     ParagraphProperties baseStyle = ss.getParagraphStyle(istd);
-      props = ParagraphSprmUncompressor.uncompressPAP(baseStyle, getGrpprl(), 2);
+    ParagraphProperties props = ParagraphSprmUncompressor.uncompressPAP(baseStyle, getGrpprl(), 2);
-      super.fillCache(props);
-    }
     return props;
-
   }
 
   public boolean equals(Object o)

src/scratchpad/src/org/apache/poi/hwpf/usermodel/CharacterRun.java

@@ -1,56 +1,20 @@
 /* ====================================================================
- * The Apache Software License, Version 1.1
+   Copyright 2002-2004   Apache Software Foundation
- *
+
- * Copyright (c) 2003 The Apache Software Foundation.  All rights
+   Licensed under the Apache License, Version 2.0 (the "License");
- * reserved.
+   you may not use this file except in compliance with the License.
- *
+   You may obtain a copy of the License at
- * Redistribution and use in source and binary forms, with or without
+
- * modification, are permitted provided that the following conditions
+       http://www.apache.org/licenses/LICENSE-2.0
- * are met:
+
- *
+   Unless required by applicable law or agreed to in writing, software
- * 1. Redistributions of source code must retain the above copyright
+   distributed under the License is distributed on an "AS IS" BASIS,
- *    notice, this list of conditions and the following disclaimer.
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *
+   See the License for the specific language governing permissions and
- * 2. Redistributions in binary form must reproduce the above copyright
+   limitations under the License.
- *    notice, this list of conditions and the following disclaimer in
+==================================================================== */
- *    the documentation and/or other materials provided with the
+
- *    distribution.
+
- *
- * 3. The end-user documentation included with the redistribution,
- *    if any, must include the following acknowledgment:
- *       "This product includes software developed by the
- *        Apache Software Foundation (http://www.apache.org/)."
- *    Alternately, this acknowledgment may appear in the software itself,
- *    if and wherever such third-party acknowledgments normally appear.
- *
- * 4. The names "Apache" and "Apache Software Foundation" and
- *    "Apache POI" must not be used to endorse or promote products
- *    derived from this software without prior written permission. For
- *    written permission, please contact apache@apache.org.
- *
- * 5. Products derived from this software may not be called "Apache",
- *    "Apache POI", nor may "Apache" appear in their name, without
- *    prior written permission of the Apache Software Foundation.
- *
- * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
- * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
- * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
- * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
- * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
- * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
- * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- * SUCH DAMAGE.
- * ====================================================================
- *
- * This software consists of voluntary contributions made by many
- * individuals on behalf of the Apache Software Foundation.  For more
- * information on the Apache Software Foundation, please see
- * <http://www.apache.org/>.
- */
 
 package org.apache.poi.hwpf.usermodel;
 
@@ -62,6 +26,11 @@ import org.apache.poi.hwpf.model.StyleSheet;
 import org.apache.poi.hwpf.sprm.SprmBuffer;
 import org.apache.poi.hwpf.sprm.CharacterSprmCompressor;
 
+/**
+ * This class represents a run of text that share common properties.
+ *
+ * @author Ryan Ackley
+ */
 public class CharacterRun
   extends Range
   implements Cloneable
@@ -120,6 +89,13 @@ public class CharacterRun
   SprmBuffer _chpx;
   CharacterProperties _props;
 
+  /**
+   *
+   * @param chpx The chpx this object is based on.
+   * @param ss The stylesheet for the document this run belongs to.
+   * @param istd The style index if this run's base style.
+   * @param parent The parent range of this character run (usually a paragraph).
+   */
   CharacterRun(CHPX chpx, StyleSheet ss, short istd, Range parent)
   {
     super(Math.max(parent._start, chpx.getStart()), Math.min(parent._end, chpx.getEnd()), parent);
@@ -127,6 +103,11 @@ public class CharacterRun
     _chpx = chpx.getSprmBuf();
   }
 
+  /**
+   * Here for runtime type determination using a switch statement convenient.
+   *
+   * @return TYPE_CHARACTER
+   */
   public int type()
   {
     return TYPE_CHARACTER;
@@ -469,6 +450,12 @@ public class CharacterRun
     _props.setIco24(colour24);
   }
 
+  /**
+   * Used to create a deep copy of this object.
+   *
+   * @return A deep copy.
+   * @throws CloneNotSupportedException never
+   */
   public Object clone()
     throws CloneNotSupportedException
   {

src/scratchpad/src/org/apache/poi/hwpf/usermodel/DateAndTime.java

@@ -1,62 +1,31 @@
 /* ====================================================================
- * The Apache Software License, Version 1.1
+   Copyright 2002-2004   Apache Software Foundation
- *
+
- * Copyright (c) 2003 The Apache Software Foundation.  All rights
+   Licensed under the Apache License, Version 2.0 (the "License");
- * reserved.
+   you may not use this file except in compliance with the License.
- *
+   You may obtain a copy of the License at
- * Redistribution and use in source and binary forms, with or without
+
- * modification, are permitted provided that the following conditions
+       http://www.apache.org/licenses/LICENSE-2.0
- * are met:
+
- *
+   Unless required by applicable law or agreed to in writing, software
- * 1. Redistributions of source code must retain the above copyright
+   distributed under the License is distributed on an "AS IS" BASIS,
- *    notice, this list of conditions and the following disclaimer.
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *
+   See the License for the specific language governing permissions and
- * 2. Redistributions in binary form must reproduce the above copyright
+   limitations under the License.
- *    notice, this list of conditions and the following disclaimer in
+==================================================================== */
- *    the documentation and/or other materials provided with the
+
- *    distribution.
+
- *
- * 3. The end-user documentation included with the redistribution,
- *    if any, must include the following acknowledgment:
- *       "This product includes software developed by the
- *        Apache Software Foundation (http://www.apache.org/)."
- *    Alternately, this acknowledgment may appear in the software itself,
- *    if and wherever such third-party acknowledgments normally appear.
- *
- * 4. The names "Apache" and "Apache Software Foundation" and
- *    "Apache POI" must not be used to endorse or promote products
- *    derived from this software without prior written permission. For
- *    written permission, please contact apache@apache.org.
- *
- * 5. Products derived from this software may not be called "Apache",
- *    "Apache POI", nor may "Apache" appear in their name, without
- *    prior written permission of the Apache Software Foundation.
- *
- * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
- * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
- * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
- * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
- * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
- * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
- * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- * SUCH DAMAGE.
- * ====================================================================
- *
- * This software consists of voluntary contributions made by many
- * individuals on behalf of the Apache Software Foundation.  For more
- * information on the Apache Software Foundation, please see
- * <http://www.apache.org/>.
- */
 
 package org.apache.poi.hwpf.usermodel;
 
 import org.apache.poi.util.BitField;
 import org.apache.poi.util.LittleEndian;
 
+/**
+ * This class is used to represent a date and time in a Word document.
+ *
+ * @author Ryan Ackley
+ */
 public class DateAndTime
   implements Cloneable
 {

src/scratchpad/src/org/apache/poi/hwpf/usermodel/DropCapSpecifier.java

@@ -1,8 +1,32 @@
+/* ====================================================================
+   Copyright 2002-2004   Apache Software Foundation
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+==================================================================== */
+
 package org.apache.poi.hwpf.usermodel;
 
 import org.apache.poi.util.BitField;
 import org.apache.poi.util.LittleEndian;
 
+/**
+ * This data structure is used by a paragraph to determine how it should drop
+ * its first letter. I think its the visual effect that will show a giant first
+ * letter to a paragraph. I've seen this used in the first paragraph of a
+ * book
+ *
+ * @author Ryan Ackley
+ */
 public class DropCapSpecifier
 {
   private short _info;

src/scratchpad/src/org/apache/poi/hwpf/usermodel/HWPFList.java

@@ -1,3 +1,19 @@
+/* ====================================================================
+   Copyright 2002-2004   Apache Software Foundation
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+==================================================================== */
+
 package org.apache.poi.hwpf.usermodel;
 
 import org.apache.poi.hwpf.HWPFDocument;
@@ -10,15 +26,26 @@ import org.apache.poi.hwpf.model.StyleSheet;
 import org.apache.poi.hwpf.sprm.CharacterSprmCompressor;
 import org.apache.poi.hwpf.sprm.ParagraphSprmCompressor;
 
-
+/**
-public class List
+ * This class is used to create a list in a Word document. It is used in
+ * conjunction with {@link
+ * org.apache.poi.hwpf.HWPFDocument#registerList(HWPFList) registerList} in
+ * {@link org.apache.poi.hwpf.HWPFDocument HWPFDocument}.
+ *
+ * In Word, lists are not ranged entities. Lists only act as properties for
+ * list entries. Once you register a list, you can add list entries to a
+ * document that use the list.
+ *
+ * @author Ryan Ackley
+ */
+public class HWPFList
 {
   private ListData _listData;
   private ListFormatOverride _override;
   private boolean _registered;
   private StyleSheet _styleSheet;
 
-  public List(boolean numbered, StyleSheet styleSheet)
+  public HWPFList(boolean numbered, StyleSheet styleSheet)
   {
     _listData = new ListData((int)(Math.random() * (double)System.currentTimeMillis()), numbered);
     _override = new ListFormatOverride(_listData.getLsid());

src/scratchpad/src/org/apache/poi/hwpf/usermodel/LineSpacingDescriptor.java

@@ -1,61 +1,28 @@
 /* ====================================================================
- * The Apache Software License, Version 1.1
+   Copyright 2002-2004   Apache Software Foundation
- *
+
- * Copyright (c) 2003 The Apache Software Foundation.  All rights
+   Licensed under the Apache License, Version 2.0 (the "License");
- * reserved.
+   you may not use this file except in compliance with the License.
- *
+   You may obtain a copy of the License at
- * Redistribution and use in source and binary forms, with or without
+
- * modification, are permitted provided that the following conditions
+       http://www.apache.org/licenses/LICENSE-2.0
- * are met:
+
- *
+   Unless required by applicable law or agreed to in writing, software
- * 1. Redistributions of source code must retain the above copyright
+   distributed under the License is distributed on an "AS IS" BASIS,
- *    notice, this list of conditions and the following disclaimer.
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *
+   See the License for the specific language governing permissions and
- * 2. Redistributions in binary form must reproduce the above copyright
+   limitations under the License.
- *    notice, this list of conditions and the following disclaimer in
+==================================================================== */
- *    the documentation and/or other materials provided with the
- *    distribution.
- *
- * 3. The end-user documentation included with the redistribution,
- *    if any, must include the following acknowledgment:
- *       "This product includes software developed by the
- *        Apache Software Foundation (http://www.apache.org/)."
- *    Alternately, this acknowledgment may appear in the software itself,
- *    if and wherever such third-party acknowledgments normally appear.
- *
- * 4. The names "Apache" and "Apache Software Foundation" and
- *    "Apache POI" must not be used to endorse or promote products
- *    derived from this software without prior written permission. For
- *    written permission, please contact apache@apache.org.
- *
- * 5. Products derived from this software may not be called "Apache",
- *    "Apache POI", nor may "Apache" appear in their name, without
- *    prior written permission of the Apache Software Foundation.
- *
- * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
- * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
- * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
- * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
- * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
- * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
- * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- * SUCH DAMAGE.
- * ====================================================================
- *
- * This software consists of voluntary contributions made by many
- * individuals on behalf of the Apache Software Foundation.  For more
- * information on the Apache Software Foundation, please see
- * <http://www.apache.org/>.
- */
 
 package org.apache.poi.hwpf.usermodel;
 
 import org.apache.poi.util.LittleEndian;
 
+/**
+ * This class is used to determine line spacing for a paragraph.
+ *
+ * @author Ryan Ackley
+ */
 public class LineSpacingDescriptor
   implements Cloneable
 {

src/scratchpad/src/org/apache/poi/hwpf/usermodel/Range.java

@@ -1,56 +1,20 @@
 /* ====================================================================
- * The Apache Software License, Version 1.1
+   Copyright 2002-2004   Apache Software Foundation
- *
+
- * Copyright (c) 2003 The Apache Software Foundation.  All rights
+   Licensed under the Apache License, Version 2.0 (the "License");
- * reserved.
+   you may not use this file except in compliance with the License.
- *
+   You may obtain a copy of the License at
- * Redistribution and use in source and binary forms, with or without
+
- * modification, are permitted provided that the following conditions
+       http://www.apache.org/licenses/LICENSE-2.0
- * are met:
+
- *
+   Unless required by applicable law or agreed to in writing, software
- * 1. Redistributions of source code must retain the above copyright
+   distributed under the License is distributed on an "AS IS" BASIS,
- *    notice, this list of conditions and the following disclaimer.
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *
+   See the License for the specific language governing permissions and
- * 2. Redistributions in binary form must reproduce the above copyright
+   limitations under the License.
- *    notice, this list of conditions and the following disclaimer in
+==================================================================== */
- *    the documentation and/or other materials provided with the
+
- *    distribution.
+
- *
- * 3. The end-user documentation included with the redistribution,
- *    if any, must include the following acknowledgment:
- *       "This product includes software developed by the
- *        Apache Software Foundation (http://www.apache.org/)."
- *    Alternately, this acknowledgment may appear in the software itself,
- *    if and wherever such third-party acknowledgments normally appear.
- *
- * 4. The names "Apache" and "Apache Software Foundation" and
- *    "Apache POI" must not be used to endorse or promote products
- *    derived from this software without prior written permission. For
- *    written permission, please contact apache@apache.org.
- *
- * 5. Products derived from this software may not be called "Apache",
- *    "Apache POI", nor may "Apache" appear in their name, without
- *    prior written permission of the Apache Software Foundation.
- *
- * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
- * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
- * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
- * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
- * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
- * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
- * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- * SUCH DAMAGE.
- * ====================================================================
- *
- * This software consists of voluntary contributions made by many
- * individuals on behalf of the Apache Software Foundation.  For more
- * information on the Apache Software Foundation, please see
- * <http://www.apache.org/>.
- */
 
 package org.apache.poi.hwpf.usermodel;
 
@@ -202,7 +166,7 @@ public class Range
    *
    * @param start Starting character offset of the range.
    * @param end Ending character offset of the range.
-   * @param doc The parent this range belongs to.
+   * @param parent The parent this range belongs to.
    */
   protected Range(int start, int end, Range parent)
   {
@@ -516,6 +480,14 @@ public class Range
     return getParagraph(numParagraphs() - 1);
   }
 
+  /**
+   * Inserts a simple table into the beginning of this range. The number of
+   * columns is determined by the TableProperties passed into this function.
+   *
+   * @param props The table properties for the table.
+   * @param rows The number of rows.
+   * @return The empty Table that is now part of the document.
+   */
   public Table insertBefore(TableProperties props, int rows)
   {
     ParagraphProperties parProps = new ParagraphProperties();
@@ -538,8 +510,17 @@ public class Range
     return new Table(_start, _start + (rows * (columns + 1)), this, 0);
   }
 
+  /**
+   * Inserts a list into the beginning of this range.
+   *
+   * @param props The properties of the list entry. All list entries are
+   *        paragraphs.
+   * @param listID The id of the list that contains the properties.
+   * @param level The indentation level of the list.
+   * @param styleIndex The base style's index in the stylesheet.
+   * @return The empty ListEntry that is now part of the document.
+   */
   public ListEntry insertBefore(ParagraphProperties props, int listID, int level, int styleIndex)
-    //throws UnsupportedEncodingException
   {
     ListTables lt = _doc.getListTables();
     if (lt.getLevel(listID, level) == null)
@@ -554,6 +535,12 @@ public class Range
     return (ListEntry)insertBefore(props, styleIndex);
   }
 
+  /**
+   * Gets the character run at index. The index is relative to this range.
+   *
+   * @param index The index of the character run to get.
+   * @return The character run at the specified index in this range.
+   */
   public CharacterRun getCharacterRun(int index)
   {
     initCharacterRuns();
@@ -569,6 +556,12 @@ public class Range
     return chp;
   }
 
+  /**
+   * Gets the section at index. The index is relative to this range.
+   *
+   * @param index The index of the section to get.
+   * @return The section at the specified index in this range.
+   */
   public Section getSection(int index)
   {
     initSections();
@@ -577,6 +570,13 @@ public class Range
     return sep;
   }
 
+  /**
+   * Gets the paragraph at index. The index is relative to this range.
+   *
+   * @param index The index of the paragraph to get.
+   * @return The paragraph at the specified index in this range.
+   */
+
   public Paragraph getParagraph(int index)
   {
     initParagraphs();
@@ -596,11 +596,24 @@ public class Range
     return pap;
   }
 
+  /**
+   * This method is used to determine the type. Handy for switch statements
+   * compared to the instanceof operator.
+   *
+   * @return A TYPE constant.
+   */
   public int type()
   {
     return TYPE_UNDEFINED;
   }
 
+  /**
+   * Gets the table that starts with paragraph. In a Word file, a table consists
+   * of a group of paragraphs with certain flags set.
+   *
+   * @param paragraph The paragraph that is the first paragraph in the table.
+   * @return The table that starts with paragraph
+   */
   public Table getTable(Paragraph paragraph)
   {
     if (!paragraph.isInTable())
@@ -640,6 +653,9 @@ public class Range
     return new Table(r._parStart, tableEnd, r._doc.getRange(), 1);
   }
 
+  /**
+   * loads all of the list indexes.
+   */
   private void initAll()
   {
     initText();
@@ -648,7 +664,9 @@ public class Range
     initSections();
   }
 
-
+  /**
+   * inits the paragraph list indexes.
+   */
   private void initParagraphs()
   {
     if (!_parRangeFound)
@@ -660,6 +678,9 @@ public class Range
     }
   }
 
+  /**
+   * inits the character run list indexes.
+   */
   private void initCharacterRuns()
   {
     if (!_charRangeFound)
@@ -671,6 +692,9 @@ public class Range
     }
   }
 
+  /**
+   * inits the text piece list indexes.
+   */
   private void initText()
   {
     if (!_textRangeFound)
@@ -682,6 +706,9 @@ public class Range
     }
   }
 
+  /**
+   * inits the section list indexes.
+   */
   private void initSections()
   {
     if (!_sectionRangeFound)
@@ -693,6 +720,16 @@ public class Range
     }
   }
 
+  /**
+   * Used to find the list indexes of a particular property.
+   *
+   * @param rpl A list of property nodes.
+   * @param min A hint on where to start looking.
+   * @param start The starting character offset.
+   * @param end The ending character offset.
+   * @return An int array of length 2. The first int is the start index and the
+   *         second int is the end index.
+   */
   private int[] findRange(List rpl, int min, int start, int end)
   {
     int x = min;
@@ -713,6 +750,9 @@ public class Range
     return new int[]{x, y + 1};
   }
 
+  /**
+   * resets the list indexes.
+   */
   private void reset()
   {
     _textRangeFound = false;
@@ -721,6 +761,10 @@ public class Range
     _sectionRangeFound = false;
   }
 
+  /**
+   * adjust this range after an insert happens.
+   * @param length the length to adjust for
+   */
   private void adjustForInsert(int length)
   {
     _end += length;