Comments added

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

src/java/org/apache/fop/layoutmgr/KnuthBox.java

@@ -18,11 +18,34 @@
 
 package org.apache.fop.layoutmgr;
 
+/**
+ * An instance of this class represents an unbreakable piece of content with
+ * fixed width: for example an image, a syllable (but only if letter spacing
+ * is constant), ...
+ * 
+ * A KnuthBox is never a feasible breaking point.
+ * 
+ * The represented piece of content is never suppressed.
+ * 
+ * Besides the inherited methods and attributes, this class has some more
+ * attributes to store information about the content height and its vertical
+ * positioning, and the methods used to get them.
+ */
 public class KnuthBox extends KnuthElement {
     private int lead;
     private int total;
     private int middle;
 
+    /**
+     * Create a new KnuthBox.
+     *
+     * @param w    the width of this box
+     * @param l    the height of this box above the main baseline
+     * @param t    the total height of this box
+     * @param m    the height of this box above and below the middle baseline
+     * @param pos  the Position stored in this box
+     * @param bAux is this box auxiliary?
+     */
     public KnuthBox(int w, int l, int t, int m, Position pos, boolean bAux) {
         super(KNUTH_BOX, w, pos, bAux);
         lead = l;
@@ -30,15 +53,24 @@ public class KnuthBox extends KnuthElement {
         middle = m;
     }
 
+    /**
+     * Return the height of this box above the main baseline.
+     */
     public int getLead() {
         return lead;
     }
 
+    /**
+     * Return the total height of this box.
+     */
     public int getTotal() {
         return total;
     }
 
+    /**
+     * Return the height of this box above and below the middle baseline.
+     */
     public int getMiddle() {
         return middle;
     }
-}
+}

src/java/org/apache/fop/layoutmgr/KnuthElement.java

@@ -18,6 +18,14 @@
 
 package org.apache.fop.layoutmgr;
 
