From 4d77beff3195315d899d138db2fd5e592e41c9be Mon Sep 17 00:00:00 2001
From: Joerg Pietschmann <pietsch@apache.org>
Date: Thu, 8 Sep 2005 22:06:48 +0000
Subject: [PATCH] Fixed javadoc errors. Added a few TODOs.

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@279656 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/fop/apps/FOPException.java     |  2 +-
 .../org/apache/fop/area/BookmarkData.java     |  2 +-
 src/java/org/apache/fop/area/CTM.java         |  2 +-
 .../apache/fop/area/inline/InlineArea.java    |  2 +-
 .../org/apache/fop/datatypes/LengthBase.java  |  4 ++-
 .../org/apache/fop/datatypes/Numeric.java     |  2 +-
 .../datatypes/SimplePercentBaseContext.java   |  2 +-
 .../apache/fop/fo/expr/NumericProperty.java   |  9 ++---
 .../fop/fo/expr/RelativeNumericProperty.java  | 14 ++++----
 .../org/apache/fop/fo/pagination/Root.java    |  2 +-
 .../fo/properties/BoxPropShorthandParser.java |  4 +--
 .../fop/fo/properties/CharacterProperty.java  |  2 +-
 .../fop/fo/properties/ColorTypeProperty.java  |  2 +-
 .../fo/properties/CompoundPropertyMaker.java  |  4 +--
 .../fop/fo/properties/CondLengthProperty.java |  2 +-
 .../apache/fop/fo/properties/EnumLength.java  | 14 +++-----
 .../fop/fo/properties/EnumProperty.java       |  2 +-
 .../apache/fop/fo/properties/FixedLength.java | 19 ++++-------
 .../fop/fo/properties/KeepProperty.java       |  2 +-
 .../fop/fo/properties/LengthProperty.java     |  2 +-
 .../fo/properties/LengthRangeProperty.java    |  2 +-
 .../properties/LineHeightPropertyMaker.java   |  6 ++--
 .../fop/fo/properties/NumberProperty.java     |  6 ++--
 .../fop/fo/properties/PercentLength.java      |  9 ++---
 .../fop/fo/properties/PropertyMaker.java      | 15 ++++----
 .../fop/fo/properties/SpaceProperty.java      |  2 +-
 .../fop/fo/properties/StringProperty.java     |  2 +-
 .../fop/fo/properties/TableColLength.java     |  9 ++---
 src/java/org/apache/fop/fonts/FontSetup.java  |  5 ++-
 .../layoutmgr/BlockStackingLayoutManager.java |  2 +-
 .../apache/fop/layoutmgr/KnuthElement.java    |  1 -
 .../inline/AbstractGraphicsLayoutManager.java |  3 +-
 .../inline/ContentLayoutManager.java          | 34 ++++++++++++-------
 .../layoutmgr/inline/InlineLayoutManager.java |  2 +-
 .../layoutmgr/inline/TextLayoutManager.java   |  5 +--
 .../list/ListBlockLayoutManager.java          |  1 -
 .../table/CollapsingBorderModel.java          |  5 +--
 .../table/TableContentLayoutManager.java      |  2 +-
 .../apache/fop/pdf/PDFEncryptionManager.java  |  1 -
 .../fop/render/java2d/Java2DRenderer.java     | 22 ++++++++----
 src/java/org/apache/fop/svg/SVGUserAgent.java |  5 ++-
 .../fop/tools/anttasks/FileCompare.java       |  6 ++--
 src/java/org/apache/fop/traits/MinOptMax.java | 22 +++++++-----
 43 files changed, 129 insertions(+), 132 deletions(-)

