add / update documentation

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

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

@@ -21,45 +21,46 @@ import java.util.ArrayList;
 
 import org.apache.poi.util.LittleEndian;
 
-
-
 /**
- * common data structure in a Word file. Contains an array of 4 byte ints in
+ * Plex of CPs stored in File (PLCF)
- * the front that relate to an array of abitrary data structures in the back.
  * 
+ * common data structure in a Word file. Contains an array of 4 byte ints in the
+ * front that relate to an array of arbitrary data structures in the back.
+ * 
+ * See page 184 of official documentation for details
  * 
  * @author Ryan Ackley
  */
 public final class PlexOfCps
 {
-  private int _count;
+    private int _iMac;
     private int _offset;
-  private int _sizeOfStruct;
+    private int _cbStruct;
     private ArrayList<GenericPropertyNode> _props;
 
-
     public PlexOfCps( int sizeOfStruct )
     {
         _props = new ArrayList<GenericPropertyNode>();
-    _sizeOfStruct = sizeOfStruct;
+        _cbStruct = sizeOfStruct;
     }
 
     /**
      * Constructor
      * 
-   * @param size The size in bytes of this PlexOfCps
+     * @param cb
-   * @param sizeOfStruct The size of the data structure type stored in
+     *            The size of PLCF in bytes
-   *        this PlexOfCps.
+     * @param cbStruct
+     *            The size of the data structure type stored in this PlexOfCps.
      */
-  public PlexOfCps(byte[] buf, int start, int size, int sizeOfStruct)
+    public PlexOfCps( byte[] buf, int start, int cb, int cbStruct )
     {
         // Figure out the number we hold
-    _count = (size - 4)/(4 + sizeOfStruct);
+        _iMac = ( cb - 4 ) / ( 4 + cbStruct );
 
-    _sizeOfStruct = sizeOfStruct;
+        _cbStruct = cbStruct;
-    _props = new ArrayList<GenericPropertyNode>(_count);
+        _props = new ArrayList<GenericPropertyNode>( _iMac );
 
-    for (int x = 0; x < _count; x++)
+        for ( int x = 0; x < _iMac; x++ )
         {
             _props.add( getProperty( x, buf, start ) );
         }
@@ -79,7 +80,7 @@ public final class PlexOfCps
     {
         int size = _props.size();
         int cpBufSize = ( ( size + 1 ) * LittleEndian.INT_SIZE );
-    int structBufSize =  + (_sizeOfStruct * size);
+        int structBufSize = +( _cbStruct * size );
         int bufSize = cpBufSize + structBufSize;
 
         byte[] buf = new byte[bufSize];
@@ -90,11 +91,12 @@ public final class PlexOfCps
             node = _props.get( x );
 
             // put the starting offset of the property into the plcf.
-      LittleEndian.putInt(buf, (LittleEndian.INT_SIZE * x), node.getStart());
+            LittleEndian.putInt( buf, ( LittleEndian.INT_SIZE * x ),
+                    node.getStart() );
 
             // put the struct into the plcf
-      System.arraycopy(node.getBytes(), 0, buf, cpBufSize + (x * _sizeOfStruct),
+            System.arraycopy( node.getBytes(), 0, buf, cpBufSize
-                       _sizeOfStruct);
+                    + ( x * _cbStruct ), _cbStruct );
         }
         // put the ending offset of the last property into the plcf.
         LittleEndian.putInt( buf, LittleEndian.INT_SIZE * size, node.getEnd() );
@@ -108,8 +110,9 @@ public final class PlexOfCps
         int start = LittleEndian.getInt( buf, offset + getIntOffset( index ) );
         int end = LittleEndian.getInt( buf, offset + getIntOffset( index + 1 ) );
 
-    byte[] struct = new byte[_sizeOfStruct];
+        byte[] struct = new byte[_cbStruct];
-    System.arraycopy(buf, offset + getStructOffset(index), struct, 0, _sizeOfStruct);
+        System.arraycopy( buf, offset + getStructOffset( index ), struct, 0,
+                _cbStruct );
 
         return new GenericPropertyNode( start, end, struct );
     }
@@ -120,26 +123,27 @@ public final class PlexOfCps
     }
 
     /**
-   * returns the number of data structures in this PlexOfCps.
+     * returns the number of data structures in this PlexofCps.
      * 
-   * @return The number of data structures in this PlexOfCps
+     * @return The number of data structures in this PlexofCps
      */
     public int length()
     {
-    return _count;
+        return _iMac;
     }
 
     /**
-   * Returns the offset, in bytes, from the beginning if this PlexOfCps to
+     * Returns the offset, in bytes, from the beginning if this PlexOfCps to the
-   * the data structure at index.
+     * data structure at index.
      * 
-   * @param index The index of the data structure.
+     * @param index
+     *            The index of the data structure.
      * 
-   * @return The offset, in bytes, from the beginning if this PlexOfCps to
+     * @return The offset, in bytes, from the beginning if this PlexOfCps to the
-   *         the data structure at index.
+     *         data structure at index.
      */
     private int getStructOffset( int index )
     {
-    return (4 * (_count + 1)) + (_sizeOfStruct * index);
+        return ( 4 * ( _iMac + 1 ) ) + ( _cbStruct * index );
     }
 }

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

@@ -51,10 +51,30 @@ public final class HeaderStories {
 		}
 
         // Handle the PlcfHdd
-		plcfHdd = new PlexOfCps(
+        /*
-				doc.getTableStream(), fib.getPlcfHddOffset(),
+         * Page 88:
-				fib.getPlcfHddSize(), 0
+         * 
-		);
+         * "The plcfhdd, a table whose location and length within the file is
+         * stored in fib.fcPlcfhdd and fib.cbPlcfhdd, describes where the text
+         * of each header/footer begins. If there are n headers/footers stored
+         * in the Word file, the plcfhdd consists of n+2 CP entries. The
+         * beginning CP of the ith header/footer is the ith CP in the plcfhdd.
+         * The limit CP (the CP of character 1 position past the end of a
+         * header/footer) of the ith header/footer is the i+1st CP in the
+         * plcfhdd. Note: at the limit CP - 1, Word always places a chEop as a
+         * placeholder which is never displayed as part of the header/footer.
+         * This allows Word to change an existing header/footer to be empty.
+         * 
+         * If there are n header/footers, the n+2nd CP entry value is always 1
+         * greater than the n+1st CP entry value. A paragraph end (ASCII 13) is
+         * always stored at the file position marked by the n+1st CP value.
+         * 
+         * The transformation in a full saved file from a header/footer CP to an
+         * offset from the beginning of a file (fc) is
+         * fc=fib.fcMin+ccpText+ccpFtn+cp."
+         */
+        plcfHdd = new PlexOfCps( doc.getTableStream(), fib.getPlcfHddOffset(),
+                fib.getPlcfHddSize(), 0 );
     }
 
 	public String getFootnoteSeparator() {