fixed some style errors

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

9 files changed, 404 insertions, 182 deletions

diff --git a/src/org/apache/fop/pdf/ASCII85Filter.java b/src/org/apache/fop/pdf/ASCII85Filter.java
index d08e835bb..e3a5f61c4 100644
--- a/src/org/apache/fop/pdf/ASCII85Filter.java
+++ b/src/org/apache/fop/pdf/ASCII85Filter.java
@@ -1,34 +1,57 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
 
 package org.apache.fop.pdf;
 
-import java.io.ByteArrayOutputStream;
+import java.io.OutputStream;
+import java.io.InputStream;
 import java.io.IOException;
-import java.io.*;
 
+/**
+ * PDF Filter for ASCII85.
+ * This applies a filter to a pdf stream that converts
+ * the data to ASCII.
+ */
 public class ASCII85Filter extends PDFFilter {
     private static final char ASCII85_ZERO = 'z';
     private static final char ASCII85_START = '!';
     private static final String ASCII85_EOD = "~>";
 
-    private static final long base85_4 = 85;
+    private static final long BASE85_4 = 85;
     //private static final long base85_3 = base85_4 * base85_4;
     //private static final long base85_2 = base85_3 * base85_4;
     //private static final long base85_1 = base85_2 * base85_4;
 
+    /**
+     * Get the PDF name of this filter.
+     *
+     * @return the name of the filter to be inserted into the PDF
+     */
     public String getName() {
         return "/ASCII85Decode";
     }
 
+    /**
+     * Get the decode parameters.
+     *
+     * @return always null
+     */
     public String getDecodeParms() {
         return null;
     }
 
+    /**
+     * Encode a pdf stream using this filter.
+     *
+     * @param in the input stream to read the data from
+     * @param out the output stream to write the data
+     * @param length the length of the data to filter
+     * @throws IOException if there is an error reading or writing to the streams
+     */
     public void encode(InputStream in, OutputStream out, int length) throws IOException {
 
         int i;
@@ -94,7 +117,11 @@ public class ASCII85Filter extends PDFFilter {
          * int out = (result.length-ASCII85_EOD.getBytes().length) % 5;
          * if ((in+1 != out) && !(in == 0 && out == 0)) {
          * System.out.println("ASCII85 assertion failed:");
-         * System.out.println("        inlength = "+data.length+" inlength % 4 = "+(data.length % 4)+" outlength = "+(result.length-ASCII85_EOD.getBytes().length)+" outlength % 5 = "+((result.length-ASCII85_EOD.getBytes().length) % 5));
+         * System.out.println("inlength = "+data.length+" inlength % 4 = "
+         *         + (data.length % 4)+" outlength = "
+         *         + (result.length-ASCII85_EOD.getBytes().length)
+         *         + " outlength % 5 = "
+         *         + ((result.length-ASCII85_EOD.getBytes().length) % 5));
          * }
          */
 
@@ -128,11 +155,11 @@ public class ASCII85Filter extends PDFFilter {
             byte c3 =
                 (byte)(((word - (c1 * base85_1) - (c2 * base85_2)) / base85_3)
                        & 0xFF);
-            byte c4 =
-                (byte)(((word - (c1 * base85_1) - (c2 * base85_2) - (c3 * base85_3)) / base85_4)
+            byte c4 = (byte)(((word - (c1 * base85_1)
+                      - (c2 * base85_2) - (c3 * base85_3)) / base85_4)
                        & 0xFF);
-            byte c5 =
-                (byte)(((word - (c1 * base85_1) - (c2 * base85_2) - (c3 * base85_3) - (c4 * base85_4)))
+            byte c5 = (byte)(((word - (c1 * base85_1)
+                       - (c2 * base85_2) - (c3 * base85_3) - (c4 * base85_4)))
                        & 0xFF);
 
             byte[] ret = {
@@ -142,15 +169,15 @@ public class ASCII85Filter extends PDFFilter {
             };
             */
 
-            byte c5 = (byte)((word % base85_4) + ASCII85_START);
-            word = word / base85_4;
-            byte c4 = (byte)((word % base85_4) + ASCII85_START);
-            word = word / base85_4;
-            byte c3 = (byte)((word % base85_4) + ASCII85_START);
-            word = word / base85_4;
-            byte c2 = (byte)((word % base85_4) + ASCII85_START);
-            word = word / base85_4;
-            byte c1 = (byte)((word % base85_4) + ASCII85_START);
+            byte c5 = (byte)((word % BASE85_4) + ASCII85_START);
+            word = word / BASE85_4;
+            byte c4 = (byte)((word % BASE85_4) + ASCII85_START);
+            word = word / BASE85_4;
+            byte c3 = (byte)((word % BASE85_4) + ASCII85_START);
+            word = word / BASE85_4;
+            byte c2 = (byte)((word % BASE85_4) + ASCII85_START);
+            word = word / BASE85_4;
+            byte c1 = (byte)((word % BASE85_4) + ASCII85_START);
 
             byte[] ret = {
               c1 , c2, c3, c4, c5
diff --git a/src/org/apache/fop/pdf/ASCIIHexFilter.java b/src/org/apache/fop/pdf/ASCIIHexFilter.java
index 4e81bfc6e..200d1e13e 100644
--- a/src/org/apache/fop/pdf/ASCIIHexFilter.java
+++ b/src/org/apache/fop/pdf/ASCIIHexFilter.java
@@ -1,33 +1,58 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
 package org.apache.fop.pdf;
 
-import java.io.ByteArrayOutputStream;
+import java.io.OutputStream;
+import java.io.InputStream;
+import java.io.Writer;
+import java.io.OutputStreamWriter;
 import java.io.IOException;
-import java.io.*;
 
+/**
+ * ASCII Hex filter for PDF streams.
+ * This filter converts a pdf stream to ASCII hex data.
+ */
 public class ASCIIHexFilter extends PDFFilter {
     private static final String ASCIIHEX_EOD = ">";
 
-
+    /**
+     * Get the name of this filter.
+     *
+     * @return the name of this filter for pdf
+     */
     public String getName() {
         return "/ASCIIHexDecode";
     }
 
+    /**
+     * Get the decode params.
+     *
+     * @return always null
+     */
     public String getDecodeParms() {
         return null;
     }
 
+    /**
+     * Encode the pdf stream using this filter.
+     *
+     * @param in the input stream to read the data from
+     * @param out the output stream to write data to
+     * @param length the length of data to read from the stream
+     * @throws IOException if an error occurs reading or writing to
+     *                     the streams
+     */
     public void encode(InputStream in, OutputStream out, int length) throws IOException {
         Writer writer = new OutputStreamWriter(out);
         for (int i = 0; i < length; i++) {
             int val = (int)(in.read() & 0xFF);
-            if (val < 16)
+            if (val < 16) {
                 writer.write("0");
+            }
             writer.write(Integer.toHexString(val));
         }
         writer.write(ASCIIHEX_EOD);
diff --git a/src/org/apache/fop/pdf/FlateFilter.java b/src/org/apache/fop/pdf/FlateFilter.java
index d3d5b3d35..c16f2965f 100644
--- a/src/org/apache/fop/pdf/FlateFilter.java
+++ b/src/org/apache/fop/pdf/FlateFilter.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -9,10 +9,10 @@ package org.apache.fop.pdf;
 
 import org.apache.fop.util.StreamUtilities;
 
-import java.io.ByteArrayOutputStream;
+import java.io.OutputStream;
+import java.io.InputStream;
 import java.io.IOException;
 import java.util.zip.DeflaterOutputStream;
-import java.io.*;
 
 /**
  * A filter to deflate a stream. Note that the attributes for
@@ -22,39 +22,79 @@ import java.io.*;
  * file.
  */
 public class FlateFilter extends PDFFilter {
-
+    /**
+     * The supported mode when this filter is used for data compression
+     */
     public static final int PREDICTION_NONE = 1;
+
+    /**
+     * Mode for externally encoded data.
+     */
     public static final int PREDICTION_TIFF2 = 2;
+
+    /**
+     * Mode for externally encoded data.
+     */
     public static final int PREDICTION_PNG_NONE = 10;
+
+    /**
+     * Mode for externally encoded data.
+     */
     public static final int PREDICTION_PNG_SUB = 11;
+
+    /**
+     * Mode for externally encoded data.
+     */
     public static final int PREDICTION_PNG_UP = 12;
+
+    /**
+     * Mode for externally encoded data.
+     */
     public static final int PREDICTION_PNG_AVG = 13;
+
+    /**
+     * Mode for externally encoded data.
+     */
     public static final int PREDICTION_PNG_PAETH = 14;
+
+    /**
+     * Mode for externally encoded data.
+     */
     public static final int PREDICTION_PNG_OPT = 15;
 
 
-    private int _predictor = PREDICTION_NONE;
-    private int _colors;
-    private int _bitsPerComponent;
-    private int _columns;
+    private int predictor = PREDICTION_NONE;
+    private int colors;
+    private int bitsPerComponent;
+    private int columns;
 
+    /**
+     * Get the name of this filter.
+     *
+     * @return the pdf name of the flate decode filter
+     */
     public String getName() {
         return "/FlateDecode";
     }
 
+    /**
+     * Get the decode params for this filter.
+     *
+     * @return a string containing the decode params for this filter
+     */
     public String getDecodeParms() {
-        if (_predictor > PREDICTION_NONE) {
+        if (predictor > PREDICTION_NONE) {
             StringBuffer sb = new StringBuffer();
             sb.append("<< /Predictor ");
-            sb.append(_predictor);
-            if (_colors > 0) {
-                sb.append(" /Colors " + _colors);
+            sb.append(predictor);
+            if (colors > 0) {
+                sb.append(" /Colors " + colors);
             }
-            if (_bitsPerComponent > 0) {
-                sb.append(" /BitsPerComponent " + _bitsPerComponent);
+            if (bitsPerComponent > 0) {
+                sb.append(" /BitsPerComponent " + bitsPerComponent);
             }
-            if (_columns > 0) {
-                sb.append(" /Columns " + _columns);
+            if (columns > 0) {
+                sb.append(" /Columns " + columns);
             }
             sb.append(" >> ");
             return sb.toString();
@@ -68,9 +108,14 @@ public class FlateFilter extends PDFFilter {
      * this method is that it resets the prediction to the default
      * because these attributes are not supported. So the DecodeParms
      * should be retrieved after calling this method.
+     *
+     * @param in the input stream to read the data from
+     * @param out the output stream to write the data to
+     * @param length the length of data to read
+     * @throws IOException if there is an error reading or writing to the streams
      */
     public void encode(InputStream in, OutputStream out, int length) throws IOException {
-        _predictor = PREDICTION_NONE;
+        predictor = PREDICTION_NONE;
         try {
             DeflaterOutputStream compressedStream =
                 new DeflaterOutputStream(out);
@@ -84,52 +129,99 @@ public class FlateFilter extends PDFFilter {
 
     }
 
+    /**
+     * Set the predictor for this filter.
+     *
+     * @param predictor the predictor to use
+     * @throws PDFFilterException if there is an error with the predictor
+     */
     public void setPredictor(int predictor) throws PDFFilterException {
-        _predictor = predictor;
+        predictor = predictor;
 
     }
 
+    /**
+     * Get the predictor for this filter.
+     *
+     * @return the predictor used for this filter
+     */
     public int getPredictor() {
-        return _predictor;
+        return predictor;
     }
 
-
+    /**
+     * Set the colors for this filter.
+     *
+     * @param colors the colors to use
+     * @throws PDFFilterException if predictor is not PREDICTION_NONE
+     */
     public void setColors(int colors) throws PDFFilterException {
-        if (_predictor != PREDICTION_NONE) {
-            _colors = colors;
+        if (predictor != PREDICTION_NONE) {
+            colors = colors;
         } else {
-            throw new PDFFilterException("Prediction must not be PREDICTION_NONE in order to set Colors");
+            throw new PDFFilterException(
+                          "Prediction must not be PREDICTION_NONE in"
+                          + " order to set Colors");
         }
     }
 
+    /**
+     * Get the colors for this filter.
+     *
+     * @return the colors for this filter
+     */
     public int getColors() {
-        return _colors;
+        return colors;
     }
 
-
+    /**
+     * Set the number of bits per component.
+     *
+     * @param bits the number of bits per component
+     * @throws PDFFilterException if predictor is not PREDICTION_NONE
+     */
     public void setBitsPerComponent(int bits) throws PDFFilterException {
-        if (_predictor != PREDICTION_NONE) {
-            _bitsPerComponent = bits;
+        if (predictor != PREDICTION_NONE) {
+            bitsPerComponent = bits;
         } else {
-            throw new PDFFilterException("Prediction must not be PREDICTION_NONE in order to set bitsPerComponent");
+            throw new PDFFilterException(
+                         "Prediction must not be PREDICTION_NONE in order"
+                         + " to set bitsPerComponent");
         }
     }
 
+    /**
+     * Get the number of bits per component.
+     *
+     * @return the number of bits per component
+     */
     public int getBitsPerComponent() {
-        return _bitsPerComponent;
+        return bitsPerComponent;
     }
 
-
+    /**
+     * Set the number of columns for this filter.
+     *
+     * @param columns the number of columns to use for the filter
+     * @throws PDFFilterException if predictor is not PREDICTION_NONE
+     */
     public void setColumns(int columns) throws PDFFilterException {
-        if (_predictor != PREDICTION_NONE) {
-            _columns = columns;
+        if (predictor != PREDICTION_NONE) {
+            columns = columns;
         } else {
-            throw new PDFFilterException("Prediction must not be PREDICTION_NONE in order to set Columns");
+            throw new PDFFilterException(
+                      "Prediction must not be PREDICTION_NONE in"
+                      + " order to set Columns");
         }
     }
 
+    /**
+     * Get the number of columns for this filter.
+     *
+     * @return the number of columns
+     */
     public int getColumns() {
-        return _columns;
+        return columns;
     }
 
 
diff --git a/src/org/apache/fop/pdf/PDFAction.java b/src/org/apache/fop/pdf/PDFAction.java
index 2749a221f..de1626caf 100644
--- a/src/org/apache/fop/pdf/PDFAction.java
+++ b/src/org/apache/fop/pdf/PDFAction.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -30,7 +30,7 @@ public abstract class PDFAction extends PDFObject {
      * this constructor is used when there is no additional object being created
      *
      */
-    public PDFAction() {}
+    public PDFAction() { }
 
     /**
      * represent the action to call
@@ -40,7 +40,7 @@ public abstract class PDFAction extends PDFObject {
      *
      * @return the action to place next to /A within a Link
      */
-    abstract public String getAction();
+    public abstract String getAction();
 
 
     /**
@@ -50,6 +50,6 @@ public abstract class PDFAction extends PDFObject {
      *
      * @return the PDF string
      */
-    abstract public byte[] toPDF();
+    public abstract byte[] toPDF();
 
 }
diff --git a/src/org/apache/fop/pdf/PDFAnnotList.java b/src/org/apache/fop/pdf/PDFAnnotList.java
index 5aa805670..41246194b 100644
--- a/src/org/apache/fop/pdf/PDFAnnotList.java
+++ b/src/org/apache/fop/pdf/PDFAnnotList.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
diff --git a/src/org/apache/fop/pdf/PDFArray.java b/src/org/apache/fop/pdf/PDFArray.java
index 243c19f09..fb4bb1728 100644
--- a/src/org/apache/fop/pdf/PDFArray.java
+++ b/src/org/apache/fop/pdf/PDFArray.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -11,7 +11,9 @@ package org.apache.fop.pdf;
  * class representing an array object
  */
 public class PDFArray extends PDFObject {
-
+    /**
+     * Array of calues for this pdf object.
+     */
     protected int[] values;
 
     /**
diff --git a/src/org/apache/fop/pdf/PDFCIDFont.java b/src/org/apache/fop/pdf/PDFCIDFont.java
index 5323996bb..3e912f5e6 100644
--- a/src/org/apache/fop/pdf/PDFCIDFont.java
+++ b/src/org/apache/fop/pdf/PDFCIDFont.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
diff --git a/src/org/apache/fop/pdf/PDFDocument.java b/src/org/apache/fop/pdf/PDFDocument.java
index ffdd3de32..e483b6791 100644
--- a/src/org/apache/fop/pdf/PDFDocument.java
+++ b/src/org/apache/fop/pdf/PDFDocument.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -43,16 +43,13 @@ import java.awt.geom.Rectangle2D;
  * of the document; ability to write to a stream and flush
  * the object list; enhanced trailer output; cleanups.
  *
- * Modified by lmckenzi@ca.ibm.com
- * Sometimes IDs are created, but not validated. This tracks
- * the difference.
  */
 public class PDFDocument {
-    private static final Integer locationPlaceholder = new Integer(0);
+    private static final Integer LOCATION_PLACEHOLDER = new Integer(0);
     /**
-     * the version of PDF supported
+     * the version of PDF supported which is 1.4
      */
-    protected static final String pdfVersion = "1.4";
+    protected static final String PDF_VERSION = "1.4";
 
     /**
      * the current character position
@@ -106,7 +103,6 @@ public class PDFDocument {
     /**
      * the colorspace (0=RGB, 1=CMYK)
      */
-    // protected int colorspace = 0;
     protected PDFColorSpace colorspace = new PDFColorSpace(PDFColorSpace.DEVICE_RGB);
 
     /**
@@ -135,11 +131,29 @@ public class PDFDocument {
      */
     protected HashMap fontMap = new HashMap();
 
+    /**
+     * The filter map.
+     */
     protected HashMap filterMap = new HashMap();
 
+    /**
+     * List of PDFGState objects.
+     */
     protected ArrayList gstates = new ArrayList();
+
+    /**
+     * List of functions.
+     */
     protected ArrayList functions = new ArrayList();
+
+    /**
+     * List of shadings.
+     */
     protected ArrayList shadings = new ArrayList();
+
+    /**
+     * List of patterns.
+     */
     protected ArrayList patterns = new ArrayList();
 
     /**
@@ -150,9 +164,9 @@ public class PDFDocument {
      * the trailer is written. Note that the object ID of the
      * pages object is determined now, and the xref table is
      * updated later. This allows Pages to refer to their
-     * Parent before we write it out. This took me a long
-     * time to work out, and is so obvious now. Sigh.
-     * mark-fop@inomial.com. Maybe I should do a PDF course.
+     * Parent before we write it out.
+     *
+     * @param prod the name of the producer of this pdf document
      */
     public PDFDocument(String prod) {
 
@@ -178,10 +192,20 @@ public class PDFDocument {
         this.info.setProducer(producer);
     }
 
+    /**
+     * Set the filter map to use for filters in this document.
+     *
+     * @param map the map of filter lists for each stream type
+     */
     public void setFilterMap(HashMap map) {
         filterMap = map;
     }
 
+    /**
+     * Get the filter map used for filters in this document.
+     *
+     * @return the map of filters being used
+     */
     public HashMap getFilterMap() {
         return filterMap;
     }
@@ -189,6 +213,9 @@ public class PDFDocument {
     /**
      * Make a /Catalog (Root) object. This object is written in
      * the trailer.
+     *
+     * @param pages the pages pdf object that the root points to
+     * @return the new pdf root object for this document
      */
     public PDFRoot makeRoot(PDFPages pages) {
 
@@ -202,8 +229,9 @@ public class PDFDocument {
 
     /**
      * Make a /Pages object. This object is written in the trailer.
+     *
+     * @return a new PDF Pages object for adding pages to
      */
-
     public PDFPages makePages() {
         PDFPages pdfPages = new PDFPages(++this.objectcount);
         addTrailerObject(pdfPages);
@@ -212,6 +240,8 @@ public class PDFDocument {
 
     /**
      * Make a /Resources object. This object is written in the trailer.
+     *
+     * @return a new PDF resources object
      */
     public PDFResources makeResources() {
         PDFResources pdfResources = new PDFResources(++this.objectcount);
@@ -222,7 +252,7 @@ public class PDFDocument {
     /**
      * make an /Info object
      *
-     * @param producer string indicating application producing the PDF
+     * @param prod string indicating application producing the PDF
      * @return the created /Info object
      */
     protected PDFInfo makeInfo(String prod) {
@@ -238,6 +268,11 @@ public class PDFDocument {
         return pdfInfo;
     }
 
+    /**
+     * Get the pdf info object for this document.
+     *
+     * @return the PDF Info object for this document
+     */
     public PDFInfo getInfo() {
         return info;
     }
@@ -257,10 +292,12 @@ public class PDFDocument {
      * so maybe this should be an array of length 2.
      *
      * See page 265 of the PDF 1.3 Spec.
-     * @param theBitsPerSample An int specifying the number of bits user to represent each sample value.
+     * @param theBitsPerSample An int specifying the number of bits user
+     *                    to represent each sample value.
      * Limited to 1,2,4,8,12,16,24 or 32.
      * See page 265 of the 1.3 PDF Spec.
-     * @param theOrder The order of interpolation between samples. Default is 1 (one). Limited
+     * @param theOrder The order of interpolation between samples.
+     *                 Default is 1 (one). Limited
      * to 1 (one) or 3, which means linear or cubic-spline interpolation.
      *
      * This attribute is optional.
@@ -279,14 +316,16 @@ public class PDFDocument {
      *
      * This attribute is optional.
      * Read about it on page 265 of the PDF 1.3 spec.
-     * @param theFunctionDataStream The sample values that specify the function are provided in a stream.
+     * @param theFunctionDataStream The sample values that specify
+     *                        the function are provided in a stream.
      *
      * This is optional, but is almost always used.
      *
      * Page 265 of the PDF 1.3 spec has more.
-     * @param theFilter This is a vector of String objects which are the various filters that
-     * have are to be applied to the stream to make sense of it. Order matters,
-     * so watch out.
+     * @param theFilter This is a vector of String objects which
+     *                  are the various filters that have are to be
+     *                  applied to the stream to make sense of it.
+     *                  Order matters, so watch out.
      *
      * This is not documented in the Function section of the PDF 1.3 spec,
      * it was deduced from samples that this is sometimes used, even if we may never
@@ -300,7 +339,8 @@ public class PDFDocument {
                                     int theBitsPerSample, int theOrder,
                                     ArrayList theEncode, ArrayList theDecode,
                                     StringBuffer theFunctionDataStream,
-                                    ArrayList theFilter) {    // Type 0 function
+                                    ArrayList theFilter) {
+        // Type 0 function
         PDFFunction function = new PDFFunction(++this.objectcount,
                                                theFunctionType, theDomain,
                                                theRange, theSize,
@@ -310,7 +350,7 @@ public class PDFDocument {
                                                theFilter);
 
         PDFFunction oldfunc = findFunction(function);
-        if(oldfunc == null) {
+        if (oldfunc == null) {
             functions.add(function);
             this.objects.add(function);
         } else {
@@ -355,7 +395,7 @@ public class PDFDocument {
                                                theRange, theCZero, theCOne,
                                                theInterpolationExponentN);
         PDFFunction oldfunc = findFunction(function);
-        if(oldfunc == null) {
+        if (oldfunc == null) {
             functions.add(function);
             this.objects.add(function);
         } else {
@@ -367,9 +407,9 @@ public class PDFDocument {
     }
 
     private PDFFunction findFunction(PDFFunction compare) {
-        for(Iterator iter = functions.iterator(); iter.hasNext(); ) {
+        for (Iterator iter = functions.iterator(); iter.hasNext();) {
             Object func = iter.next();
-            if(compare.equals(func)) {
+            if (compare.equals(func)) {
                 return (PDFFunction)func;
             }
         }
@@ -377,9 +417,9 @@ public class PDFDocument {
     }
 
     private PDFShading findShading(PDFShading compare) {
-        for(Iterator iter = shadings.iterator(); iter.hasNext(); ) {
+        for (Iterator iter = shadings.iterator(); iter.hasNext();) {
             Object shad = iter.next();
-            if(compare.equals(shad)) {
+            if (compare.equals(shad)) {
                 return (PDFShading)shad;
             }
         }
@@ -393,9 +433,9 @@ public class PDFDocument {
      * would only be a small amount of data.
      */
     private PDFPattern findPattern(PDFPattern compare) {
-        for(Iterator iter = patterns.iterator(); iter.hasNext(); ) {
+        for (Iterator iter = patterns.iterator(); iter.hasNext();) {
             Object patt = iter.next();
-            if(compare.equals(patt)) {
+            if (compare.equals(patt)) {
                 return (PDFPattern)patt;
             }
         }
@@ -411,14 +451,17 @@ public class PDFDocument {
      * @param theRange ArrayList objects of Double objects.
      * This is the Range of the function.
      * See page 264 of the PDF 1.3 Spec.
-     * @param theFunctions A ArrayList of the PDFFunction objects that the stitching function stitches.
+     * @param theFunctions An ArrayList of the PDFFunction objects
+     *                     that the stitching function stitches.
      *
      * This attributed is required.
      * It is described on page 269 of the PDF spec.
-     * @param theBounds This is a vector of Doubles representing the numbers that,
-     * in conjunction with Domain define the intervals to which each function from
-     * the 'functions' object applies. It must be in order of increasing magnitude,
-     * and each must be within Domain.
+     * @param theBounds This is a vector of Doubles representing
+     *                  the numbers that, in conjunction with Domain
+     *                  define the intervals to which each function from
+     *                  the 'functions' object applies. It must be in
+     *                  order of increasing magnitude, and each must be
+     *                  within Domain.
      *
      * It basically sets how much of the gradient each function handles.
      *
@@ -437,7 +480,8 @@ public class PDFDocument {
     public PDFFunction makeFunction(int theFunctionType, ArrayList theDomain,
                                     ArrayList theRange, ArrayList theFunctions,
                                     ArrayList theBounds,
-                                    ArrayList theEncode) {    // Type 3
+                                    ArrayList theEncode) {
+        // Type 3
 
         PDFFunction function = new PDFFunction(++this.objectcount,
                                                theFunctionType, theDomain,
@@ -445,7 +489,7 @@ public class PDFDocument {
                                                theBounds, theEncode);
 
         PDFFunction oldfunc = findFunction(function);
-        if(oldfunc == null) {
+        if (oldfunc == null) {
             functions.add(function);
             this.objects.add(function);
         } else {
@@ -474,7 +518,7 @@ public class PDFDocument {
                                                theFunctionDataStream);
 
         PDFFunction oldfunc = findFunction(function);
-        if(oldfunc == null) {
+        if (oldfunc == null) {
             functions.add(function);
             this.objects.add(function);
         } else {
@@ -512,7 +556,8 @@ public class PDFDocument {
                                   ArrayList theBackground, ArrayList theBBox,
                                   boolean theAntiAlias, ArrayList theDomain,
                                   ArrayList theMatrix,
-                                  PDFFunction theFunction) {    // make Shading of Type 1
+                                  PDFFunction theFunction) {
+        // make Shading of Type 1
         String theShadingName = new String("Sh" + (++this.shadingCount));
 
         PDFShading shading = new PDFShading(++this.objectcount,
@@ -522,7 +567,7 @@ public class PDFDocument {
                                             theMatrix, theFunction);
 
         PDFShading oldshad = findShading(shading);
-        if(oldshad == null) {
+        if (oldshad == null) {
             shadings.add(shading);
             this.objects.add(shading);
         } else {
@@ -532,7 +577,7 @@ public class PDFDocument {
         }
 
         // add this shading to resources
-        if(res != null) {
+        if (res != null) {
             res.getPDFResources().addShading(shading);
         } else {
             this.resources.addShading(shading);
@@ -556,8 +601,10 @@ public class PDFDocument {
      * @param theAntiAlias Default is false
      * @param theCoords ArrayList of four (type 2) or 6 (type 3) Double
      * @param theDomain ArrayList of Doubles specifying the domain
-     * @param theFunction the Stitching (PDFfunction type 3) function, even if it's stitching a single function
-     * @param theExtend ArrayList of Booleans of whether to extend teh start and end colors past the start and end points
+     * @param theFunction the Stitching (PDFfunction type 3) function,
+     *                    even if it's stitching a single function
+     * @param theExtend ArrayList of Booleans of whether to extend the
+     *                  start and end colors past the start and end points
      * The default is [false, false]
      */
     public PDFShading makeShading(PDFResourceContext res, int theShadingType,
@@ -565,7 +612,8 @@ public class PDFDocument {
                                   ArrayList theBackground, ArrayList theBBox,
                                   boolean theAntiAlias, ArrayList theCoords,
                                   ArrayList theDomain, PDFFunction theFunction,
-                                  ArrayList theExtend) {    // make Shading of Type 2 or 3
+                                  ArrayList theExtend) {
+        // make Shading of Type 2 or 3
         String theShadingName = new String("Sh" + (++this.shadingCount));
 
         PDFShading shading = new PDFShading(++this.objectcount,
@@ -576,7 +624,7 @@ public class PDFDocument {
                                             theExtend);
 
         PDFShading oldshad = findShading(shading);
-        if(oldshad == null) {
+        if (oldshad == null) {
             shadings.add(shading);
             this.objects.add(shading);
         } else {
@@ -585,7 +633,7 @@ public class PDFDocument {
             shading = oldshad;
         }
 
-        if(res != null) {
+        if (res != null) {
             res.getPDFResources().addShading(shading);
         } else {
             this.resources.addShading(shading);
@@ -623,7 +671,8 @@ public class PDFDocument {
                                   int theBitsPerCoordinate,
                                   int theBitsPerComponent,
                                   int theBitsPerFlag, ArrayList theDecode,
-                                  PDFFunction theFunction) {    // make Shading of type 4,6 or 7
+                                  PDFFunction theFunction) {
+        // make Shading of type 4,6 or 7
         String theShadingName = new String("Sh" + (++this.shadingCount));
 
         PDFShading shading = new PDFShading(++this.objectcount,
@@ -636,7 +685,7 @@ public class PDFDocument {
                                             theFunction);
 
         PDFShading oldshad = findShading(shading);
-        if(oldshad == null) {
+        if (oldshad == null) {
             shadings.add(shading);
             this.objects.add(shading);
         } else {
@@ -645,7 +694,7 @@ public class PDFDocument {
             shading = oldshad;
         }
 
-        if(res != null) {
+        if (res != null) {
             res.getPDFResources().addShading(shading);
         } else {
             this.resources.addShading(shading);
@@ -681,7 +730,8 @@ public class PDFDocument {
                                   int theBitsPerCoordinate,
                                   int theBitsPerComponent, ArrayList theDecode,
                                   int theVerticesPerRow,
-                                  PDFFunction theFunction) {    // make shading of Type 5
+                                  PDFFunction theFunction) {
+        // make shading of Type 5
         String theShadingName = new String("Sh" + (++this.shadingCount));
 
         PDFShading shading = new PDFShading(++this.objectcount,
@@ -693,7 +743,7 @@ public class PDFDocument {
                                             theVerticesPerRow, theFunction);
 
         PDFShading oldshad = findShading(shading);
-        if(oldshad == null) {
+        if (oldshad == null) {
             shadings.add(shading);
             this.objects.add(shading);
         } else {
@@ -702,7 +752,7 @@ public class PDFDocument {
             shading = oldshad;
         }
 
-        if(res != null) {
+        if (res != null) {
             res.getPDFResources().addShading(shading);
         } else {
             this.resources.addShading(shading);
@@ -727,7 +777,8 @@ public class PDFDocument {
      */
     public PDFPattern makePattern(PDFResourceContext res, int thePatternType,    // 1
                                   PDFResources theResources, int thePaintType, int theTilingType,
-                                  ArrayList theBBox, double theXStep, double theYStep, ArrayList theMatrix,
+                                  ArrayList theBBox, double theXStep,
+                                  double theYStep, ArrayList theMatrix,
                                   ArrayList theXUID, StringBuffer thePatternDataStream) {
         String thePatternName = new String("Pa" + (++this.patternCount));
         // int theNumber, String thePatternName,
@@ -740,7 +791,7 @@ public class PDFDocument {
                                             thePatternDataStream);
 
         PDFPattern oldpatt = findPattern(pattern);
-        if(oldpatt == null) {
+        if (oldpatt == null) {
             patterns.add(pattern);
             this.objects.add(pattern);
         } else {
@@ -749,7 +800,7 @@ public class PDFDocument {
             pattern = oldpatt;
         }
 
-        if(res != null) {
+        if (res != null) {
             res.getPDFResources().addPattern(pattern);
         } else {
             this.resources.addPattern(pattern);
@@ -767,7 +818,8 @@ public class PDFDocument {
      * @param theExtGState optional: the extended graphics state, if used.
      * @param theMatrix Optional:ArrayList of Doubles that specify the matrix.
      */
-    public PDFPattern makePattern(PDFResourceContext res, int thePatternType, PDFShading theShading,
+    public PDFPattern makePattern(PDFResourceContext res,
+                                  int thePatternType, PDFShading theShading,
                                   ArrayList theXUID, StringBuffer theExtGState,
                                   ArrayList theMatrix) {
         String thePatternName = new String("Pa" + (++this.patternCount));
@@ -777,7 +829,7 @@ public class PDFDocument {
                                             theXUID, theExtGState, theMatrix);
 
         PDFPattern oldpatt = findPattern(pattern);
-        if(oldpatt == null) {
+        if (oldpatt == null) {
             patterns.add(pattern);
             this.objects.add(pattern);
         } else {
@@ -786,7 +838,7 @@ public class PDFDocument {
             pattern = oldpatt;
         }
 
-        if(res != null) {
+        if (res != null) {
             res.getPDFResources().addPattern(pattern);
         } else {
             this.resources.addPattern(pattern);
@@ -834,11 +886,13 @@ public class PDFDocument {
                                  + 1);
             // colorspace must be consistant
             if (this.colorspace.getColorSpace()
-                    != currentColor.getColorSpace())
+                    != currentColor.getColorSpace()) {
                 currentColor.setColorSpace(this.colorspace.getColorSpace());
+            }
 
-            if (this.colorspace.getColorSpace() != nextColor.getColorSpace())
+            if (this.colorspace.getColorSpace() != nextColor.getColorSpace()) {
                 nextColor.setColorSpace(this.colorspace.getColorSpace());
+            }
 
             theCzero = currentColor.getVector();
             theCone = nextColor.getVector();
@@ -916,6 +970,11 @@ public class PDFDocument {
         return iccStream;
     }
 
+    /**
+     * Get the font map for this document.
+     *
+     * @return the map of fonts used in this document
+     */
     public HashMap getFontMap() {
         return fontMap;
     }
@@ -933,7 +992,7 @@ public class PDFDocument {
     public PDFFont makeFont(String fontname, String basefont,
                             String encoding, FontMetric metrics,
                             FontDescriptor descriptor) {
-        if(fontMap.containsKey(fontname)) {
+        if (fontMap.containsKey(fontname)) {
             return (PDFFont)fontMap.get(fontname);
         }
 
@@ -949,9 +1008,10 @@ public class PDFDocument {
             return font;
         } else {
             byte subtype = PDFFont.TYPE1;
-            if (metrics instanceof org.apache.fop.render.pdf.Font)
+            if (metrics instanceof org.apache.fop.render.pdf.Font) {
                 subtype =
                     ((org.apache.fop.render.pdf.Font)metrics).getSubType();
+            }
 
             PDFFontDescriptor pdfdesc = makeFontDescriptor(descriptor,
                                         subtype);
@@ -987,9 +1047,9 @@ public class PDFDocument {
 
             if (subtype == PDFFont.TYPE0) {
                 CIDFont cidMetrics;
-                if(metrics instanceof LazyFont){
+                if (metrics instanceof LazyFont) {
                     cidMetrics = (CIDFont) ((LazyFont) metrics).getRealFont();
-                }else{
+                } else {
                     cidMetrics = (CIDFont)metrics;
                 }
                 PDFCIDSystemInfo sysInfo =
@@ -1004,8 +1064,6 @@ public class PDFDocument {
                                    (PDFCIDFontDescriptor)pdfdesc);
                 this.objects.add(cidFont);
 
-                // ((PDFFontType0)font).setCMAP(cmap);
-
                 ((PDFFontType0)font).setDescendantFonts(cidFont);
             } else {
                 font.setWidthMetrics(metrics.getFirstChar(),
@@ -1032,14 +1090,10 @@ public class PDFDocument {
             font = new PDFCIDFontDescriptor(++this.objectcount,
                                             desc.fontName(),
                                             desc.getFontBBox(),
-                                            // desc.getAscender(),
-                                            // desc.getDescender(),
                                             desc.getCapHeight(), desc.getFlags(),
-                                            // new PDFRectangle(desc.getFontBBox()),
-                                            desc.getItalicAngle(), desc.getStemV(), null);    // desc.getLang(),
-            // null);//desc.getPanose());
-        }
-        else {
+                                            desc.getItalicAngle(),
+                                            desc.getStemV(), null);
+        } else {
             // Create normal FontDescriptor
             font = new PDFFontDescriptor(++this.objectcount, desc.fontName(),
                                          desc.getAscender(),
@@ -1089,12 +1143,12 @@ public class PDFDocument {
         wanted.addValues(settings);
 
         PDFGState poss;
-        for(Iterator iter = gstates.iterator(); iter.hasNext(); ) {
+        for (Iterator iter = gstates.iterator(); iter.hasNext();) {
             PDFGState avail = (PDFGState)iter.next();
             poss = new PDFGState(0);
             poss.addValues(current);
             poss.addValues(avail);
-            if(poss.equals(wanted)) {
+            if (poss.equals(wanted)) {
                 return avail;
             }
         }
@@ -1116,7 +1170,7 @@ public class PDFDocument {
         String key = img.getKey();
         PDFXObject xObject = (PDFXObject)xObjectsMap.get(key);
         if (xObject != null) {
-            if(res != null) {
+            if (res != null) {
                 res.getPDFResources().addXObject(xObject);
             }
             return xObject;
@@ -1129,7 +1183,7 @@ public class PDFDocument {
                                  img);
         this.objects.add(xObject);
         this.resources.addXObject(xObject);
-        if(res != null) {
+        if (res != null) {
             res.getPDFResources().addXObject(xObject);
         }
         this.xObjectsMap.put(key, xObject);
@@ -1234,8 +1288,9 @@ public class PDFDocument {
       objects that have been created.
      */
     private void prepareLocations() {
-        while(location.size() < objectcount)
-            location.add(locationPlaceholder);
+        while (location.size() < objectcount) {
+            location.add(LOCATION_PLACEHOLDER);
+        }
     }
 
     /**
@@ -1253,7 +1308,7 @@ public class PDFDocument {
         PDFStream obj = new PDFStream(++this.objectcount);
         obj.addDefaultFilters(filterMap, type);
 
-        if(add) {
+        if (add) {
             this.objects.add(obj);
         }
         return obj;
@@ -1261,6 +1316,8 @@ public class PDFDocument {
 
     /**
      * add a stream object
+     *
+     * @param obj the PDF Stream to add to this document
      */
     public void addStream(PDFStream obj) {
         this.objects.add(obj);
@@ -1286,10 +1343,13 @@ public class PDFDocument {
      * Get the root Outlines object. This method does not write
      * the outline to the PDF document, it simply creates a
      * reference for later.
+     *
+     * @return the PDF Outline root object
      */
     public PDFOutline getOutlineRoot() {
-        if(outlineRoot != null)
+        if (outlineRoot != null) {
             return outlineRoot;
+        }
 
         outlineRoot = new PDFOutline(++this.objectcount, null, null);
         addTrailerObject(outlineRoot);
@@ -1299,9 +1359,11 @@ public class PDFDocument {
 
     /**
      * Make an outline object and add it to the given outline
-     * @param parent parent PDFOutline object
+     *
+     * @param parent parent PDFOutline object which may be null
      * @param label the title for the new outline object
      * @param destination the reference string for the action to go to
+     * @return the new PDF outline object
      */
     public PDFOutline makeOutline(PDFOutline parent, String label,
                                   String destination) {
@@ -1328,7 +1390,8 @@ public class PDFDocument {
     /**
      * write the entire document out
      *
-     * @param writer the OutputStream to output the document to
+     * @param stream the OutputStream to output the document to
+     * @throws IOException if there is an exception writing to the output stream
      */
     public void output(OutputStream stream) throws IOException {
 
@@ -1362,13 +1425,13 @@ public class PDFDocument {
      * and outputting AreaTrees.
      *
      * @param stream the OutputStream to write the header to
-     * @return the number of bytes written
+     * @throws IOException if there is an exception writing to the output stream
      */
     public void outputHeader(OutputStream stream)
     throws IOException {
-        this.position=0;
+        this.position = 0;
 
-        byte[] pdf = ("%PDF-" + this.pdfVersion + "\n").getBytes();
+        byte[] pdf = ("%PDF-" + PDF_VERSION + "\n").getBytes();
         stream.write(pdf);
         this.position += pdf.length;
 
@@ -1385,11 +1448,12 @@ public class PDFDocument {
      * write the trailer
      *
      * @param stream the OutputStream to write the trailer to
+     * @throws IOException if there is an exception writing to the output stream
      */
     public void outputTrailer(OutputStream stream)
     throws IOException {
         output(stream);
-        for(int count = 0; count < trailerObjects.size(); count++) {
+        for (int count = 0; count < trailerObjects.size(); count++) {
             PDFObject o = (PDFObject) trailerObjects.get(count);
             this.location.set(o.getNumber() - 1, 
                               new Integer(this.position));
@@ -1400,16 +1464,13 @@ public class PDFDocument {
         this.position += outputXref(stream);
 
         /* construct the trailer */
-        String pdf =
-            "trailer\n" +
-            "<<\n" +
-            "/Size " + (this.objectcount + 1) + "\n" +
-            "/Root " + this.root.number + " " + this.root.generation + " R\n" +
-            "/Info " + this.info.number + " " + this.info.generation + " R\n" +
-            ">>\n" +
-            "startxref\n" +
-            this.xref + "\n" +
-            "%%EOF\n";
+        String pdf = "trailer\n" + "<<\n"
+                     + "/Size " + (this.objectcount + 1) + "\n"
+                     + "/Root " + this.root.number + " "
+                     + this.root.generation + " R\n" + "/Info "
+                     + this.info.number + " " + this.info.generation
+                     + " R\n" + ">>\n" + "startxref\n" + this.xref
+                     + "\n" + "%%EOF\n";
 
         /* write the trailer */
         stream.write(pdf.getBytes());
diff --git a/src/org/apache/fop/pdf/PDFXObject.java b/src/org/apache/fop/pdf/PDFXObject.java
index 8430751d9..5de9df5cd 100644
--- a/src/org/apache/fop/pdf/PDFXObject.java
+++ b/src/org/apache/fop/pdf/PDFXObject.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -13,38 +13,51 @@ package org.apache.fop.pdf;
 // Java
 import java.io.IOException;
 import java.io.OutputStream;
-import java.io.ByteArrayOutputStream;
 
 /**
  * PDF XObject
  *
  * A derivative of the PDF Object, is a PDF Stream that has not only a
  * dictionary but a stream of image data.
- * the dictionary just provides information like the stream length
+ * The dictionary just provides information like the stream length.
+ * This outputs the image dictionary and the image data.
+ * This is used as a reference for inserting the same image in the
+ * document in another place.
  */
 public class PDFXObject extends PDFObject {
-    PDFImage pdfimage;
-    int Xnum;
+    private PDFImage pdfimage;
+    private int xnum;
 
     /**
      * create an XObject with the given number and name and load the
      * image in the object
+     *
+     * @param number the pdf object number
+     * @param xnumber the pdf object X number
+     * @param img the pdf image that contains the image data
      */
-    public PDFXObject(int number, int Xnumber, PDFImage img) {
+    public PDFXObject(int number, int xnumber, PDFImage img) {
         super(number);
-        this.Xnum = Xnumber;
+        this.xnum = xnumber;
         pdfimage = img;
     }
 
     /**
+     * Get the xnumber for this pdf object.
+     *
      * @return the PDF XObject number
      */
     public int getXNumber() {
-        return this.Xnum;
+        return this.xnum;
     }
 
     /**
-     * represent as PDF
+     * Output the image as PDF.
+     * This sets up the image dictionary and adds the image data stream.
+     *
+     * @param stream the output stream to write the data
+     * @throws IOException if there is an error writing the data
+     * @return the length of the data written
      */
     protected int output(OutputStream stream) throws IOException {
         int length = 0;
@@ -61,38 +74,38 @@ public class PDFXObject extends PDFObject {
             String p = this.number + " " + this.generation + " obj\n";
             p = p + "<</Type /XObject\n";
             p = p + "/Subtype /Image\n";
-            p = p + "/Name /Im" + Xnum + "\n";
+            p = p + "/Name /Im" + xnum + "\n";
             p = p + "/Length " + (imgStream.getDataLength() + 1) + "\n";
             p = p + "/Width " + pdfimage.getWidth() + "\n";
             p = p + "/Height " + pdfimage.getHeight() + "\n";
-            p = p + "/BitsPerComponent " + pdfimage.getBitsPerPixel() +
-                "\n";
+            p = p + "/BitsPerComponent " + pdfimage.getBitsPerPixel()
+                  + "\n";
 
             PDFICCStream pdfICCStream = pdfimage.getICCStream();
             if (pdfICCStream != null) {
-                p = p + "/ColorSpace [/ICCBased " +
-                    pdfICCStream.referencePDF() + "]\n";
+                p = p + "/ColorSpace [/ICCBased "
+                    + pdfICCStream.referencePDF() + "]\n";
             } else {
                 PDFColorSpace cs = pdfimage.getColorSpace();
-                p = p + "/ColorSpace /" + cs.getColorSpacePDFString() +
-                    "\n";
+                p = p + "/ColorSpace /" + cs.getColorSpacePDFString()
+                      + "\n";
             }
 
             /* PhotoShop generates CMYK values that's inverse,
                this will invert the values - too bad if it's not
                a PhotoShop image...
              */
-            if (pdfimage.getColorSpace().getColorSpace() ==
-                    PDFColorSpace.DEVICE_CMYK) {
+            if (pdfimage.getColorSpace().getColorSpace()
+                    == PDFColorSpace.DEVICE_CMYK) {
                 p = p + "/Decode [ 1.0 0.0 1.0 0.0 1.0 0.0 1.1 0.0 ]\n";
             }
 
             if (pdfimage.isTransparent()) {
                 PDFColor transp = pdfimage.getTransparentColor();
-                p = p + "/Mask [" + transp.red255() + " " +
-                    transp.red255() + " " + transp.green255() +
-                    " " + transp.green255() + " " +
-                    transp.blue255() + " " + transp.blue255() + "]\n";
+                p = p + "/Mask [" + transp.red255() + " "
+                    + transp.red255() + " " + transp.green255()
+                    + " " + transp.green255() + " "
+                    + transp.blue255() + " " + transp.blue255() + "]\n";
             }
             String ref = pdfimage.getSoftMask();
             if (ref != null) {
@@ -115,6 +128,8 @@ public class PDFXObject extends PDFObject {
             length += pdfBytes.length;
         }
         // let it gc
+        // this object is retained as a reference to inserting
+        // the same image but the image data is no longer needed
         pdfimage = null;
         return length;
     }