Added comments

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

3 files changed, 162 insertions, 16 deletions

diff --git a/src/scratchpad/src/org/apache/poi/hdf/model/hdftypes/PropertyNode.java b/src/scratchpad/src/org/apache/poi/hdf/model/hdftypes/PropertyNode.java
index 773e3ca0e7..af9c14f779 100644
--- a/src/scratchpad/src/org/apache/poi/hdf/model/hdftypes/PropertyNode.java
+++ b/src/scratchpad/src/org/apache/poi/hdf/model/hdftypes/PropertyNode.java
@@ -54,39 +54,61 @@
 package org.apache.poi.hdf.model.hdftypes;
 
 
-
+/**
+ * Represents a lightweight node in the Trees used to store formatting
+ * properties.
+ *
+ * @author Ryan Ackley
+ */
 public class PropertyNode implements Comparable
 {
   private byte[] _grpprl;
   private int _fcStart;
   private int _fcEnd;
 
+  /**
+   * @param fcStart The start of the text for this property.
+   * @param fcEnd The end of the text for this property.
+   * @param grpprl The property description in compressed form.
+   */
   public PropertyNode(int fcStart, int fcEnd, byte[] grpprl)
   {
       _fcStart = fcStart;
       _fcEnd = fcEnd;
       _grpprl = grpprl;
   }
+  /**
+   * @return The offset of this property's text.
+   */
   public int getStart()
   {
       return _fcStart;
   }
+  /**
+   * @retrun The offset of the end of this property's text.
+   */
   public int getEnd()
   {
     return _fcEnd;
   }
+  /**
+   * @return This property's property in copmpressed form.
+   */
   protected byte[] getGrpprl()
   {
     return _grpprl;
   }
+  /**
+   * Used for sorting in collections.
+   */
   public int compareTo(Object o)
   {
-      int fcStart = ((PropertyNode)o).getStart();
-      if(_fcStart == fcStart)
+      int fcEnd = ((PropertyNode)o).getEnd();
+      if(_fcEnd == fcEnd)
       {
         return 0;
       }
-      else if(_fcStart < fcStart)
+      else if(_fcEnd < fcEnd)
       {
         return -1;
       }
diff --git a/src/scratchpad/src/org/apache/poi/hdf/model/hdftypes/StyleSheet.java b/src/scratchpad/src/org/apache/poi/hdf/model/hdftypes/StyleSheet.java
index a7cb893ee2..2f99c9478e 100644
--- a/src/scratchpad/src/org/apache/poi/hdf/model/hdftypes/StyleSheet.java
+++ b/src/scratchpad/src/org/apache/poi/hdf/model/hdftypes/StyleSheet.java
@@ -60,8 +60,12 @@ package org.apache.poi.hdf.model.hdftypes;
 import java.util.*;
 import org.apache.poi.util.LittleEndian;
 import org.apache.poi.hdf.model.hdftypes.definitions.TCAbstractType;
+
 /**
- * Comment me
+ * Represents a document's stylesheet. A word documents formatting is stored as
+ * compressed styles that are based on styles contained in the stylesheet. This
+ * class also contains static utility functions to uncompress different
+ * formatting properties.
  *
  * @author Ryan Ackley
  */
@@ -78,6 +82,13 @@ public class StyleSheet implements HDFType
   StyleDescription _nilStyle = new StyleDescription();
   StyleDescription[] _styleDescriptions;
 
+  /**
+   * StyleSheet constructor. Loads a document's stylesheet information,
+   *
+   * @param styleSheet A byte array containing a document's raw stylesheet
+   *        info. Found by using FileInformationBlock.getFcStshf() and
+   *        FileInformationBLock.getLcbStshf()
+   */
   public StyleSheet(byte[] styleSheet)
   {
       int stshiLength = LittleEndian.getShort(styleSheet, 0);
@@ -120,6 +131,16 @@ public class StyleSheet implements HDFType
           }
       }
   }
