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

21 files changed, 52 insertions, 77 deletions

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();