+/**
+ * This is the super class for KnuthBox, KnuthGlue and KnuthPenalty.
+ * 
+ * It stores information common to all sub classes, and the methods to get it:
+ * the width, a Position and a boolean marking KnuthElements used for some
+ * special feature (for example, the additional elements used to represent
+ * a space when text alignment is right, left or center).
+ */
 public abstract class KnuthElement {
 
     public static final int KNUTH_BOX = 0;
@@ -31,6 +39,15 @@ public abstract class KnuthElement {
     private Position position;
     private boolean bIsAuxiliary;
 
+    /**
+     * 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?
+     */
     protected KnuthElement(int t, int w, Position pos, boolean bAux) {
         type = t;
         width = w;
@@ -38,34 +55,58 @@ public abstract class KnuthElement {
         bIsAuxiliary = bAux;
     }
 
+    /**
+     * Return true if this element is a KnuthBox.
+     */
     public boolean isBox() {
         return (type == KNUTH_BOX);
     }
 
+    /**
+     * Return true if this element is a KnuthGlue.
+     */
     public boolean isGlue() {
         return (type == KNUTH_GLUE);
     }
 
+    /**
+     * Return true if this element is a KnuthPenalty.
+     */
     public boolean isPenalty() {
         return (type == KNUTH_PENALTY);
     }
 
+    /**
+     * Return true if this element is an auxiliary one.
+     */
     public boolean isAuxiliary() {
         return bIsAuxiliary;
     }
 
+    /**
+     * Return the width of this element.
+     */
     public int getW() {
         return width;
     }
 
+    /**
+     * Return the Position stored in this element.
+     */
     public Position getPosition() {
         return position;
     }
 
+    /**
+     * Change the Position stored in this element.
+     */
     public void setPosition(Position pos) {
         position = pos;
     }
 
+    /**
+     * Return the LayoutManager responsible for this element.
+     */
     public LayoutManager getLayoutManager() {
         if (position != null) {
             return position.getLM();
@@ -73,4 +114,4 @@ public abstract class KnuthElement {
             return null;
         }
     }
-}
+}

src/java/org/apache/fop/layoutmgr/KnuthGlue.java

@@ -18,21 +18,62 @@
 
 package org.apache.fop.layoutmgr;
 
+/**
+ * An instance of this class represents a piece of content with adjustable 
+ * width: for example a space between words of justified text.
+ * 
+ * A KnuthGlue is a feasible breaking point only if it immediately follows
+ * a KnuthBox.
+ * 
+ * The represented piece of content is suppressed if either the KnuthGlue
+ * is a chosen breaking point or there isn't any KnuthBox between the
+ * previous breaking point and the KnuthGlue itself.
+ * 
+ * So, an unsuppressible piece of content with adjustable width, for example
+ * a leader or a word with adjustable letter space, cannot be represented
+ * by a single KnuthGlue; it can be represented using the sequence:
+ *   KnuthBox(width = 0)
+ *   KnuthPenalty(width = 0, penalty = infinity)
+ *   KnuthGlue(...)
+ *   KnuthBox(width = 0)
+ * where the infinity penalty avoids choosing the KnuthGlue as a breaking point
+ * and the 0-width KnuthBoxes prevent suppression.
+ * 
+ * Besides the inherited methods and attributes, this class has two attributes
+ * used to store the stretchability (difference between max and opt width) and
+ * the shrinkability (difference between opt and min width), and the methods
+ * to get these values.
+ */
 public class KnuthGlue extends KnuthElement {
     private int stretchability;
     private int shrinkability;
 
+    /**
+     * Create a new KnuthGlue.
+     *
+     * @param w the width of this glue
+     * @param y the stretchability of this glue
+     * @param z the shrinkability of this glue
+     * @param pos the Position stored in this glue
+     * @param bAux is this glue auxiliary?
+     */
     public KnuthGlue(int w, int y, int z, Position pos, boolean bAux) {
         super(KNUTH_GLUE, w, pos, bAux);
         stretchability = y;
         shrinkability = z;
     }
 
+    /**
+     * Return the stretchability of this glue.
+     */
     public int getY() {
         return stretchability;
     }
 
+    /**
+     * Return the shrinkability of this glue.
+     */
     public int getZ() {
         return shrinkability;
     }
-}
+}

src/java/org/apache/fop/layoutmgr/KnuthPenalty.java

@@ -18,21 +18,54 @@
 
 package org.apache.fop.layoutmgr;
 
+/**
+ * An instance of this class represents information about a feasible
+ * breaking point; it does not represent any piece of content.
+ * 
+ * A KnuthPenalty is a feasible breaking point unless its value is infinity;
+ * a KnuthPenalty whose value is -infinity represents a forced break.
+ * 
+ * A KnuthPenalty is suppressed, and its width is ignored, if it is not a
+ * chosen breaking point; for example, a KnuthPenalty representing a
+ * hyphenation point has a width (the "-" width), which must be ignored if
+ * that point is not chosen as a breaking point.
+ * 
+ * Besides the inherited methods and attributes, this class has two more
+ * attributes and the methods used to get them: the penalty value, which is
+ * a kind of "aesthetic cost" (the higher the value, the more unsightly the
+ * breaking point), and a boolean that marks KnuthPenalties which should not
+ * be chosen as breaking points for consecutive lines.
+ */
 public class KnuthPenalty extends KnuthElement {
     private int penalty;
     private boolean bFlagged; 
 
+    /**
+     * Create a new KnuthPenalty.
+     *
+     * @param w the width of this penalty
+     * @param p the penalty value of this penalty
+     * @param f is this penalty flagged?
+     * @param pos the Position stored in this penalty
+     * @param bAux is this penalty auxiliary?
+     */
     public KnuthPenalty(int w, int p, boolean f, Position pos, boolean bAux) {
         super(KNUTH_PENALTY, w, pos, bAux);
         penalty = p;
         bFlagged = f;
     }
 
+    /**
+     * Return the penalty value of this penalty.
+     */
     public int getP() {
         return penalty;
     }
 
+    /**
+     * Return true is this penalty is a flagged one.
+     */
     public boolean isFlagged() {
         return bFlagged;
     }
-}
+}