+  /**
+   * Creates a PartagraphProperties object from a papx stored in the
+   * StyleDescription at the index istd in the StyleDescription array. The PAP
+   * is placed in the StyleDescription at istd after its been created. Not
+   * every StyleDescription will contain a papx. In these cases this function
+   * does nothing
+   *
+   * @param istd The index of the StyleDescription to create the
+   *        ParagraphProperties  from (and also place the finished PAP in)
+   */
   private void createPap(int istd)
   {
       StyleDescription sd = _styleDescriptions[istd];
@@ -145,6 +166,16 @@ public class StyleSheet implements HDFType
           sd.setPAP(pap);
       }
   }
+  /**
+   * Creates a CharacterProperties object from a chpx stored in the
+   * StyleDescription at the index istd in the StyleDescription array. The
+   * CharacterProperties object is placed in the StyleDescription at istd after
+   * its been created. Not every StyleDescription will contain a chpx. In these
+   * cases this function does nothing.
+   *
+   * @param istd The index of the StyleDescription to create the
+   *        CharacterProperties object from.
+   */
   private void createChp(int istd)
   {
       StyleDescription sd = _styleDescriptions[istd];
@@ -170,10 +201,31 @@ public class StyleSheet implements HDFType
           sd.setCHP(chp);
       }
   }
+
+  /**
+   * Gets the StyleDescription at index x.
+   *
+   * @param x the index of the desired StyleDescription.
+   */
   public StyleDescription getStyleDescription(int x)
   {
       return _styleDescriptions[x];
   }
+
+  /**
+   * Used in decompression of a chpx. This performs an operation defined by
+   * a single sprm.
+   *
+   * @param oldCHP The base CharacterProperties.
+   * @param newCHP The current CharacterProperties.
+   * @param operand The operand defined by the sprm (See Word file format spec)
+   * @param param The parameter defined by the sprm (See Word file format spec)
+   * @param varParam The variable length parameter defined by the sprm. (See
+   *        Word file format spec)
+   * @param grpprl The entire chpx that this operation is a part of.
+   * @param offset The offset in the grpprl of the next sprm
+   * @param styleSheet The StyleSheet for this document.
+   */
   static void doCHPOperation(CharacterProperties oldCHP, CharacterProperties newCHP,
                              int operand, int param,
                              byte[] varParam, byte[] grpprl, int offset,
@@ -615,12 +667,33 @@ public class StyleSheet implements HDFType
       }
   }
 
+  /**
+   * Used to uncompress a property stored in a grpprl. These include
+   * CharacterProperties, ParagraphProperties, TableProperties, and
+   * SectionProperties.
+   *
+   * @param grpprl The compressed form of the property.
+   * @param parent The base property of the property.
+   * @param styleSheet The document's stylesheet.
+   *
+   * @return An object that should be casted to the appropriate property.
+   */
   static Object uncompressProperty(byte[] grpprl, Object parent, StyleSheet styleSheet)
   {
     return uncompressProperty(grpprl, parent, styleSheet, true);
   }
 
-
+  /**
+   * Used to uncompress a property stored in a grpprl. These include
+   * CharacterProperties, ParagraphProperties, TableProperties, and
+   * SectionProperties.
+   *
+   * @param grpprl The compressed form of the property.
+   * @param parent The base property of the property.
+   * @param styleSheet The document's stylesheet.
+   *
+   * @return An object that should be casted to the appropriate property.
+   */
   static Object uncompressProperty(byte[] grpprl, Object parent, StyleSheet styleSheet, boolean doIstd)
   {
       Object newProperty = null;
@@ -765,6 +838,18 @@ public class StyleSheet implements HDFType
       return newProperty;
 
   }
+  /**
+   * Performs an operation on a ParagraphProperties object. Used to uncompress
+   * from a papx.
+   *
+   * @param newPAP The ParagraphProperties object to perform the operation on.
+   * @param operand The operand that defines the operation.
+   * @param param The operation's parameter.
+   * @param varParam The operation's variable length parameter.
+   * @param grpprl The original papx.
+   * @param offset The current offset in the papx.
+   * @param spra A part of the sprm that defined this operation.
+   */
   static void doPAPOperation(ParagraphProperties newPAP, int operand, int param,
                              byte[] varParam, byte[] grpprl, int offset,
                              int spra)
