Squashed CheckStyle warnings, mostly JavaDoc.

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

16 files changed, 156 insertions, 57 deletions

diff --git a/src/java/org/apache/fop/apps/FOPException.java b/src/java/org/apache/fop/apps/FOPException.java
index 569a025f1..5a496bd67 100644
--- a/src/java/org/apache/fop/apps/FOPException.java
+++ b/src/java/org/apache/fop/apps/FOPException.java
@@ -33,14 +33,20 @@ public class FOPException extends SAXException {
     private int column;
 
     /**
-     * create a new FOP Exception
-     *
-     * @param message descriptive message
+     * Constructs a new FOP exception with the specified detail message.
+     * @param message the detail message.
      */
     public FOPException(String message) {
         super(message);
     }
 
+    /**
+     * Constructs a new FOP exception with the specified detail message and location.
+     * @param message the detail message
+     * @param systemId the system id of the FO document which is associated with the exception. May be null.
+     * @param line line number in the FO document which is associated with the exception.
+     * @param column clolumn number in the line which is associated with the exception.
+     */
     public FOPException(String message, String systemId, int line, int column) {
         super(message);
         this.systemId = systemId;
@@ -48,6 +54,11 @@ public class FOPException extends SAXException {
         this.column = column;
     }
 
+    /**
+     * Constructs a new FOP exception with the specified detail message and location.
+     * @param message the detail message.
+     * @param locator the locator holding the location.
+     */
     public FOPException(String message, Locator locator) {
         super(message);
         setLocator(locator);
@@ -55,22 +66,26 @@ public class FOPException extends SAXException {
 
 
     /**
-     *
-     * @param e Throwable object
+     * Constructs a new FOP exception with the specified cause.
+     * @param cause the cause.
      */
-    public FOPException(Exception e) {
-        super(e);
+    public FOPException(Exception cause) {
+        super(cause);
     }
 
     /**
-     *
-     * @param message descriptive message
-     * @param e Throwable object
+     * Constructs a new exception with the specified detail message and cause.
+     * @param message  the detail message
+     * @param cause the cause 
      */
-    public FOPException(String message, Throwable e) {
-        super(message);
+    public FOPException(String message, Exception cause) {
+        super(message, cause);
     }
 
+    /**
+     * Set a location associated with the exception.
+     * @param location the locator holding the location.
+     */
     public void setLocator(Locator locator) {
         if (locator != null) {
             this.systemId = locator.getSystemId();
@@ -79,19 +94,40 @@ public class FOPException extends SAXException {
         }
     }
 
+    /**
+     * Set a location associated with the exception.
+     * @param systemId the system id of the FO document which is associated with the exception. May be null.
+     * @param line line number in the FO document which is associated with the exception.
+     * @param column clolumn number in the line which is associated with the exception.
+     */
     public void setLocation(String systemId, int line, int column) {
         this.systemId = systemId;
         this.line = line;
         this.column = column;
     }
 
+    /**
+     * Indicate whether a location was set.
+     */
     public boolean isLocationSet() {
+        // TODO: this is actually a dangerous assumption: A line
+        // number of 0 or -1 might be used to indicate an unknown line
+        // number, while the system ID might still be of use.
         return line > 0;
     }
 
+    /**
+     * Returns the detail message string of this FOP exception.
+     * If a location was set, the message is prepended with it in the
+     * form
+     * <pre>
+     *  SystemId:LL:CC: &amp;the message&amp;
+     * </pre>
+     * (the format used by most GNU tools)
+     */
     public String getMessage() {
         if (isLocationSet()) {
-            return systemId + ":" + line + "," + column + " " + super.getMessage();
+            return systemId + ":" + line + ":" + column + ": " + super.getMessage();
         } else {
             return super.getMessage();
         }
@@ -108,8 +144,8 @@ public class FOPException extends SAXException {
             result = ((SAXException)result).getException();
         }
         if (result instanceof java.lang.reflect.InvocationTargetException) {
-            result =
-                ((java.lang.reflect.InvocationTargetException)result).getTargetException();
+            result
+                = ((java.lang.reflect.InvocationTargetException)result).getTargetException();
         }
         if (result != getException()) {
             return result;
@@ -118,7 +154,7 @@ public class FOPException extends SAXException {
     }
 
     /**
-     * Write stack trace to stderr
+     * Prints this FOP exception and its backtrace to the standard error stream.
      */
     public void printStackTrace() {
         synchronized (System.err) {
@@ -135,8 +171,8 @@ public class FOPException extends SAXException {
     }
 
     /**
-     * write stack trace on a PrintStream
-     * @param stream PrintStream on which to write stack trace
+     * Prints this FOP exception and its backtrace to the specified print stream.
+     * @param stream PrintStream to use for output
      */
     public void printStackTrace(java.io.PrintStream stream) {
         synchronized (stream) {
@@ -153,8 +189,8 @@ public class FOPException extends SAXException {
     }
 
     /**
-     * Write stack trace on a PrintWriter
-     * @param writer PrintWriter on which to write stack trace
+     * Prints this FOP exception and its backtrace to the specified print writer.
+     * @param writer PrintWriter to use for output
      */
     public void printStackTrace(java.io.PrintWriter writer) {
         synchronized (writer) {
diff --git a/src/java/org/apache/fop/apps/FOUserAgent.java b/src/java/org/apache/fop/apps/FOUserAgent.java
index 328087f3b..d84715ba4 100644
--- a/src/java/org/apache/fop/apps/FOUserAgent.java
+++ b/src/java/org/apache/fop/apps/FOUserAgent.java
@@ -421,7 +421,6 @@ public class FOUserAgent {
      */
     public Source resolveURI(String uri) {
         Source source = null;
-        URIResolver uriResolver = getURIResolver();
         if (uriResolver != null) {
             try {
                 source = uriResolver.resolve(uri, getBaseURL());
diff --git a/src/java/org/apache/fop/area/AreaTreeModel.java b/src/java/org/apache/fop/area/AreaTreeModel.java
index 92504696b..34a4d39fa 100644
--- a/src/java/org/apache/fop/area/AreaTreeModel.java
+++ b/src/java/org/apache/fop/area/AreaTreeModel.java
@@ -60,7 +60,7 @@ public class AreaTreeModel {
     }
 
     /**
-     * Add a page to this moel.
+     * Add a page to this model.
      * @param page the page to add to the model.
      */
     public void addPage(PageViewport page) {
@@ -75,6 +75,7 @@ public class AreaTreeModel {
 
     /**
      * Signal the end of the document for any processing.
+     * @throws SAXException if a problem was encountered.
      */
     public void endDocument() throws SAXException {};
 
diff --git a/src/java/org/apache/fop/area/CTM.java b/src/java/org/apache/fop/area/CTM.java
index ca2a79ff8..265121626 100644
--- a/src/java/org/apache/fop/area/CTM.java
+++ b/src/java/org/apache/fop/area/CTM.java
@@ -115,17 +115,15 @@ public class CTM implements Serializable {
         switch (wm) {
             case Constants.EN_LR_TB:
                 return new CTM(CTM_LRTB);
-            case Constants.EN_RL_TB: {
-                    wmctm = new CTM(CTM_RLTB);
-                    wmctm.e = ipd;
-                    return wmctm;
-                }
+            case Constants.EN_RL_TB: 
+                wmctm = new CTM(CTM_RLTB);
+                wmctm.e = ipd;
+                return wmctm;
                 //return  CTM_RLTB.translate(ipd, 0);
-            case Constants.EN_TB_RL: { // CJK
-                    wmctm = new CTM(CTM_TBRL);
-                    wmctm.e = bpd;
-                    return wmctm;
-                }
+            case Constants.EN_TB_RL:  // CJK
+                wmctm = new CTM(CTM_TBRL);
+                wmctm.e = bpd;
+                return wmctm;
                 //return CTM_TBRL.translate(0, ipd);
             default:
                 return null;
@@ -248,6 +246,8 @@ public class CTM implements Serializable {
 
     /**
      * Construct a coordinate transformation matrix (CTM).
+     * @param absRefOrient absolute reference orientation
+     * @param writingmode the writing mode
      * @param absVPrect absolute viewpoint rectangle
      * @param reldims relative dimensions
      * @return CTM the coordinate transformation matrix (CTM)
@@ -294,6 +294,8 @@ public class CTM implements Serializable {
                 case -90:
                     ctm = ctm.translate(height, 0); // height = absVPrect.width
                     break;
+                default:
+                    throw new RuntimeException();
             }
             ctm = ctm.rotate(absRefOrient);
         }
diff --git a/src/java/org/apache/fop/area/CachedRenderPagesModel.java b/src/java/org/apache/fop/area/CachedRenderPagesModel.java
index d7c148c4e..d86e9913b 100644
--- a/src/java/org/apache/fop/area/CachedRenderPagesModel.java
+++ b/src/java/org/apache/fop/area/CachedRenderPagesModel.java
@@ -83,8 +83,8 @@ public class CachedRenderPagesModel extends RenderPagesModel {
                     if (!p.isResolved()) {
                         String[] idrefs = p.getIDRefs();
                         for (int count = 0; count < idrefs.length; count++) {
-                            log.warn("Page " + p.getPageNumberString() + 
-                                ": Unresolved id reference \"" + idrefs[count] 
+                            log.warn("Page " + p.getPageNumberString()
+                                + ": Unresolved id reference \"" + idrefs[count] 
                                 + "\" found.");
                         }
                     }
diff --git a/src/java/org/apache/fop/area/Footnote.java b/src/java/org/apache/fop/area/Footnote.java
index 928b39cf5..735dfaf25 100644
--- a/src/java/org/apache/fop/area/Footnote.java
+++ b/src/java/org/apache/fop/area/Footnote.java
@@ -56,14 +56,29 @@ public class Footnote extends BlockParent {
         return separator;
     }
 
+    /**
+     * Set the relative position of the footnote inside the body region.
+     *
+     * @param top the relative position.
+     */
     public void setTop(int top) {
         this.top = top;
     }
 
+    /**
+     * Get the relative position of the footnote inside the body region.
+     *
+     * @return the relative position.
+     */
     public int getTop() {
         return top;
     }
 
+    /**
+     * Add a block area as child to the footnote area
+     *
+     * @param child the block area.
+     */
     public void addBlock(Block child) {
         if (children == null) {
             children = new ArrayList();
@@ -72,10 +87,20 @@ public class Footnote extends BlockParent {
         children.add(child);
     }
 
+    /**
+     * Get all child areas.
+     *
+     * @return the list of child areas. Maybe null.
+     */
     public List getChildAreas() {
         return children;
     }
 
+    /**
+     * Check whether there are child areas.
+     *
+     * @return the result.
+     */
     public boolean isEmpty() {
         return children == null || children.size() == 0;
     }
diff --git a/src/java/org/apache/fop/area/LineArea.java b/src/java/org/apache/fop/area/LineArea.java
index 2b28033de..7b0037506 100644
--- a/src/java/org/apache/fop/area/LineArea.java
+++ b/src/java/org/apache/fop/area/LineArea.java
@@ -192,6 +192,8 @@ public class LineArea extends Area {
                     finalize();
                 }
                 break;
+            default:
+                throw new RuntimeException();
         }
     }
     
diff --git a/src/java/org/apache/fop/area/LinkResolver.java b/src/java/org/apache/fop/area/LinkResolver.java
index 7874a0334..28390ee6c 100644
--- a/src/java/org/apache/fop/area/LinkResolver.java
+++ b/src/java/org/apache/fop/area/LinkResolver.java
@@ -54,6 +54,11 @@ public class LinkResolver implements Resolvable, Serializable {
         return resolved;
     }
 
+    /**
+     * Get the references for this link.
+     *
+     * @return the String array of references.
+     */
     public String[] getIDRefs() {
         return new String[] {idRef};
     }
diff --git a/src/java/org/apache/fop/area/MainReference.java b/src/java/org/apache/fop/area/MainReference.java
index 7ae288f90..638008587 100644
--- a/src/java/org/apache/fop/area/MainReference.java
+++ b/src/java/org/apache/fop/area/MainReference.java
@@ -36,6 +36,8 @@ public class MainReference extends Area {
 
     /**
      * Constructor
+     *
+     * @param parent the body region this reference area is placed in.
      */
     public MainReference(BodyRegion parent) {
         this.parent = parent;
@@ -46,11 +48,12 @@ public class MainReference extends Area {
      * Add a span area to this area.
      *
      * @param spanAll whether to make a single-column span
+     * @return the created span area.
      */
     public Span createSpan(boolean spanAll) {
         RegionViewport rv = parent.getRegionViewport();
-        int ipdWidth = (int) parent.getIPD() -
-            rv.getBorderAndPaddingWidthStart() - rv.getBorderAndPaddingWidthEnd();
+        int ipdWidth = (int) parent.getIPD()
+            - rv.getBorderAndPaddingWidthStart() - rv.getBorderAndPaddingWidthEnd();
         
         Span newSpan = new Span(((spanAll) ? 1 : getColumnCount()), 
                 getColumnGap(), ipdWidth);
@@ -72,7 +75,7 @@ public class MainReference extends Area {
      * @return the active span.
      */
     public Span getCurrentSpan() {
-        return (Span) spanAreas.get(spanAreas.size()-1);
+        return (Span) spanAreas.get(spanAreas.size() - 1);
     }
 
     /**
@@ -85,7 +88,7 @@ public class MainReference extends Area {
         if (isEmpty) {
             int areaCount = 0;
             if (spanAreas != null) {
-                for (Iterator spaniter = spanAreas.iterator(); spaniter.hasNext(); ) {
+                for (Iterator spaniter = spanAreas.iterator(); spaniter.hasNext();) {
                     Span spanArea = (Span) spaniter.next();
                     for (int i = 0; i < spanArea.getColumnCount(); i++) {
                         NormalFlow flow = spanArea.getNormalFlow(i);
diff --git a/src/java/org/apache/fop/area/PageViewport.java b/src/java/org/apache/fop/area/PageViewport.java
index 263524083..046bd4698 100644
--- a/src/java/org/apache/fop/area/PageViewport.java
+++ b/src/java/org/apache/fop/area/PageViewport.java
@@ -94,6 +94,7 @@ public class PageViewport implements Resolvable, Cloneable {
     /**
      * Create a page viewport 
      * @param spm SimplePageMaster indicating the page and region dimensions
+     * @param pageStr the page number as string.
      * @param p Page Reference Area
      * @param bounds Page Viewport dimensions
      */
@@ -183,8 +184,8 @@ public class PageViewport implements Resolvable, Cloneable {
      * @return String array of idref's that still have not been resolved
      */
     public String[] getIDRefs() {
-        return (unresolvedIDRefs == null) ? null :
-            (String[]) unresolvedIDRefs.keySet().toArray(new String[] {});
+        return (unresolvedIDRefs == null) ? null
+            : (String[]) unresolvedIDRefs.keySet().toArray(new String[] {});
     }
 
     /**
@@ -288,9 +289,8 @@ public class PageViewport implements Resolvable, Cloneable {
                     }
                 }
             }
-        }
-        // at the end of the area, register is-last and any areas
-        else {
+        } else {
+            // at the end of the area, register is-last and any areas
             if (islast) {
                 if (markerLastEnd == null) {
                     markerLastEnd = new HashMap();
@@ -357,6 +357,8 @@ public class PageViewport implements Resolvable, Cloneable {
                     posName = "LastAny after " + posName;
                 }
             break;
+            default:
+                throw new RuntimeException();
         }
         if (log.isTraceEnabled()) {
             log.trace("page " + pageNumberString + ": " + "Retrieving marker " + name 
diff --git a/src/java/org/apache/fop/area/RenderPagesModel.java b/src/java/org/apache/fop/area/RenderPagesModel.java
index c40ff156a..505902e33 100644
--- a/src/java/org/apache/fop/area/RenderPagesModel.java
+++ b/src/java/org/apache/fop/area/RenderPagesModel.java
@@ -152,8 +152,8 @@ public class RenderPagesModel extends AreaTreeModel {
                     if (!p.isResolved()) {
                         String[] idrefs = p.getIDRefs();
                         for (int count = 0; count < idrefs.length; count++) {
-                            log.warn("Page " + p.getPageNumberString() + 
-                                ": Unresolved id reference \"" + idrefs[count] 
+                            log.warn("Page " + p.getPageNumberString()
+                                + ": Unresolved id reference \"" + idrefs[count] 
                                 + "\" found.");
                         }
                     }
@@ -200,6 +200,8 @@ public class RenderPagesModel extends AreaTreeModel {
             case OffDocumentItem.END_OF_DOC:
                 endDocODI.add(oDI);
                 break;
+            default:
+                throw new RuntimeException();
         }
     }
 
diff --git a/src/java/org/apache/fop/area/inline/AbstractTextArea.java b/src/java/org/apache/fop/area/inline/AbstractTextArea.java
index 0bb11cc81..6e8f9d418 100644
--- a/src/java/org/apache/fop/area/inline/AbstractTextArea.java
+++ b/src/java/org/apache/fop/area/inline/AbstractTextArea.java
@@ -35,6 +35,13 @@ public abstract class AbstractTextArea extends InlineArea {
         // (this is equivalent to the property word-spacing.optimum)
         protected int spaceDifference = 0;
         
+        /**
+         * Constructor
+         *
+         * @param stretch the available space for stretching
+         * @param shrink the available space for shrinking
+         * @param adj space adjustment type
+         */
         protected TextAdjustingInfo(int stretch, int shrink, int adj) {
             super(stretch, shrink, adj);
         }
@@ -45,7 +52,7 @@ public abstract class AbstractTextArea extends InlineArea {
     private TextAdjustingInfo adjustingInfo = null;
 
     /**
-     * Default onstructor
+     * Default constructor
      */
     public AbstractTextArea() {
     }
diff --git a/src/java/org/apache/fop/area/inline/InlineArea.java b/src/java/org/apache/fop/area/inline/InlineArea.java
index 02861830b..f187a4080 100644
--- a/src/java/org/apache/fop/area/inline/InlineArea.java
+++ b/src/java/org/apache/fop/area/inline/InlineArea.java
@@ -42,6 +42,13 @@ public class InlineArea extends Area {
         // total adjustment (= ipd - width of fixed elements)
         protected int adjustment;
         
+        /**
+         * Constructor
+         *
+         * @param stretch the available space for stretching
+         * @param shrink the available space for shrinking
+         * @param adj space adjustment type
+         */
         protected InlineAdjustingInfo(int stretch, int shrink, int adj) {
             availableStretch = stretch;
             availableShrink = shrink;
@@ -122,8 +129,9 @@ public class InlineArea extends Area {
     }
     
     /**
-     * Override Area.addChildArea(Area)
-     * set the parent for the child area
+     * Set the parent for the child area.
+     *
+     * @see org.apache.fop.area.inline.Area#addChildArea(Area)
      */
     public void addChildArea(Area childArea) {
         super.addChildArea(childArea);
@@ -132,7 +140,9 @@ public class InlineArea extends Area {
         }
     }
     
-    /** @return true if the inline area is underlined. */
+    /**
+     *@return true if the inline area is underlined.
+     */
     public boolean hasUnderline() {
         return getBooleanTrait(Trait.UNDERLINE);
     }
diff --git a/src/java/org/apache/fop/datatypes/ColorType.java b/src/java/org/apache/fop/datatypes/ColorType.java
index c19819a2d..c9800f34a 100644
--- a/src/java/org/apache/fop/datatypes/ColorType.java
+++ b/src/java/org/apache/fop/datatypes/ColorType.java
@@ -29,29 +29,29 @@ public interface ColorType {
      * Returns the blue component of the color.
      * @return float a value between 0.0 and 1.0
      */
-    public float getBlue();
+    float getBlue();
 
     /**
      * Returns the green component of the color.
      * @return float a value between 0.0 and 1.0
      */
-    public float getGreen();
+    float getGreen();
 
     /**
      * Returns the red component of the color.
      * @return float a value between 0.0 and 1.0
      */
-    public float getRed();
+    float getRed();
 
     /**
      * Returns the alpha (degree of opaque-ness) component of the color.
      * @return float a value between 0.0 (fully transparent) and 1.0 (fully opaque)
      */
-    public float getAlpha();
+    float getAlpha();
 
     /**
      * Returns an AWT instance of this color
      * @return float the AWT color represented by this ColorType instance
      */
-    public Color getAWTColor();
-}
\ No newline at end of file
+    Color getAWTColor();
+}
diff --git a/src/java/org/apache/fop/datatypes/Length.java b/src/java/org/apache/fop/datatypes/Length.java
index 13f7cf5da..08ef93e93 100644
--- a/src/java/org/apache/fop/datatypes/Length.java
+++ b/src/java/org/apache/fop/datatypes/Length.java
@@ -26,13 +26,13 @@ public interface Length extends Numeric {
      * Returns the length in 1/1000ths of a point (millipoints)
      * @return the length in millipoints
      */
-    public int getValue();
+    int getValue();
     
     /**
      * Returns the length in 1/1000ths of a point (millipoints)
      * @param context The context for the length calculation (for percentage based lengths)
      * @return the length in millipoints
      */
-    public int getValue(PercentBaseContext context);
+    int getValue(PercentBaseContext context);
 
 }
diff --git a/src/java/org/apache/fop/datatypes/LengthBase.java b/src/java/org/apache/fop/datatypes/LengthBase.java
index eceaf6139..42960b0c1 100644
--- a/src/java/org/apache/fop/datatypes/LengthBase.java
+++ b/src/java/org/apache/fop/datatypes/LengthBase.java
@@ -77,6 +77,7 @@ public class LengthBase implements PercentBase {
      * @param parentFO parent FO for this
      * @param plist property list for this
      * @param iBaseType a member of {@link #PERCENT_BASED_LENGTH_TYPES}
+     * @throws PropertyException
      */
     public LengthBase(FObj parentFO, PropertyList plist, int iBaseType) throws PropertyException {
         this.fobj = plist.getFObj();
@@ -88,6 +89,10 @@ public class LengthBase implements PercentBase {
         case INH_FONTSIZE:
             this.fontSize = plist.getInherited(Constants.PR_FONT_SIZE).getLength();
             break;
+        default:
+            // TODO: pacify CheckStyle
+            // throw new RuntimeException();
+            break;
         }
     }