diff --git a/src/java/org/apache/fop/apps/FOPException.java b/src/java/org/apache/fop/apps/FOPException.java
index 5a496bd67..10fe45fbe 100644
--- a/src/java/org/apache/fop/apps/FOPException.java
+++ b/src/java/org/apache/fop/apps/FOPException.java
@@ -84,7 +84,7 @@ public class FOPException extends SAXException {
 
     /**
      * Set a location associated with the exception.
-     * @param location the locator holding the location.
+     * @param locator the locator holding the location.
      */
     public void setLocator(Locator locator) {
         if (locator != null) {
diff --git a/src/java/org/apache/fop/area/BookmarkData.java b/src/java/org/apache/fop/area/BookmarkData.java
index 92f008d97..ab022e7d9 100644
--- a/src/java/org/apache/fop/area/BookmarkData.java
+++ b/src/java/org/apache/fop/area/BookmarkData.java
@@ -177,7 +177,7 @@ public class BookmarkData extends AbstractOffDocumentItem implements Resolvable
      * id reference.
      *
      * @see org.apache.fop.area.Resolvable#resolveIDRef(String, List)
-     * @todo check to make sure works when multiple bookmark-items
+     * @todo check to make sure it works if multiple bookmark-items
      * have the same idref
      */
     public void resolveIDRef(String id, List pages) {
diff --git a/src/java/org/apache/fop/area/CTM.java b/src/java/org/apache/fop/area/CTM.java
index 265121626..a4eab7c2e 100644
--- a/src/java/org/apache/fop/area/CTM.java
+++ b/src/java/org/apache/fop/area/CTM.java
@@ -247,7 +247,7 @@ public class CTM implements Serializable {
     /**
      * Construct a coordinate transformation matrix (CTM).
      * @param absRefOrient absolute reference orientation
-     * @param writingmode the writing mode
+     * @param writingMode the writing mode
      * @param absVPrect absolute viewpoint rectangle
      * @param reldims relative dimensions
      * @return CTM the coordinate transformation matrix (CTM)
diff --git a/src/java/org/apache/fop/area/inline/InlineArea.java b/src/java/org/apache/fop/area/inline/InlineArea.java
index f187a4080..e448a4516 100644
--- a/src/java/org/apache/fop/area/inline/InlineArea.java
+++ b/src/java/org/apache/fop/area/inline/InlineArea.java
@@ -131,7 +131,7 @@ public class InlineArea extends Area {
     /**
      * Set the parent for the child area.
      *
-     * @see org.apache.fop.area.inline.Area#addChildArea(Area)
+     * @see org.apache.fop.area.Area#addChildArea(Area)
      */
     public void addChildArea(Area childArea) {
         super.addChildArea(childArea);
diff --git a/src/java/org/apache/fop/datatypes/LengthBase.java b/src/java/org/apache/fop/datatypes/LengthBase.java
index 42960b0c1..633643ecb 100644
--- a/src/java/org/apache/fop/datatypes/LengthBase.java
+++ b/src/java/org/apache/fop/datatypes/LengthBase.java
@@ -110,7 +110,9 @@ public class LengthBase implements PercentBase {
         return 1.0;
     }
 
-    /** @see org.apache.fop.datatypes.PercentBase#getBaseLength() */
+    /**
+     * @see org.apache.fop.datatypes.PercentBase#getBaseLength(PercentBaseContext)
+     */
     public int getBaseLength(PercentBaseContext context) throws PropertyException {
         int baseLength = 0;
         if (context != null) {
diff --git a/src/java/org/apache/fop/datatypes/Numeric.java b/src/java/org/apache/fop/datatypes/Numeric.java
index c8b9af75c..92bc3d107 100644
--- a/src/java/org/apache/fop/datatypes/Numeric.java
+++ b/src/java/org/apache/fop/datatypes/Numeric.java
@@ -71,7 +71,7 @@ public interface Numeric {
 
     /**
      * Returns the value of this numeric as an int.
-     * @param conext The context for the length calculation (for percentage based lengths)
+     * @param context the context for the length calculation (for percentage based lengths)
      * @return the value as an integer.
      */
     public int getValue(PercentBaseContext context);
diff --git a/src/java/org/apache/fop/datatypes/SimplePercentBaseContext.java b/src/java/org/apache/fop/datatypes/SimplePercentBaseContext.java
index 1b4bbd8bc..8b0688fe1 100644
--- a/src/java/org/apache/fop/datatypes/SimplePercentBaseContext.java
+++ b/src/java/org/apache/fop/datatypes/SimplePercentBaseContext.java
@@ -44,7 +44,7 @@ public class SimplePercentBaseContext implements PercentBaseContext {
 
     /**
      * Returns the value for the given lengthBase.
-     * @see org.apache.fop.datatypes.PercentBaseContext#getBaseLength(int, fobj)
+     * @see org.apache.fop.datatypes.PercentBaseContext#getBaseLength(int, FObj)
      */
     public int getBaseLength(int lengthBase, FObj fobj) {
         // if its for us return our value otherwise delegate to parent context
diff --git a/src/java/org/apache/fop/fo/expr/NumericProperty.java b/src/java/org/apache/fop/fo/expr/NumericProperty.java
index dd146ce7f..ba0047448 100644
--- a/src/java/org/apache/fop/fo/expr/NumericProperty.java
+++ b/src/java/org/apache/fop/fo/expr/NumericProperty.java
@@ -61,9 +61,7 @@ public class NumericProperty extends Property implements Numeric, Length {
     }
 
     /**
-     * Return the value.
-     * @param Evaluation context
-     * @see Numeric#getNumericValue(Object)
+     * @see Numeric#getNumericValue(PercentBaseContext)
      */
     public double getNumericValue(PercentBaseContext context) {
         return value;
@@ -92,15 +90,14 @@ public class NumericProperty extends Property implements Numeric, Length {
     }
 
     /**
-     * Return the value of this numeric as a length in millipoints. 
+     * @see org.apache.fop.datatypes.Numeric#getValue()
      */
     public int getValue() {
         return (int) value;
     }
 
     /**
-     * Return the value of this numeric as a length in millipoints. 
-     * @param Evaluation context
+     * @see org.apache.fop.datatypes.Numeric#getValue(PercentBaseContext)
      */
     public int getValue(PercentBaseContext context) {
         return (int) value;
diff --git a/src/java/org/apache/fop/fo/expr/RelativeNumericProperty.java b/src/java/org/apache/fop/fo/expr/RelativeNumericProperty.java
index 1d4a921d3..07a2e2440 100755
--- a/src/java/org/apache/fop/fo/expr/RelativeNumericProperty.java
+++ b/src/java/org/apache/fop/fo/expr/RelativeNumericProperty.java
@@ -128,16 +128,14 @@ public class RelativeNumericProperty extends Property implements Numeric, Length
 
     /**
      * Return the resolved (calculated) value of the expression. 
-     * @see Numeric#getNumericValue()
+     * @see org.apache.fop.datatypes.Numeric#getNumericValue()
      */
     public double getNumericValue() throws PropertyException {
         return getResolved(null).getNumericValue(null);
     }
 
     /**
-     * Return the value.
-     * @param Evaluation context
-     * @see Numeric#getNumericValue(Object)
+     * @see org.apache.fop.datatypes.Numeric#getNumericValue(PercentBaseContext)
      */
     public double getNumericValue(PercentBaseContext context) throws PropertyException {
         return getResolved(context).getNumericValue(context);
@@ -174,7 +172,7 @@ public class RelativeNumericProperty extends Property implements Numeric, Length
     }
 
     /**
-     * Return a resolved length.
+     * @see org.apache.fop.datatypes.Numeric#getValue()
      */
     public int getValue() {
         try {
@@ -186,8 +184,7 @@ public class RelativeNumericProperty extends Property implements Numeric, Length
     }
 
     /**
-     * Return the value of this numeric as a length in millipoints. 
-     * @param Evaluation context
+     * @see org.apache.fop.datatypes.Numeric#getValue(PercentBaseContext)
      */
     public int getValue(PercentBaseContext context) {
         try {
@@ -199,7 +196,8 @@ public class RelativeNumericProperty extends Property implements Numeric, Length
     }
 
     /**
-     * Return a string represention of the expression. Only used for debugging. 
+     * Return a string represention of the expression. Only used for debugging.
+     * @return the string representation.
      */
     public String toString() {
         switch (operation) {
diff --git a/src/java/org/apache/fop/fo/pagination/Root.java b/src/java/org/apache/fop/fo/pagination/Root.java
index 4d27222de..cbd87c43f 100644
--- a/src/java/org/apache/fop/fo/pagination/Root.java
+++ b/src/java/org/apache/fop/fo/pagination/Root.java
@@ -236,7 +236,7 @@ public class Root extends FObj {
 
     /**
      * Sets the associated Declarations.
-     * @param Declarations the Declarations to use
+     * @param declarations the Declarations to use
      */
     public void setDeclarations(Declarations declarations) {
         this.declarations = declarations;
diff --git a/src/java/org/apache/fop/fo/properties/BoxPropShorthandParser.java b/src/java/org/apache/fop/fo/properties/BoxPropShorthandParser.java
index 83c4f46a4..9d99c0d11 100644
--- a/src/java/org/apache/fop/fo/properties/BoxPropShorthandParser.java
+++ b/src/java/org/apache/fop/fo/properties/BoxPropShorthandParser.java
@@ -28,7 +28,7 @@ import org.apache.fop.fo.expr.PropertyException;
 public class BoxPropShorthandParser extends GenericShorthandParser {
 
     /**
-     * @see org.apache.fop.fo.GenericShorthandParser#GenericShorthandParser()
+     * Default constructor.
      */
     public BoxPropShorthandParser() {
     }
@@ -38,7 +38,7 @@ public class BoxPropShorthandParser extends GenericShorthandParser {
      * Set the given property based on the number of values set.
      * Example: padding, border-width, border-color, border-style, margin
      * @see org.apache.fop.fo.GenericShorthandParser#convertValueForProperty(
-     * int, ListProperty, PropertyMaker, PropertyList)
+     * int, Property, PropertyMaker, PropertyList)
      */
     protected Property convertValueForProperty(int propId,
                                                Property property,
diff --git a/src/java/org/apache/fop/fo/properties/CharacterProperty.java b/src/java/org/apache/fop/fo/properties/CharacterProperty.java
index d5a912681..bf2e9db00 100644
--- a/src/java/org/apache/fop/fo/properties/CharacterProperty.java
+++ b/src/java/org/apache/fop/fo/properties/CharacterProperty.java
@@ -32,7 +32,7 @@ public class CharacterProperty extends Property {
     public static class Maker extends PropertyMaker {
 
         /**
-         * @param propName name of property for which a Maker should be created
+         * @param propId the id of the property for which a Maker should be created
          */
         public Maker(int propId) {
             super(propId);
diff --git a/src/java/org/apache/fop/fo/properties/ColorTypeProperty.java b/src/java/org/apache/fop/fo/properties/ColorTypeProperty.java
index 99311cc98..6d3fc6b73 100644
--- a/src/java/org/apache/fop/fo/properties/ColorTypeProperty.java
+++ b/src/java/org/apache/fop/fo/properties/ColorTypeProperty.java
@@ -57,7 +57,7 @@ public class ColorTypeProperty extends Property implements ColorType {
     public static class Maker extends PropertyMaker {
 
         /**
-         * @param propName name of property for which a Maker should be created
+         * @param propId the id of the property for which a Maker should be created
          */
         public Maker(int propId) {
             super(propId);
diff --git a/src/java/org/apache/fop/fo/properties/CompoundPropertyMaker.java b/src/java/org/apache/fop/fo/properties/CompoundPropertyMaker.java
index 1f8e57779..7fc2495bf 100644
--- a/src/java/org/apache/fop/fo/properties/CompoundPropertyMaker.java
+++ b/src/java/org/apache/fop/fo/properties/CompoundPropertyMaker.java
@@ -93,7 +93,7 @@ public class CompoundPropertyMaker extends PropertyMaker {
      * of compound property types, such as "space".
      * Overridden by property maker subclasses which handle
      * compound properties.
-     * @param subprop The Constants ID of the component for which a Maker is to
+     * @param subpropId the id of the component for which a Maker is to
      * returned, for example CP_OPTIMUM, if the FO attribute is
      * space.optimum='10pt'.
      * @return the Maker object specified
@@ -139,7 +139,7 @@ public class CompoundPropertyMaker extends PropertyMaker {
      * the default value.
      * @param subpropId  The subproperty id of the property being retrieved.
      *        Is 0 when retriving a base property.
-     * @param propertylist The PropertyList object being built for this FO.
+     * @param propertyList The PropertyList object being built for this FO.
      * @param bTryInherit true if inherited properties should be examined.
      * @param bTryDefault true if the default value should be returned. 
      */
diff --git a/src/java/org/apache/fop/fo/properties/CondLengthProperty.java b/src/java/org/apache/fop/fo/properties/CondLengthProperty.java
index 0253e8a81..a5188f2eb 100644
--- a/src/java/org/apache/fop/fo/properties/CondLengthProperty.java
+++ b/src/java/org/apache/fop/fo/properties/CondLengthProperty.java
@@ -39,7 +39,7 @@ public class CondLengthProperty extends Property implements CompoundDatatype {
     public static class Maker extends CompoundPropertyMaker {
 
         /**
-         * @param name of property for which a Maker should be created
+         * @param propId the id of the property for which a Maker should be created
          */
         public Maker(int propId) {
             super(propId);
diff --git a/src/java/org/apache/fop/fo/properties/EnumLength.java b/src/java/org/apache/fop/fo/properties/EnumLength.java
index 04efebaa6..910335613 100755
--- a/src/java/org/apache/fop/fo/properties/EnumLength.java
+++ b/src/java/org/apache/fop/fo/properties/EnumLength.java
@@ -42,8 +42,7 @@ public class EnumLength extends LengthProperty {
     }
 
     /**
-     * Returns the length in 1/1000ths of a point (millipoints)
-     * @return the length in millipoints
+     * @see org.apache.fop.datatypes.Numeric#getValue()
      */
     public int getValue() {
         log.error("getValue() called on " + enumProperty + " length");
@@ -51,9 +50,7 @@ public class EnumLength extends LengthProperty {
     }
 
     /**
-     * Returns the length in 1/1000ths of a point (millipoints)
-     * @param Evaluation context
-     * @return the length in millipoints
+     * @see org.apache.fop.datatypes.Numeric#getValue(PercentBaseContext)
      */
     public int getValue(PercentBaseContext context) {
         log.error("getValue() called on " + enumProperty + " length");
@@ -61,8 +58,7 @@ public class EnumLength extends LengthProperty {
     }
 
     /**
-     * Returns the value as numeric.
-     * @return the length in millipoints
+     * @see org.apache.fop.datatypes.Numeric#getNumericValue()
      */
     public double getNumericValue() {
         log.error("getNumericValue() called on " + enumProperty + " number");
@@ -70,9 +66,7 @@ public class EnumLength extends LengthProperty {
     }
 
     /**
-     * Returns the value as numeric.
-     * @param context Evaluation context
-     * @return the length in millipoints
+     * @see org.apache.fop.datatypes.Numeric#getNumericValue()
      */
     public double getNumericValue(PercentBaseContext context) {
         log.error("getNumericValue() called on " + enumProperty + " number");
diff --git a/src/java/org/apache/fop/fo/properties/EnumProperty.java b/src/java/org/apache/fop/fo/properties/EnumProperty.java
index 0e1a90bf2..658e52c07 100644
--- a/src/java/org/apache/fop/fo/properties/EnumProperty.java
+++ b/src/java/org/apache/fop/fo/properties/EnumProperty.java
@@ -33,7 +33,7 @@ public class EnumProperty extends Property {
     public static class Maker extends PropertyMaker {
 
         /**
-         * @param propName name of property for which a Maker should be created
+         * @param propId the id of the property for which a Maker should be created
          */
         public Maker(int propId) {
             super(propId);
diff --git a/src/java/org/apache/fop/fo/properties/FixedLength.java b/src/java/org/apache/fop/fo/properties/FixedLength.java
index 347051990..62c7c1c4d 100644
--- a/src/java/org/apache/fop/fo/properties/FixedLength.java
+++ b/src/java/org/apache/fop/fo/properties/FixedLength.java
@@ -58,6 +58,7 @@ public class FixedLength extends LengthProperty {
      * @param unit input unit specifier (in, cm, etc.)
      */
     protected void convert(double dvalue, String unit) {
+        // TODO: the whole routine smells fishy.
 
         int assumedResolution = 1;    // points/pixel
 
@@ -71,6 +72,7 @@ public class FixedLength extends LengthProperty {
             // Do nothing.
             // dvalue = dvalue;
         } else if (unit.equals("mpt")) { //mpt is non-standard!!! mpt=millipoints
+            // TODO: this seems to be wrong.
             // Do nothing.
             // dvalue = dvalue;
         } else if (unit.equals("pc")) {
@@ -80,6 +82,7 @@ public class FixedLength extends LengthProperty {
              * dvalue = dvalue * fontsize;
              */
         } else if (unit.equals("px")) {
+            // TODO: get resolution from user agent?
             dvalue = dvalue * assumedResolution;
         } else {
             dvalue = 0;
@@ -93,36 +96,28 @@ public class FixedLength extends LengthProperty {
     }
 
     /**
-     * Returns the length in 1/1000ths of a point (millipoints)
-     * @return the length in millipoints
+     * @see org.apache.fop.datatypes.Numeric#getValue()
      */
     public int getValue() {
         return millipoints;
     }
 
     /**
-     * Returns the length in 1/1000ths of a point (millipoints)
-     * @param Evaluation context
-     * @return the length in millipoints
+     * @see org.apache.fop.datatypes.Numeric#getValue(PercentBaseContext)
      */
     public int getValue(PercentBaseContext context) {
         return millipoints;
     }
 
     /**
-     * Returns the value as numeric.
-     * @return the length in millipoints
-     * @see Numeric#getNumericValue()
+     * @see org.apache.fop.datatypes.Numeric#getNumericValue()
      */
     public double getNumericValue() {
         return millipoints;
     }
 
     /**
-     * Return the value of this Numeric.
-     * @param context Evaluation context
-     * @return the length in millipoints
-     * @see Numeric#getNumericValue(Object)
+     * @see org.apache.fop.datatypes.Numeric#getNumericValue(PercentBaseContext)
      */
     public double getNumericValue(PercentBaseContext context) {
         return millipoints;
diff --git a/src/java/org/apache/fop/fo/properties/KeepProperty.java b/src/java/org/apache/fop/fo/properties/KeepProperty.java
index e0a92886a..14f0e54a2 100644
--- a/src/java/org/apache/fop/fo/properties/KeepProperty.java
+++ b/src/java/org/apache/fop/fo/properties/KeepProperty.java
@@ -37,7 +37,7 @@ public class KeepProperty extends Property implements CompoundDatatype {
     public static class Maker extends CompoundPropertyMaker {
 
         /**
-         * @param name name of property for which Maker should be created
+         * @param propId the id of the property for which a Maker should be created
          */
         public Maker(int propId) {
             super(propId);
diff --git a/src/java/org/apache/fop/fo/properties/LengthProperty.java b/src/java/org/apache/fop/fo/properties/LengthProperty.java
index 78646d87c..243414605 100644
--- a/src/java/org/apache/fop/fo/properties/LengthProperty.java
+++ b/src/java/org/apache/fop/fo/properties/LengthProperty.java
@@ -37,7 +37,7 @@ abstract public class LengthProperty extends Property
         private boolean autoOk = false;
 
         /**
-         * @param name name of property for which Maker should be created
+         * @param propId the id of the property for which a Maker should be created
          */
         public Maker(int propId) {
             super(propId);
diff --git a/src/java/org/apache/fop/fo/properties/LengthRangeProperty.java b/src/java/org/apache/fop/fo/properties/LengthRangeProperty.java
index 37e40028b..b11d4b806 100644
--- a/src/java/org/apache/fop/fo/properties/LengthRangeProperty.java
+++ b/src/java/org/apache/fop/fo/properties/LengthRangeProperty.java
@@ -43,7 +43,7 @@ public class LengthRangeProperty extends Property implements CompoundDatatype {
     public static class Maker extends CompoundPropertyMaker {
 
         /**
-         * @param name name of property for which to create Maker
+         * @param propId the id of the property for which a Maker should be created
          */
         public Maker(int propId) {
             super(propId);
diff --git a/src/java/org/apache/fop/fo/properties/LineHeightPropertyMaker.java b/src/java/org/apache/fop/fo/properties/LineHeightPropertyMaker.java
index 269b0c2e3..b2194dc97 100644
--- a/src/java/org/apache/fop/fo/properties/LineHeightPropertyMaker.java
+++ b/src/java/org/apache/fop/fo/properties/LineHeightPropertyMaker.java
@@ -24,9 +24,9 @@ import org.apache.fop.fo.expr.PropertyException;
 
 /**
  * A maker which calculates the line-height property.
- * This property maker is special because line-height inherit the specified
+ * This property maker is special because line-height inherits the specified
  * value, instead of the computed value.
- * So when a line-height is create based on a attribute, the specified value
+ * So when a line-height is create based on an attribute, the specified value
  * is stored in the property and in compute() the stored specified value of
  * the nearest specified is used to recalculate the line-height.  
  */
@@ -60,7 +60,7 @@ public class LineHeightPropertyMaker extends SpaceProperty.Maker {
     }
 
     /**
-     * @see SpaceProperty#convertProperty(Property, PropertyList, FObj)
+     * @see SpaceProperty.Maker#convertProperty(Property, PropertyList, FObj)
      */
     public Property convertProperty(Property p,
             PropertyList propertyList,
diff --git a/src/java/org/apache/fop/fo/properties/NumberProperty.java b/src/java/org/apache/fop/fo/properties/NumberProperty.java
index 268066c57..c3f3788e0 100644
--- a/src/java/org/apache/fop/fo/properties/NumberProperty.java
+++ b/src/java/org/apache/fop/fo/properties/NumberProperty.java
@@ -35,7 +35,7 @@ public class NumberProperty extends Property implements Numeric {
 
         /**
          * Constructor for NumberProperty.Maker
-         * @param propName the name of the property
+         * @param propId the id of the property for which a Maker should be created
          */
         public Maker(int propId) {
             super(propId);
@@ -109,7 +109,7 @@ public class NumberProperty extends Property implements Numeric {
      * Return the value of this Numeric.
      * @param context Evaluation context
      * @return The value as a double.
-     * @see Numeric#getNumericValue(Object)
+     * @see Numeric#getNumericValue(PercentBaseContext)
      */
     public double getNumericValue(PercentBaseContext context) {
         return getNumericValue();
@@ -123,7 +123,7 @@ public class NumberProperty extends Property implements Numeric {
      * Return the value
      * @param context Evaluation context
      * @return The value as an int.
-     * @see Numeric#getValue(Object)
+     * @see Numeric#getValue(PercentBaseContext)
      */
     public int getValue(PercentBaseContext context) {
         return getValue();
diff --git a/src/java/org/apache/fop/fo/properties/PercentLength.java b/src/java/org/apache/fop/fo/properties/PercentLength.java
index ccad91d79..b17785c36 100644
--- a/src/java/org/apache/fop/fo/properties/PercentLength.java
+++ b/src/java/org/apache/fop/fo/properties/PercentLength.java
@@ -79,7 +79,6 @@ public class PercentLength extends LengthProperty {
     }
 
     /**
-     * Return the value of this Numeric.
      * @see org.apache.fop.datatypes.Numeric#getNumericValue()
      */
     public double getNumericValue() {
@@ -87,10 +86,7 @@ public class PercentLength extends LengthProperty {
     }
 
     /**
-     * Return the value of this Numeric.
-     * @param context Evaluation context
-     * @return the length in millipoints
-     * @see Numeric#getNumericValue(Object)
+     * @see org.apache.fop.datatypes.Numeric#getNumericValue(PercentBaseContext)
      */
     public double getNumericValue(PercentBaseContext context) {
         try {
@@ -111,8 +107,7 @@ public class PercentLength extends LengthProperty {
     }
 
     /**
-     * Return the value of this numeric as a length in millipoints. 
-     * @param Evaluation context
+     * @see org.apache.fop.datatypes.Numeric#getValue(PercentBaseContext)
      */
     public int getValue(PercentBaseContext context) {
         return (int) getNumericValue(context);
diff --git a/src/java/org/apache/fop/fo/properties/PropertyMaker.java b/src/java/org/apache/fop/fo/properties/PropertyMaker.java
index 6f0d86bfb..a719d5881 100644
--- a/src/java/org/apache/fop/fo/properties/PropertyMaker.java
+++ b/src/java/org/apache/fop/fo/properties/PropertyMaker.java
@@ -163,7 +163,7 @@ public class PropertyMaker implements Cloneable {
 
     /**
      * Set the shorthand datatype parser.
-     * @param subproperty
+     * @param parser the shorthand parser
      */
     public void setDatatypeParser(ShorthandParser parser) {
         datatypeParser = parser;
@@ -197,11 +197,11 @@ public class PropertyMaker implements Cloneable {
     }
 
     /**
-     * Set the byShorthand flag which only is applicable for subproperty 
+     * Set the setByShorthand flag which only is applicable for subproperty 
      * makers. It should be true for the subproperties which must be 
      * assigned a value when the base property is assigned a attribute 
      * value directly.
-     * @param defaultValue
+     * @param setByShorthand
      */
     public void setByShorthand(boolean setByShorthand) {
         this.setByShorthand = setByShorthand;
@@ -273,7 +273,7 @@ public class PropertyMaker implements Cloneable {
      * the default value.
      * @param subpropId  The subproperty id of the property being retrieved.
      *        Is 0 when retriving a base property.
-     * @param propertylist The PropertyList object being built for this FO.
+     * @param propertyList The PropertyList object being built for this FO.
      * @param bTryInherit true if inherited properties should be examined.
      * @param bTryDefault true if the default value should be returned. 
      */
@@ -319,7 +319,7 @@ public class PropertyMaker implements Cloneable {
      * property.
      * @param p A property value for a compound property type such as
      * SpaceProperty.
-     * @param subprop The Constants ID of the component whose value is to be
+     * @param subpropId the id of the component whose value is to be
      * returned.
      * NOTE: this is only to ease porting when calls are made to
      * PropertyList.get() using a component name of a compound property,
@@ -503,8 +503,8 @@ public class PropertyMaker implements Cloneable {
      * initializers "thin", "medium", or "thick". The FOPropertyMapping
      * file specifies a length value equivalent for these keywords,
      * such as "0.5pt" for "thin".
-     * @param value The string value of property attribute.
-     * @return A String containging a parseable equivalent or null if
+     * @param keyword the string value of property attribute.
+     * @return a String containing a parseable equivalent or null if
      * the passed value isn't a keyword initializer for this Property.
      */
     protected String checkValueKeywords(String keyword) {
@@ -514,6 +514,7 @@ public class PropertyMaker implements Cloneable {
                 return value;
             }
         }
+        // TODO: should return null here?
         return keyword;            
     }
 
diff --git a/src/java/org/apache/fop/fo/properties/SpaceProperty.java b/src/java/org/apache/fop/fo/properties/SpaceProperty.java
index 45dce11a9..3d667c0f0 100644
--- a/src/java/org/apache/fop/fo/properties/SpaceProperty.java
+++ b/src/java/org/apache/fop/fo/properties/SpaceProperty.java
@@ -38,7 +38,7 @@ public class SpaceProperty extends LengthRangeProperty {
     public static class Maker extends CompoundPropertyMaker {
 
         /**
-         * @param name name of the property whose Maker is to be created
+         * @param propId the id of the property for which a Maker should be created
          */
         public Maker(int propId) {
             super(propId);
diff --git a/src/java/org/apache/fop/fo/properties/StringProperty.java b/src/java/org/apache/fop/fo/properties/StringProperty.java
index 9da2ea4b8..04e673e17 100644
--- a/src/java/org/apache/fop/fo/properties/StringProperty.java
+++ b/src/java/org/apache/fop/fo/properties/StringProperty.java
@@ -33,7 +33,7 @@ public class StringProperty extends Property {
     public static class Maker extends PropertyMaker {
 
         /**
-         * @param propName name of property for which to create a Maker
+         * @param propId the id of the property for which a Maker should be created
          */
         public Maker(int propId) {
             super(propId);
diff --git a/src/java/org/apache/fop/fo/properties/TableColLength.java b/src/java/org/apache/fop/fo/properties/TableColLength.java
index a8cb201d3..554501c73 100644
--- a/src/java/org/apache/fop/fo/properties/TableColLength.java
+++ b/src/java/org/apache/fop/fo/properties/TableColLength.java
@@ -78,10 +78,7 @@ public class TableColLength extends LengthProperty {
     }
 
     /**
-     * Return the value of this Numeric.
-     * @param context Evaluation context
-     * @return the value
-     * @see Numeric#getNumericValue(Object)
+     * @see org.apache.fop.datatypes.Numeric#getNumericValue(PercentBaseContext)
      */
     public double getNumericValue(PercentBaseContext context) {
         return getNumericValue();
@@ -96,9 +93,7 @@ public class TableColLength extends LengthProperty {
     }
 
     /**
-     * Returns the length in 1/1000ths of a point (millipoints)
-     * @param Evaluation context
-     * @return the length in millipoints
+     * @see org.apache.fop.datatypes.Numeric#getValue(PercentBaseContext)
      */
     public int getValue(PercentBaseContext context) {
         return getValue();
diff --git a/src/java/org/apache/fop/fonts/FontSetup.java b/src/java/org/apache/fop/fonts/FontSetup.java
index 93942f63f..29f9aaea9 100644
--- a/src/java/org/apache/fop/fonts/FontSetup.java
+++ b/src/java/org/apache/fop/fonts/FontSetup.java
@@ -164,10 +164,9 @@ public class FontSetup {
     }
 
     /**
-     * Add fonts from configuration file starting with
-     * internalnames F<num>
+     * Add fonts from configuration file starting with internal name F<num>.
      * @param fontInfo the font info object to set up
-     * @param fontInfos ???
+     * @param fontInfoList
      * @param num starting index for internal font numbering
      */
     public static void addConfiguredFonts(FontInfo fontInfo, List fontInfoList, int num) {
diff --git a/src/java/org/apache/fop/layoutmgr/BlockStackingLayoutManager.java b/src/java/org/apache/fop/layoutmgr/BlockStackingLayoutManager.java
index f6a327171..b01e9d075 100644
--- a/src/java/org/apache/fop/layoutmgr/BlockStackingLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/BlockStackingLayoutManager.java
@@ -82,7 +82,7 @@ public abstract class BlockStackingLayoutManager extends AbstractLayoutManager
     private int contentAreaIPD = 0;
     
     /**
-     * @param the fo this LM deals with
+     * @param node the fo this LM deals with
      */
     public BlockStackingLayoutManager(FObj node) {
         super(node);
diff --git a/src/java/org/apache/fop/layoutmgr/KnuthElement.java b/src/java/org/apache/fop/layoutmgr/KnuthElement.java
index 74db99634..cef81aaab 100644
--- a/src/java/org/apache/fop/layoutmgr/KnuthElement.java
+++ b/src/java/org/apache/fop/layoutmgr/KnuthElement.java
@@ -38,7 +38,6 @@ public abstract class KnuthElement {
      * Create a new KnuthElement.
      * This class being abstract, this can be called only by subclasses.
      *
-     * @param t    the type of this element (one of the KNUTH_* constants)
      * @param w    the width of this element
      * @param pos  the Position stored in this element
      * @param bAux is this an auxiliary element?
diff --git a/src/java/org/apache/fop/layoutmgr/inline/AbstractGraphicsLayoutManager.java b/src/java/org/apache/fop/layoutmgr/inline/AbstractGraphicsLayoutManager.java
index ec36508f2..7bf854715 100644
--- a/src/java/org/apache/fop/layoutmgr/inline/AbstractGraphicsLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/inline/AbstractGraphicsLayoutManager.java
@@ -44,7 +44,6 @@ public abstract class AbstractGraphicsLayoutManager extends LeafNodeLayoutManage
     /**
      * Constructor
      * @param node the formatting object that creates this area
-     * @param parent the parent layout manager
      */
     public AbstractGraphicsLayoutManager(AbstractGraphics node) {
         super(node);
@@ -242,7 +241,7 @@ public abstract class AbstractGraphicsLayoutManager extends LeafNodeLayoutManage
      * to take the border/padding into account as well.
      * @param area the inline area to be updated
      * @param context the layout context used for adding the area
-     * @see LeafNodeLayoutManager#offsetArea(InlineArae, LayoutContext)
+     * @see LeafNodeLayoutManager#offsetArea(InlineArea, LayoutContext)
      */
     protected void offsetArea(InlineArea area, LayoutContext context) {
         int bpd = area.getBPD()
diff --git a/src/java/org/apache/fop/layoutmgr/inline/ContentLayoutManager.java b/src/java/org/apache/fop/layoutmgr/inline/ContentLayoutManager.java
index a8decc5de..df0746475 100644
--- a/src/java/org/apache/fop/layoutmgr/inline/ContentLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/inline/ContentLayoutManager.java
@@ -74,7 +74,7 @@ public class ContentLayoutManager extends AbstractBaseLayoutManager
         this.parentLM = pslm;
         holder = new LineArea();
 
-        setUserAgent(foTitle.getUserAgent());
+        //        setUserAgent(foTitle.getUserAgent());
 
         // use special layout manager to add the inline areas
         // to the Title.
@@ -186,18 +186,20 @@ public class ContentLayoutManager extends AbstractBaseLayoutManager
      *
      * @param ua the user agent
      */
-    public void setUserAgent(FOUserAgent ua) {
-        userAgent = ua;
-    }
+//     public void setUserAgent(FOUserAgent ua) {
+//         userAgent = ua;
+//     }
 
     /**
      * @see org.apache.fop.layoutmgr.LayoutManager#getUserAgent()
      */
-    public FOUserAgent getUserAgent() {
-        return userAgent;
-    }
+//     public FOUserAgent getUserAgent() {
+//         return userAgent;
+//     }
 
-    /** @see org.apache.fop.layoutmgr.LayoutManager */
+    /**
+     * @see org.apache.fop.layoutmgr.LayoutManager#setParent(LayoutManager)
+     */
     public void setParent(LayoutManager lm) {
         parentLM = lm;
     }
@@ -206,30 +208,36 @@ public class ContentLayoutManager extends AbstractBaseLayoutManager
         return this.parentLM;
     }
 
-    /** @see org.apache.fop.layoutmgr.LayoutManager */
+    /**
+     * @see org.apache.fop.layoutmgr.LayoutManager#isFinished()
+     */
     public boolean isFinished() {
         return false;
     }
 
-    /** @see org.apache.fop.layoutmgr.LayoutManager */
+    /**
+     * @see org.apache.fop.layoutmgr.LayoutManager#setFinished(boolean)
+     */
     public void setFinished(boolean isFinished) {
         //to be done
     }
 
-    /** @see org.apache.fop.layoutmgr.LayoutManager */
+    /**
+     * @see org.apache.fop.layoutmgr.LayoutManager#resetPosition(Position)
+     */
     public void resetPosition(Position position) {
         //to be done
     }
 
     /**
-     * @see org.apache.fop.layoutmgr.LayoutManager#createNextChildLMs
+     * @see org.apache.fop.layoutmgr.LayoutManager#createNextChildLMs(int)
      */
     public boolean createNextChildLMs(int pos) {
         return false;
     }
 
     /**
-     * @see org.apache.fop.layoutmgr.LayoutManager#getChildLMs
+     * @see org.apache.fop.layoutmgr.LayoutManager#getChildLMs()
      */
     public List getChildLMs() {
         List childLMs = new ArrayList(1);
diff --git a/src/java/org/apache/fop/layoutmgr/inline/InlineLayoutManager.java b/src/java/org/apache/fop/layoutmgr/inline/InlineLayoutManager.java
index 3463e3883..72bab19ff 100755
--- a/src/java/org/apache/fop/layoutmgr/inline/InlineLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/inline/InlineLayoutManager.java
@@ -117,7 +117,7 @@ public class InlineLayoutManager extends InlineStackingLayoutManager
         return inlineProps.spaceEnd;
     }
     
-    /** @see org.apache.fop.layoutmgr.inline.InlineStackingLayoutManager#createArea() */
+    /** @see org.apache.fop.layoutmgr.inline.InlineLayoutManager#createArea(boolean) */
     protected InlineArea createArea(boolean bInlineParent) {
         InlineArea area;
         if (bInlineParent) {
diff --git a/src/java/org/apache/fop/layoutmgr/inline/TextLayoutManager.java b/src/java/org/apache/fop/layoutmgr/inline/TextLayoutManager.java
index 0e3667798..50fc89f84 100644
--- a/src/java/org/apache/fop/layoutmgr/inline/TextLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/inline/TextLayoutManager.java
@@ -380,8 +380,9 @@ public class TextLayoutManager extends LeafNodeLayoutManager {
      * @param str the string for the TextArea
      * @param width the MinOptMax width of the content
      * @param adjust the total ipd adjustment with respect to the optimal width
-     * @param base the baseline position
-     * @return the new word area
+     * @param context the layout context
+     * @param spaceDiff unused
+     * @return the new text area
      */
     protected TextArea createTextArea(String str, MinOptMax width, int adjust,
                                       LayoutContext context, int spaceDiff) {
diff --git a/src/java/org/apache/fop/layoutmgr/list/ListBlockLayoutManager.java b/src/java/org/apache/fop/layoutmgr/list/ListBlockLayoutManager.java
index f21275acf..db157f4cf 100644
--- a/src/java/org/apache/fop/layoutmgr/list/ListBlockLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/list/ListBlockLayoutManager.java
@@ -73,7 +73,6 @@ public class ListBlockLayoutManager extends BlockStackingLayoutManager {
     /**
      * Create a new list block layout manager.
      * @param node list-block to create the layout manager for
-     * @param parent the parent layout manager
      */
     public ListBlockLayoutManager(ListBlock node) {
         super(node);
diff --git a/src/java/org/apache/fop/layoutmgr/table/CollapsingBorderModel.java b/src/java/org/apache/fop/layoutmgr/table/CollapsingBorderModel.java
index c64bfc1b4..9cbbb3d8b 100644
--- a/src/java/org/apache/fop/layoutmgr/table/CollapsingBorderModel.java
+++ b/src/java/org/apache/fop/layoutmgr/table/CollapsingBorderModel.java
@@ -48,12 +48,13 @@ public abstract class CollapsingBorderModel {
     //public static final int FIRST_ROW_IN_GROUP      = 4;
     /** Indicates that the cell is/end in the last row of a body/table-header/table-footer */
     //public static final int LAST_ROW_IN_GROUP       = 8;
-    
+
+    // TODO: this is not MT safe. Must be removed.
     private static CollapsingBorderModel collapse = null;
     private static CollapsingBorderModel collapseWithPrecedence = null;
     
     /**
-     * @param cellLM the cell
+     * @param borderCollapse border collapse control
      * @return the border model for the cell
      */
     public static CollapsingBorderModel getBorderModelFor(int borderCollapse) {
diff --git a/src/java/org/apache/fop/layoutmgr/table/TableContentLayoutManager.java b/src/java/org/apache/fop/layoutmgr/table/TableContentLayoutManager.java
index 529ec8e41..bb4112483 100644
--- a/src/java/org/apache/fop/layoutmgr/table/TableContentLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/table/TableContentLayoutManager.java
@@ -1135,7 +1135,7 @@ public class TableContentLayoutManager implements PercentBaseContext {
     // --------- Property Resolution related functions --------- //
     
     /**
-     * @see org.apache.fop.datatypes.PercentBaseContext#getBaseLength(int, fobj)
+     * @see org.apache.fop.datatypes.PercentBaseContext#getBaseLength(int, FObj)
      */
     public int getBaseLength(int lengthBase, FObj fobj) {
         return tableLM.getBaseLength(lengthBase, fobj);
diff --git a/src/java/org/apache/fop/pdf/PDFEncryptionManager.java b/src/java/org/apache/fop/pdf/PDFEncryptionManager.java
index 42c52c6ea..a2257c310 100644
--- a/src/java/org/apache/fop/pdf/PDFEncryptionManager.java
+++ b/src/java/org/apache/fop/pdf/PDFEncryptionManager.java
@@ -76,7 +76,6 @@ public class PDFEncryptionManager {
      * the necessary cryptographic support is available.
      * @param params the PDF encryption params or null to disable encryption
      * @param pdf the PDF document to setup encryption for
-     * @param log the logger to send warnings to
      */
     public static void setupPDFEncryption(PDFEncryptionParams params, 
                                           PDFDocument pdf) {
diff --git a/src/java/org/apache/fop/render/java2d/Java2DRenderer.java b/src/java/org/apache/fop/render/java2d/Java2DRenderer.java
index 060624384..0230f9e45 100644
--- a/src/java/org/apache/fop/render/java2d/Java2DRenderer.java
+++ b/src/java/org/apache/fop/render/java2d/Java2DRenderer.java
@@ -204,22 +204,31 @@ public abstract class Java2DRenderer extends AbstractRenderer implements Printab
         }
     }
 
-    /** @return The 0-based current page number */
+    /**
+     * @return The 0-based current page number
+     */
     public int getCurrentPageNumber() {
         return currentPageNumber;
     }
 
-    /** @param The 0-based current page number */
+    /**
+     * @param c the 0-based current page number
+     */
     public void setCurrentPageNumber(int c) {
         this.currentPageNumber = c;
     }
 
-    /** @return The 0-based total number of rendered pages  */
+    /**
+     * @return The 0-based total number of rendered pages
+     */
     public int getNumberOfPages() {
             return numberOfPages;
     }
 
-    /** clears the ViewportList, in case the document is reloaded */
+    /**
+     * Clears the ViewportList.
+     * Used if the document is reloaded.
+     */
     public void clearViewportList() {
         pageViewportList.clear();
         setCurrentPageNumber(0);
@@ -238,7 +247,8 @@ public abstract class Java2DRenderer extends AbstractRenderer implements Printab
      */
     public void renderPage(PageViewport pageViewport) 
                 throws IOException, FOPException {
-        pageViewportList.add(pageViewport.clone()); // FIXME clone
+        // TODO clone
+        pageViewportList.add(pageViewport.clone());
         currentPageNumber++;
     }
 
@@ -547,7 +557,7 @@ public abstract class Java2DRenderer extends AbstractRenderer implements Printab
      * Draw the background and borders. This draws the background and border
      * traits for an area given the position.
      *
-     * @param block the area to get the traits from
+     * @param area the area whose traits are used
      * @param startx the start x position
      * @param starty the start y position
      * @param width the width of the area
diff --git a/src/java/org/apache/fop/svg/SVGUserAgent.java b/src/java/org/apache/fop/svg/SVGUserAgent.java
index ecaf4cc64..6905a7cc1 100644
--- a/src/java/org/apache/fop/svg/SVGUserAgent.java
+++ b/src/java/org/apache/fop/svg/SVGUserAgent.java
@@ -46,9 +46,8 @@ public class SVGUserAgent extends UserAgentAdapter {
 
     /**
      * Creates a new SVGUserAgent.
-     * @param log an Commons logging instance
-     * @param pixelUnitToMM The pixel to millimeter conversion factor 
-     *                  currently in effect
+     * @param pixelUnitToMM the pixel to millimeter conversion factor
+     * currently in effect
      * @param at the current transform
      */
     public SVGUserAgent(float pixelUnitToMM, AffineTransform at) {
diff --git a/src/java/org/apache/fop/tools/anttasks/FileCompare.java b/src/java/org/apache/fop/tools/anttasks/FileCompare.java
index 175cb6f0a..53cdf555b 100644
--- a/src/java/org/apache/fop/tools/anttasks/FileCompare.java
+++ b/src/java/org/apache/fop/tools/anttasks/FileCompare.java
@@ -80,14 +80,16 @@ public class FileCompare {
 
     /**
      * Compares two files to see if they are equal
-     * @param true if files are same, false otherwise
+     * @param f1 first file to compare
+     * @param f2 second file to compare
+     * @return true if files are same, false otherwise
      */
     public static boolean compareFiles(File f1, File f2) throws IOException {
         return (compareFileSize(f1, f2) && compareBytes(f1, f2));
     }
 
     /**
-     * Does a byte compare of two files
+     * Compare the contents of two files.
      * @param true if files are same byte-by-byte, false otherwise
      */
     private static boolean compareBytes(File file1, File file2) throws IOException {
diff --git a/src/java/org/apache/fop/traits/MinOptMax.java b/src/java/org/apache/fop/traits/MinOptMax.java
index 7f61a1297..ad3259ea7 100644
--- a/src/java/org/apache/fop/traits/MinOptMax.java
+++ b/src/java/org/apache/fop/traits/MinOptMax.java
@@ -55,17 +55,16 @@ public class MinOptMax implements java.io.Serializable, Cloneable {
      * @param max the maximum value
      */
     public MinOptMax(int min, int opt, int max) {
+        // TODO: assert min<=opt<=max
         this.min = min;
         this.opt = opt;
         this.max = max;
     }
 
     /**
-     * New min/opt/max with the three values.
+     * Copy constructor.
      *
-     * @param min the minimum value
-     * @param opt the optimum value
-     * @param max the maximum value
+     * @param op the MinOptMax object to copy
      */
     public MinOptMax(MinOptMax op) {
         this.min = op.min;
@@ -73,6 +72,7 @@ public class MinOptMax implements java.io.Serializable, Cloneable {
         this.max = op.max;
     }
 
+    // TODO: remove this.
     /**
      * @see java.lang.Object#clone()
      */
@@ -114,6 +114,7 @@ public class MinOptMax implements java.io.Serializable, Cloneable {
      * @return MinOptMax new instance
      */
     public static MinOptMax multiply(MinOptMax op1, double mult) {
+        // TODO: assert mult>0
         return new MinOptMax((int)(op1.min * mult),
                              (int)(op1.opt * mult), (int)(op1.max * mult));
     }
@@ -129,18 +130,21 @@ public class MinOptMax implements java.io.Serializable, Cloneable {
     }
 
     /**
-     * Adds another MinOptMax instance to this one.
-     * @param op the other instance
+     * Adds min, opt and max to their counterpart components.
+     * @param min the value to add to the minimum value
+     * @param opt the value to add to the optimum value
+     * @param max the value to add to the maximum value
      */
     public void add(int min, int opt, int max) {
         this.min += min;
         this.opt += opt;
         this.max += max;
+        // TODO: assert min<=opt<=max
     }
 
     /**
-     * Adds another MinOptMax instance to this one.
-     * @param op the other instance
+     * Adds a length to all components.
+     * @param len the length to add
      */
     public void add(int len) {
         this.min += len;
@@ -150,7 +154,7 @@ public class MinOptMax implements java.io.Serializable, Cloneable {
 
 
     /**
-     * Subtracts from this instance using another.
+     * Subtracts another MinOptMax instance from this one.
      * @param op the other instance
      */
     public void subtract(MinOptMax op) {
-- 
2.39.5