@@ -1027,6 +1112,15 @@ public class StyleSheet implements HDFType
                break;
       }
   }
+  /**
+   * Used to uncompress a table property. Performs an operation defined
+   * by a sprm stored in a tapx.
+   *
+   * @param newTAP The TableProperties object to perform the operation on.
+   * @param operand The operand that defines this operation.
+   * @param param The parameter for this operation.
+   * @param varParam Variable length parameter for this operation.
+   */
   static void doTAPOperation(TableProperties newTAP, int operand, int param, byte[] varParam)
   {
       switch(operand)
@@ -1202,6 +1296,15 @@ public class StyleSheet implements HDFType
                break;
       }
   }
+  /**
+   * Used in decompression of a sepx. This performs an operation defined by
+   * a single sprm.
+   *
+   * @param newSEP The SectionProperty to perfrom the operation on.
+   * @param operand The operation to perform.
+   * @param param The operation's parameter.
+   * @param varParam The operation variable length parameter.
+   */
   static void doSEPOperation(SectionProperties newSEP, int operand, int param, byte[] varParam)
   {
       switch(operand)
@@ -1369,6 +1472,16 @@ public class StyleSheet implements HDFType
       }
 
   }
+  /**
+   * Converts an byte value into a boolean. The byte parameter can be 1,0, 128,
+   * or 129. if it is 128, this function returns the same value as oldVal. If
+   * it is 129, this function returns !oldVal. This is used for certain sprms
+   *
+   * @param x The byte value to convert.
+   * @param oldVal The old boolean value.
+   *
+   * @return A boolean whose value depends on x and oldVal.
+   */
   private static boolean getCHPFlag(byte x, boolean oldVal)
   {
       switch(x)
@@ -1385,6 +1498,15 @@ public class StyleSheet implements HDFType
                return false;
       }
   }
+
+  /**
+   * Converts an int into a boolean. If the int is non-zero, it returns true.
+   * Otherwise it returns false.
+   *
+   * @param x The int to convert.
+   *
+   * @return A boolean whose value depends on x.
+   */
   public static boolean getFlag(int x)
   {
       if(x != 0)
diff --git a/src/scratchpad/src/org/apache/poi/hdf/model/hdftypes/TextPiece.java b/src/scratchpad/src/org/apache/poi/hdf/model/hdftypes/TextPiece.java
index ae3d636080..3b4d8ec290 100644
--- a/src/scratchpad/src/org/apache/poi/hdf/model/hdftypes/TextPiece.java
+++ b/src/scratchpad/src/org/apache/poi/hdf/model/hdftypes/TextPiece.java
@@ -57,7 +57,7 @@ package org.apache.poi.hdf.model.hdftypes;
 
 
 /**
- * Comment me
+ * Lightweight representation of a text piece.
  *
  * @author Ryan Ackley
  */
@@ -67,22 +67,24 @@ public class TextPiece extends PropertyNode implements Comparable
   private boolean _usesUnicode;
   private int _length;
 
+  /**
+   * @param start Offset in main document stream.
+   * @param length The total length of the text in bytes. Note: 1 character
+   *        does not necessarily refer to 1 byte.
+   * @param unicode true if this text is unicode.
+   */
   public TextPiece(int start, int length, boolean unicode)
   {
-    super(start, start + length, null);
+      super(start, start + length, null);
       _usesUnicode = unicode;
       _length = length;
-      //_fcStart = start;
-      //_fcEnd = start + length;
 
   }
+  /**
+   * @return If this text piece uses unicode
+   */
    public boolean usesUnicode()
-  {
+   {
       return _usesUnicode;
-  }
-
-   public int compareTo(Object obj) {
-       return 0;
    }
-
 }