Merged revisions 651853,651855-651856,651866-651867,651880,651898 via svnmerge from

https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk

........
  r651853 | adelmelle | 2008-04-26 21:06:04 +0100 (Sat, 26 Apr 2008) | 3 lines
  
  Bugzilla 44203:
  Fixed a logic error in Hyphenator.java where an UnsupportedOperationException was erroneously thrown if the supplied source had an associated InputStream.
........
  r651855 | adelmelle | 2008-04-26 21:19:59 +0100 (Sat, 26 Apr 2008) | 3 lines
  
  Basic activation of keep-* properties on Character and AbstractGraphics
  + javadoc updates
........
  r651856 | adelmelle | 2008-04-26 21:21:44 +0100 (Sat, 26 Apr 2008) | 3 lines
  
  Basic activation on some widely used properties (prepare for implementation)
  + javadoc updates
........
  r651866 | adelmelle | 2008-04-26 23:08:10 +0100 (Sat, 26 Apr 2008) | 2 lines
  
  Javadoc updates: attempt at improving interactivity and consistency
........
  r651867 | adelmelle | 2008-04-27 00:07:51 +0100 (Sun, 27 Apr 2008) | 2 lines
  
  Minor refactoring: consolidate getPSLM().notifyEndOfLayout(fobj.getId()) in AbstractLayoutManager.notifyEndOfLayout()
........
  r651880 | clay | 2008-04-27 04:27:39 +0100 (Sun, 27 Apr 2008) | 1 line
  
  Updated to include dev (0.95beta) release.
........
  r651898 | adelmelle | 2008-04-27 09:18:31 +0100 (Sun, 27 Apr 2008) | 1 line
  
  Correction of r651866
........


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

83 files changed, 1322 insertions, 1223 deletions

diff --git a/src/documentation/content/doap.rdf b/src/documentation/content/doap.rdf
index 1c4253cea..c677ecbc8 100644
--- a/src/documentation/content/doap.rdf
+++ b/src/documentation/content/doap.rdf
@@ -76,13 +76,20 @@
     </asfext:implements>
     <release>
       <Version>
-        <name>Previous release</name>
+        <name>Previous stable release</name>
         <created>2007-01-02</created>
         <revision>0.93</revision>
       </Version>
     </release>
     <release>
       <Version>
+        <name>Previous development release</name>
+        <created>2008-25-08</created>
+        <revision>0.95beta</revision>
+      </Version>
+    </release>
+    <release>
+      <Version>
         <name>Latest stable release</name>
         <created>2007-08-23</created>
         <revision>0.94</revision>
diff --git a/src/java/org/apache/fop/fo/FONode.java b/src/java/org/apache/fop/fo/FONode.java
index 197a2482d..951e4c430 100644
--- a/src/java/org/apache/fop/fo/FONode.java
+++ b/src/java/org/apache/fop/fo/FONode.java
@@ -59,19 +59,21 @@ public abstract class FONode implements Cloneable {
     /** pointer to the sibling nodes */
     protected FONode[] siblings;
 
-    /** 
-     * Marks location of this object from the input FO
-     *   Call locator.getSystemId(), getLineNumber(),
-     *   getColumnNumber() for file, line, column
+    /**
+     * Marks the location of this object from the input FO
+     *   <br>Call <code>locator.getSystemId()</code>,
+     *   <code>getLineNumber()</code>,
+     *   <code>getColumnNumber()</code> for file, line, column
      *   information
      */
     protected Locator locator;
 
     /** Logger for fo-tree related messages **/
     protected static Log log = LogFactory.getLog(FONode.class);
-    
+
     /**
-     * Main constructor.
+     * Base constructor
+     *
      * @param parent parent of this node
      */
     protected FONode(FONode parent) {
@@ -79,8 +81,9 @@ public abstract class FONode implements Cloneable {
     }
 
     /**
-     * Perform a shallow cloning operation,
-     * set its parent, and optionally clean the list of child nodes
+     * Performs a shallow cloning operation, sets the clone's parent,
+     * and optionally cleans the list of child nodes
+     *
      * @param cloneparent the intended parent of the clone
      * @param removeChildren if true, clean the list of child nodes
      * @return the cloned FO node
@@ -88,32 +91,31 @@ public abstract class FONode implements Cloneable {
      */
     public FONode clone(FONode cloneparent, boolean removeChildren)
                 throws FOPException {
-        FONode foNode = (FONode) clone();
-        foNode.parent = cloneparent;
-        foNode.siblings = null;
-        return foNode;
+        try {
+            FONode foNode = (FONode) clone();
+            foNode.parent = cloneparent;
+            foNode.siblings = null;
+            return foNode;
+        } catch (CloneNotSupportedException cnse) {
+            return null;
+        }
     }
 
     /**
      * Perform a shallow cloning operation
-     * 
+     *
      * {@inheritDoc}
-     * @return the cloned object
      */
-    protected Object clone() {
-        try {
-            return super.clone();
-        } catch (CloneNotSupportedException e) {
-            return null;
-        }
+    protected Object clone() throws CloneNotSupportedException {
+        return super.clone();
     }
 
     /**
      * Bind the given <code>PropertyList</code> to this node
-     * Does nothing by default. Subclasses should override this method 
-     * in case they want to use the properties available on the 
+     * Does nothing by default. Subclasses should override this method
+     * in case they want to use the properties available on the
      * <code>PropertyList</code>.
-     * 
+     *
      * @param   propertyList    the <code>PropertyList</code>
      * @throws  FOPException if there was an error when
      *          processing the <code>PropertyList</code>
@@ -121,7 +123,7 @@ public abstract class FONode implements Cloneable {
     public void bind(PropertyList propertyList) throws FOPException {
         //nop
     }
-    
+
     /**
      * Set the location information for this element
      * @param locator the org.xml.sax.Locator object
@@ -134,20 +136,27 @@ public abstract class FONode implements Cloneable {
         }
     }
 
-    /** @return the location information for this element or null, if not available  */
+    /**
+     * Returns the <code>Locator</code> containing the location information for this
+     * element, or <code>null</code> if not available
+     *
+     * @return the location information for this element or <code>null</code>, if not available
+     */
     public Locator getLocator() {
         return this.locator;
     }
-    
+
     /**
-     * Recursively goes up the FOTree hierarchy until the fo:root is found,
-     * which returns the parent FOEventHandler.
+     * Recursively goes up the FOTree hierarchy until the <code>fo:root</code>
+     * is found, which returns the parent <code>FOEventHandler</code>.
+     * <br>(see also: {@link org.apache.fop.fo.pagination.Root#getFOEventHandler()})
+     *
      * @return the FOEventHandler object that is the parent of the FO Tree
      */
     public FOEventHandler getFOEventHandler() {
         return parent.getFOEventHandler();
     }
-    
+
     /**
      * Indicates whether this node is a child of an fo:marker.
      * @return true if this node is a child of an fo:marker
@@ -157,8 +166,10 @@ public abstract class FONode implements Cloneable {
     }
 
     /**
-     * Returns the user agent for the node.
-     * @return FOUserAgent
+     * Returns the user agent that is associated with the
+     * tree's <code>FOEventHandler</code>.
+     *
+     * @return the user agent
      */
     public FOUserAgent getUserAgent() {
         return getFOEventHandler().getUserAgent();
@@ -166,6 +177,7 @@ public abstract class FONode implements Cloneable {
 
     /**
      * Returns the logger for the node.
+     *
      * @return the logger
      */
     public Log getLogger() {
@@ -176,16 +188,17 @@ public abstract class FONode implements Cloneable {
      * Initialize the node with its name, location information, and attributes
      * The attributes must be used immediately as the sax attributes
      * will be altered for the next element.
+     *
      * @param elementName element name (e.g., "fo:block")
      * @param locator Locator object (ignored by default)
      * @param attlist Collection of attributes passed to us from the parser.
      * @param pList the property list of the parent node
      * @throws FOPException for errors or inconsistencies in the attributes
     */
-    public void processNode(String elementName, Locator locator, 
+    public void processNode(String elementName, Locator locator,
             Attributes attlist, PropertyList pList) throws FOPException {
         if (log.isDebugEnabled()) {
-            log.debug("Unhandled element: " + elementName 
+            log.debug("Unhandled element: " + elementName
                     + (locator != null ? " at " + getLocatorString(locator) : ""));
         }
     }
@@ -193,30 +206,36 @@ public abstract class FONode implements Cloneable {
     /**
      * Create a property list for this node. Return null if the node does not
      * need a property list.
-     * @param pList the closest parent propertylist. 
-     * @param foEventHandler The FOEventHandler where the PropertyListMaker 
+     *
+     * @param pList the closest parent propertylist.
+     * @param foEventHandler The FOEventHandler where the PropertyListMaker
      *              instance can be found.
      * @return A new property list.
      * @throws FOPException if there's a problem during processing
      */
-    protected PropertyList createPropertyList(PropertyList pList, FOEventHandler foEventHandler) 
+    protected PropertyList createPropertyList(
+                                PropertyList pList,
+                                FOEventHandler foEventHandler)
                 throws FOPException {
         return null;
     }
 
     /**
      * Checks to make sure, during SAX processing of input document, that the
-     * incoming node is valid for the this (parent) node (e.g., checking to
+     * incoming node is valid for this (parent) node (e.g., checking to
      * see that <code>fo:table</code> is not an immediate child of <code>fo:root</code>)
      * called from {@link FOTreeBuilder#startElement(String, String, String, Attributes)}
      * before constructing the child {@link FObj}.
-     * 
+     *
      * @param loc location in the FO source file
      * @param namespaceURI namespace of incoming node
      * @param localName name of the incoming node (without namespace prefix)
      * @throws ValidationException if incoming node not valid for parent
      */
-    protected void validateChildNode(Locator loc, String namespaceURI, String localName) 
+    protected void validateChildNode(
+                                Locator loc,
+                                String namespaceURI,
+                                String localName)
             throws ValidationException {
         //nop
     }
@@ -224,30 +243,32 @@ public abstract class FONode implements Cloneable {
     /**
      * Static version of {@link FONode#validateChildNode(Locator, String, String)} that
      * can be used by subclasses that need to validate children against a different node
-     * (for example: <code>fo:wrapper</code> needs to check if the incoming node is a 
+     * (for example: <code>fo:wrapper</code> needs to check if the incoming node is a
      *  valid child to its parent)
-     *  
-     * @param fo    the FONode to validate against
+     *
+     * @param fo    the {@link FONode} to validate against
      * @param loc   location in the source file
      * @param namespaceURI  namespace of the incoming node
-     * @param localName     name of the incoming node (without namespace prefix) 
+     * @param localName     name of the incoming node (without namespace prefix)
      * @throws ValidationException if the incoming node is not a valid child for the given FO
      */
     protected static void validateChildNode(
-                                FONode fo, 
-                                Locator loc, 
-                                String namespaceURI, 
-                                String localName) 
+                                FONode fo,
+                                Locator loc,
+                                String namespaceURI,
+                                String localName)
             throws ValidationException {
         fo.validateChildNode(loc, namespaceURI, localName);
     }
-    
+
     /**
-     * Adds characters (does nothing here)
+     * Adds characters. Does nothing by default. To be overridden in subclasses
+     * that allow <code>#PCDATA</code> content.
+     *
      * @param data array of characters containing text to be added
      * @param start starting array element to add
      * @param end ending array element to add
-     * @param pList currently applicable PropertyList 
+     * @param pList currently applicable PropertyList
      * @param locator location in the XSL-FO source file.
      * @throws FOPException if there's a problem during processing
      */
@@ -259,6 +280,7 @@ public abstract class FONode implements Cloneable {
 
     /**
      * Called after processNode() is called. Subclasses can do additional processing.
+     *
      * @throws FOPException if there's a problem during processing
      */
     protected void startOfNode() throws FOPException {
@@ -267,8 +289,9 @@ public abstract class FONode implements Cloneable {
 
     /**
      * Primarily used for making final content model validation checks
-     * and/or informing the FOEventHandler that the end of this FO
+     * and/or informing the {@link FOEventHandler} that the end of this FO
      * has been reached.
+     *
      * @throws FOPException if there's a problem during processing
      */
     protected void endOfNode() throws FOPException {
@@ -278,6 +301,7 @@ public abstract class FONode implements Cloneable {
     /**
      * Adds a node as a child of this node. The default implementation of this method
      * just ignores any child node being added.
+     *
      * @param child child node to be added to the childNodes of this node
      * @throws FOPException if there's a problem during processing
      */
@@ -288,6 +312,7 @@ public abstract class FONode implements Cloneable {
     /**
      * Removes a child node. Used by the child nodes to remove themselves, for
      * example table-body if it has no children.
+     *
      * @param child child node to be removed
      */
     public void removeChild(FONode child) {
@@ -295,6 +320,8 @@ public abstract class FONode implements Cloneable {
     }
 
     /**
+     * Return the parent node of this node
+     *
      * @return the parent node of this node
      */
     public FONode getParent() {
@@ -302,8 +329,9 @@ public abstract class FONode implements Cloneable {
     }
 
     /**
-     * Return an iterator over all the child nodes of this FObj.
-     * @return A ListIterator.
+     * Return an iterator over all the child nodes of this node.
+     *
+     * @return the iterator over the FO's childnodes
      */
     public FONodeIterator getChildNodes() {
         return null;
@@ -312,15 +340,18 @@ public abstract class FONode implements Cloneable {
     /**
      * Return an iterator over the object's child nodes starting
      * at the passed node.
+     *
      * @param childNode First node in the iterator
-     * @return A ListIterator or null if child node isn't a child of
-     * this FObj.
+     * @return the iterator, or <code>null</code> if
+     *  the given node is not a child of this node.
      */
     public FONodeIterator getChildNodes(FONode childNode) {
         return null;
     }
 
     /**
+     * Return a {@link CharIterator} over all characters in this node
+     *
      * @return an iterator for the characters in this node
      */
     public CharIterator charIterator() {
@@ -332,7 +363,7 @@ public abstract class FONode implements Cloneable {
      * name pairs in text messages.
      * For readability, using fo:, fox:, svg:, for those namespaces even
      * though that prefix may not have been chosen in the document.
-     * @param namespaceURI URI of node found 
+     * @param namespaceURI URI of node found
      *         (e.g., "http://www.w3.org/1999/XSL/Format")
      * @param localName local name of node, (e.g., "root" for "fo:root")
      * @return the prefix:localname, if fo/fox/svg, or a longer representation
@@ -359,28 +390,29 @@ public abstract class FONode implements Cloneable {
         return FOValidationEventProducer.Provider.get(
                 getUserAgent().getEventBroadcaster());
     }
-    
+
     /**
      * Helper function to standardize "too many" error exceptions
      * (e.g., two fo:declarations within fo:root)
      * @param loc org.xml.sax.Locator object of the error (*not* parent node)
      * @param nsURI namespace URI of incoming invalid node
-     * @param lName local name (i.e., no prefix) of incoming node 
+     * @param lName local name (i.e., no prefix) of incoming node
      * @throws ValidationException the validation error provoked by the method call
      */
-    protected void tooManyNodesError(Locator loc, String nsURI, String lName) 
+    protected void tooManyNodesError(Locator loc, String nsURI, String lName)
                 throws ValidationException {
         tooManyNodesError(loc, new QName(nsURI, lName));
     }
 
     /**
      * Helper function to standardize "too many" error exceptions
-     * (e.g., two fo:declarations within fo:root)
+     * (e.g., two <code>fo:declarations</code> within <code>fo:root</code>)
+     *
      * @param loc org.xml.sax.Locator object of the error (*not* parent node)
      * @param offendingNode the qualified name of the offending node
      * @throws ValidationException the validation error provoked by the method call
      */
-    protected void tooManyNodesError(Locator loc, QName offendingNode) 
+    protected void tooManyNodesError(Locator loc, QName offendingNode)
                 throws ValidationException {
         getFOValidationEventProducer().tooManyNodes(this, getName(), offendingNode, loc);
     }
@@ -393,24 +425,25 @@ public abstract class FONode implements Cloneable {
      * @param offendingNode incoming node that would cause a duplication.
      * @throws ValidationException the validation error provoked by the method call
      */
-    protected void tooManyNodesError(Locator loc, String offendingNode) 
+    protected void tooManyNodesError(Locator loc, String offendingNode)
                 throws ValidationException {
         tooManyNodesError(loc, new QName(FO_URI, offendingNode));
     }
 
     /**
      * Helper function to standardize "out of order" exceptions
-     * (e.g., fo:layout-master-set appearing after fo:page-sequence)
+     * (e.g., <code>fo:layout-master-set</code> appearing after <code>fo:page-sequence</code>)
+     *
      * @param loc org.xml.sax.Locator object of the error (*not* parent node)
      * @param tooLateNode string name of node that should be earlier in document
      * @param tooEarlyNode string name of node that should be later in document
      * @throws ValidationException the validation error provoked by the method call
      */
-    protected void nodesOutOfOrderError(Locator loc, String tooLateNode, 
+    protected void nodesOutOfOrderError(Locator loc, String tooLateNode,
             String tooEarlyNode) throws ValidationException {
         nodesOutOfOrderError(loc, tooLateNode, tooEarlyNode, false);
     }
-    
+
     /**
      * Helper function to standardize "out of order" exceptions
      * (e.g., fo:layout-master-set appearing after fo:page-sequence)
@@ -420,28 +453,30 @@ public abstract class FONode implements Cloneable {
      * @param canRecover indicates whether FOP can recover from this problem and continue working
      * @throws ValidationException the validation error provoked by the method call
      */
-    protected void nodesOutOfOrderError(Locator loc, String tooLateNode, 
+    protected void nodesOutOfOrderError(Locator loc, String tooLateNode,
             String tooEarlyNode, boolean canRecover) throws ValidationException {
         getFOValidationEventProducer().nodeOutOfOrder(this, getName(),
                 tooLateNode, tooEarlyNode, canRecover, loc);
     }
-    
+
     /**
      * Helper function to return "invalid child" exceptions
-     * (e.g., fo:block appearing immediately under fo:root)
+     * (e.g., <code>fo:block</code> appearing immediately under <code>fo:root</code>)
+     *
      * @param loc org.xml.sax.Locator object of the error (*not* parent node)
      * @param nsURI namespace URI of incoming invalid node
-     * @param lName local name (i.e., no prefix) of incoming node 
+     * @param lName local name (i.e., no prefix) of incoming node
      * @throws ValidationException the validation error provoked by the method call
      */
-    protected void invalidChildError(Locator loc, String nsURI, String lName) 
+    protected void invalidChildError(Locator loc, String nsURI, String lName)
                 throws ValidationException {
         invalidChildError(loc, getName(), nsURI, lName, null);
     }
-    
+
     /**
      * Helper function to return "invalid child" exceptions with more
      * complex validation rules (i.e., needing more explanation of the problem)
+     *
      * @param loc org.xml.sax.Locator object of the error (*not* parent node)
      * @param parentName the name of the parent element
      * @param nsURI namespace URI of incoming invalid node
@@ -458,8 +493,10 @@ public abstract class FONode implements Cloneable {
 
     /**
      * Helper function to throw an error caused by missing mandatory child elements.
-     * E.g., fo:layout-master-set not having any page-master child element.
-     * @param contentModel The XSL Content Model for the fo: object or a similar description 
+     * (e.g., <code>fo:layout-master-set</code> not having any <code>fo:page-master</code>
+     *  child element.
+     *
+     * @param contentModel The XSL Content Model for the fo: object or a similar description
      *                     indicating the necessary child elements.
      * @throws ValidationException the validation error provoked by the method call
      */
@@ -472,7 +509,7 @@ public abstract class FONode implements Cloneable {
     /**
      * Helper function to throw an error caused by missing mandatory child elements.
      * E.g., fo:layout-master-set not having any page-master child element.
-     * @param contentModel The XSL Content Model for the fo: object or a similar description 
+     * @param contentModel The XSL Content Model for the fo: object or a similar description
      *                     indicating the necessary child elements.
      * @param canRecover indicates whether FOP can recover from this problem and continue working
      * @throws ValidationException the validation error provoked by the method call
@@ -485,6 +522,7 @@ public abstract class FONode implements Cloneable {
 
     /**
      * Helper function to throw an error caused by missing mandatory properties
+     *
      * @param propertyName the name of the missing property.
      * @throws ValidationException the validation error provoked by the method call
      */
@@ -496,6 +534,7 @@ public abstract class FONode implements Cloneable {
     /**
      * Helper function to return "Error(line#/column#)" string for
      * above exception messages
+     *
      * @param loc org.xml.sax.Locator object
      * @return String opening error text
      */
@@ -506,15 +545,17 @@ public abstract class FONode implements Cloneable {
     /**
      * Helper function to return "Warning(line#/column#)" string for
      * warning messages
+     *
      * @param loc org.xml.sax.Locator object
      * @return String opening warning text
      */
     protected static String warningText(Locator loc) {
         return "Warning(" + getLocatorString(loc) + "): ";
     }
-    
+
     /**
      * Helper function to format a Locator instance.
+     *
      * @param loc org.xml.sax.Locator object
      * @return String the formatted text
      */
@@ -528,6 +569,7 @@ public abstract class FONode implements Cloneable {
 
     /**
      * Decorates a log or warning message with context information on the given node.
+     *
      * @param text the original message
      * @param node the context node
      * @return the decorated text
@@ -541,7 +583,7 @@ public abstract class FONode implements Cloneable {
             return text;
         }
     }
-    
+
     /**
      * Returns a String containing as much context information as possible about a node. Call
      * this method only in exceptional conditions because this method may perform quite extensive
@@ -573,7 +615,7 @@ public abstract class FONode implements Cloneable {
         }
         return sb.toString();
     }
-    
+
     /**
      * Returns a String containing as some context information about a node. It does not take the
      * locator into consideration and returns null if no useful context information can be found.
@@ -598,7 +640,7 @@ public abstract class FONode implements Cloneable {
             return null;
         }
     }
-    
+
     /** Function for AdvancedMessageFormat to retrieve context info from an FONode. */
     public static class GatherContextInfoFunction implements Function {
 
@@ -621,7 +663,7 @@ public abstract class FONode implements Cloneable {
             return "gatherContextInfo";
         }
     }
-    
+
     /**
      * Gathers context information for the getContextInfo() method.
      * @return the collected context information or null, if none is available
@@ -629,9 +671,10 @@ public abstract class FONode implements Cloneable {
     protected String gatherContextInfo() {
         return null;
     }
-    
+
     /**
      * Returns the root node of this tree
+     *
      * @return the root node
      */
     public Root getRoot() {
@@ -640,6 +683,7 @@ public abstract class FONode implements Cloneable {
 
     /**
      * Returns the fully qualified name of the node
+     *
      * @return the fully qualified name of this node
      */
     public String getName() {
@@ -648,6 +692,7 @@ public abstract class FONode implements Cloneable {
 
     /**
      * Returns the fully qualified name of the node
+     *
      * @param prefix the namespace prefix to build the name with (may be null)
      * @return the fully qualified name of this node
      */
@@ -663,22 +708,32 @@ public abstract class FONode implements Cloneable {
 
     /**
      * Returns the local name (i.e. without namespace prefix) of the node
+     *
      * @return the local name of this node
      */
     public abstract String getLocalName();
 
-    /** @return the normally ussed namespace prefix for this kind of node (ex. "fo" for XSL-FO) */
+    /**
+     * Returns the normally used namespace prefix for this node
+     *
+     * @return the normally used namespace prefix for this kind of node (ex. "fo" for XSL-FO)
+     */
     public abstract String getNormalNamespacePrefix();
-    
-    /** @return the namespace URI for this node */
+
+    /**
+     * Returns the namespace URI for this node
+     *
+     * @return the namespace URI for this node
+     */
     public String getNamespaceURI() {
         return null;
     }
-    
+
     /**
      * Returns the {@link Constants} class integer value of this node
-     * @return the integer enumeration of this FO (e.g. FO_ROOT)
-     *      if a formatting object, FO_UNKNOWN_NODE otherwise
+     *
+     * @return the integer enumeration of this FO (e.g. {@link Constants#FO_ROOT})
+     *      if a formatting object, {@link Constants#FO_UNKNOWN_NODE} otherwise
      */
     public int getNameId() {
         return Constants.FO_UNKNOWN_NODE;
@@ -687,25 +742,31 @@ public abstract class FONode implements Cloneable {
     /**
      * This method is overridden by extension elements and allows the extension element
      * to return a pass-through attachment which the parent formatting objects should simply
-     * carry with them but otherwise ignore. This mechanism is used to pass non-standard 
-     * information from the FO tree through to the layout engine and the renderers. 
+     * carry with them but otherwise ignore. This mechanism is used to pass non-standard
+     * information from the FO tree through to the layout engine and the renderers.
+     *
      * @return the extension attachment if one is created by the extension element, null otherwise.
      */
     public ExtensionAttachment getExtensionAttachment() {
         return null;
     }
-    
+
     /**
      * This method is overridden by extension elements and allows the extension element to return
-     * a ContentHandlerFactory. This factory can create ContentHandler implementations that handle
+     * a {@link ContentHandlerFactory}. This factory can create ContentHandler implementations that handle
      * foreign XML content by either building up a specific DOM, a Java object or something else.
-     * @return the ContentHandlerFactory or null if not applicable
+     *
+     * @return the <code>ContentHandlerFactory</code> or <code>null</code> if not applicable
      */
     public ContentHandlerFactory getContentHandlerFactory() {
         return null;
     }
-    
+
     /**
+     * Returns <code>true</code> if <code>fo:marker</code> is allowed as
+     * a child node.
+     * <br>To be overridden <i>only</i> in extension nodes that need it.
+     *
      * @return true if markers are valid children
      */
     protected boolean canHaveMarkers() {
@@ -735,16 +796,16 @@ public abstract class FONode implements Cloneable {
             return false;
         }
     }
-    
+
     /**
      * This method is used when adding child nodes to a FO that already
      * contains at least one child. In this case, the new child becomes a
      * sibling to the previous one
-     * 
+     *
      * @param precedingSibling  the previous child
      * @param followingSibling  the new child
      */
-    protected static void attachSiblings(FONode precedingSibling, 
+    protected static void attachSiblings(FONode precedingSibling,
                                          FONode followingSibling) {
         if (precedingSibling.siblings == null) {
             precedingSibling.siblings = new FONode[2];
@@ -755,52 +816,54 @@ public abstract class FONode implements Cloneable {
         precedingSibling.siblings[1] = followingSibling;
         followingSibling.siblings[0] = precedingSibling;
     }
-    
+
     /**
      * Base iterator interface over a FO's children
-     *
      */
     public interface FONodeIterator extends ListIterator {
-        
+
         /**
-         * Returns the parent node for this iterator's list 
+         * Returns the parent node for this iterator's list
          * of child nodes
+         *
          * @return  the parent node
          */
         FObj parentNode();
-        
+
         /**
          * Convenience method with return type of FONode
-         * (should be semantically equivalent to
-         * <code>(FONode) next();</code>)
+         * (semantically equivalent to: <code>(FONode) next();</code>)
+         *
          * @return the next node (if any), as a type FONode
          */
         FONode nextNode();
-        
+
         /**
          * Convenience method with return type of FONode
-         * (should be semantically equivalent to
-         * <code>(FONode) previous();</code>)
+         * (semantically equivalent to: <code>(FONode) previous();</code>)
+         *
          * @return the previous node (if any), as a type FONode
          */
         FONode previousNode();
-        
+
         /**
          * Returns the first node in the list, and decreases the index,
-         * so that a subsequent call to hasPrevious() will return false
+         * so that a subsequent call to <code>hasPrevious()</code> will
+         * return <code>false</code>
+         *
          * @return the first node in the list
-         * @throws NoSuchElementException if the list is empty
          */
         FONode firstNode();
-        
+
         /**
          * Returns the last node in the list, and advances the
-         * current position, so that a subsequent call to hasNext()
-         * will return false
+         * current position, so that a subsequent call to <code>hasNext()</code>
+         * will return <code>false</code>
+         *
          * @return the last node in the list
-         * @throws NoSuchElementException if the list is empty
          */
         FONode lastNode();
 
     }
+
 }
diff --git a/src/java/org/apache/fop/fo/FOText.java b/src/java/org/apache/fop/fo/FOText.java
index 99d37dba9..8c85bb039 100644
--- a/src/java/org/apache/fop/fo/FOText.java
+++ b/src/java/org/apache/fop/fo/FOText.java
@@ -114,7 +114,8 @@ public class FOText extends FONode {
     private static final int IS_WORD_CHAR_MAYBE = 2;
 
     /**
-     * Creates a now FO text node.
+     * Creates a new FO text node.
+     *
      * @param parent FONode that is the parent of this object
      */
     public FOText(FONode parent) {
@@ -127,7 +128,7 @@ public class FOText extends FONode {
 
         int length = end - start;
         int calength = 0;
-        char[] nca = null;
+        char[] nca;
         if (ca != null) {
             calength = ca.length;
             nca = new char[calength + length];
@@ -223,6 +224,7 @@ public class FOText extends FONode {
      /**
      * This method is run as part of the ancestor Block's flushText(), to 
      * create xref pointers to the previous FOText objects within the same Block
+     * @param  ancestorBlock the ancestor fo:block
      */
     protected void createBlockPointers(Block ancestorBlock) {
         this.ancestorBlock = ancestorBlock;
@@ -236,7 +238,6 @@ public class FOText extends FONode {
                 prevFOTextThisBlock = null;
             }
         }
-        return;
     }
 
     /**
@@ -410,7 +411,7 @@ public class FOText extends FONode {
      * depending on whether the character should be considered part of a word
      * or not.
      */
-    public static int isWordChar(char inputChar) {
+    private static int isWordChar(char inputChar) {
         switch (Character.getType(inputChar)) {
         case Character.COMBINING_SPACING_MARK:
             return IS_WORD_CHAR_TRUE;
diff --git a/src/java/org/apache/fop/fo/FObj.java b/src/java/org/apache/fop/fo/FObj.java
index a03a351e0..a2b09640b 100644
--- a/src/java/org/apache/fop/fo/FObj.java
+++ b/src/java/org/apache/fop/fo/FObj.java
@@ -39,11 +39,12 @@ import org.apache.fop.fo.properties.PropertyMaker;
 
 /**
  * Base class for representation of formatting objects and their processing.
+ * All standard formatting object classes extend this class.
  */
 public abstract class FObj extends FONode implements Constants {
     
     /** the list of property makers */
-    private static PropertyMaker[] propertyListTable
+    private static final PropertyMaker[] propertyListTable
                             = FOPropertyMapping.getGenericMappings();
     
     /** 
@@ -71,7 +72,6 @@ public abstract class FObj extends FONode implements Constants {
 
     /**
      * Create a new formatting object.
-     * All formatting object classes extend this class.
      *
      * @param parent the parent node
      */
@@ -92,9 +92,7 @@ public abstract class FObj extends FONode implements Constants {
         }
     }
 
-    /**
-     * {@inheritDoc} 
-     */
+    /** {@inheritDoc} */
     public FONode clone(FONode parent, boolean removeChildren)
         throws FOPException {
         FObj fobj = (FObj) super.clone(parent, removeChildren);
@@ -113,9 +111,7 @@ public abstract class FObj extends FONode implements Constants {
         return propertyListTable[propId];
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void processNode(String elementName, Locator locator, 
                             Attributes attlist, PropertyList pList) 
                     throws FOPException {
@@ -182,15 +178,13 @@ public abstract class FObj extends FONode implements Constants {
      * Returns Out Of Line FO Descendant indicator.
      * @return true if Out of Line FO or Out Of Line descendant, false otherwise
      */
-    public boolean getIsOutOfLineFODescendant() {
+    boolean getIsOutOfLineFODescendant() {
         return isOutOfLineFODescendant;
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc}*/
     protected void addChildNode(FONode child) throws FOPException {
-        if (canHaveMarkers() && child.getNameId() == FO_MARKER) {
+        if (child.getNameId() == FO_MARKER) {
             addMarker((Marker) child);
         } else { 
             ExtensionAttachment attachment = child.getExtensionAttachment();
@@ -318,7 +312,7 @@ public abstract class FObj extends FONode implements Constants {
      * any areas (see addMarker()).
      * @param node the node that was removed
      */
-    protected void notifyChildRemoval(FONode node) {
+    void notifyChildRemoval(FONode node) {
         //nop
     }
     
@@ -464,7 +458,7 @@ public abstract class FObj extends FONode implements Constants {
                         || lName.equals("page-number-citation-last")
                         || lName.equals("basic-link")
                         || (lName.equals("multi-toggle")
-                                && (getNameId() == FO_MULTI_CASE 
+                                && (getNameId() == FO_MULTI_CASE
                                         || findAncestor(FO_MULTI_CASE) > 0))
                         || (lName.equals("footnote") 
                                 && !isOutOfLineFODescendant)
@@ -491,7 +485,7 @@ public abstract class FObj extends FONode implements Constants {
      * @param lName local name (i.e., no prefix) of incoming node 
      * @return true if a member, false if not
      */
-    protected boolean isNeutralItem(String nsURI, String lName) {
+    boolean isNeutralItem(String nsURI, String lName) {
         return (FO_URI.equals(nsURI) 
                 && (lName.equals("multi-switch") 
                         || lName.equals("multi-properties")
@@ -546,7 +540,7 @@ public abstract class FObj extends FONode implements Constants {
      * 
      * @param attachment the attachment to add.
      */
-    public void addExtensionAttachment(ExtensionAttachment attachment) {
+    void addExtensionAttachment(ExtensionAttachment attachment) {
         if (attachment == null) {
             throw new NullPointerException(
                     "Parameter attachment must not be null");
@@ -611,27 +605,23 @@ public abstract class FObj extends FONode implements Constants {
         private static final int F_REMOVE_ALLOWED = 2;
         
         private FONode currentNode;
-        private FObj parentNode;
+        private final FObj parentNode;
         private int currentIndex;
         private int flags = F_NONE_ALLOWED;
         
-        protected FObjIterator(FObj parent) {
+        FObjIterator(FObj parent) {
             this.parentNode = parent;
             this.currentNode = parent.firstChild;
             this.currentIndex = 0;
             this.flags = F_NONE_ALLOWED;
         }
         
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public FObj parentNode() {
             return parentNode;
         }
         
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public Object next() {
             if (currentNode != null) {
                 if (currentIndex != 0) {
@@ -650,9 +640,7 @@ public abstract class FObj extends FONode implements Constants {
             }
         }
 
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public Object previous() {
             if (currentNode.siblings != null
                     && currentNode.siblings[0] != null) {
@@ -665,9 +653,7 @@ public abstract class FObj extends FONode implements Constants {
             }
         }
         
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public void set(Object o) {
             if ((flags & F_SET_ALLOWED) == F_SET_ALLOWED) {
                 FONode newNode = (FONode) o;
@@ -685,9 +671,7 @@ public abstract class FObj extends FONode implements Constants {
             }
         }
         
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public void add(Object o) {
             FONode newNode = (FONode) o;
             if (currentIndex == -1) {
@@ -707,9 +691,7 @@ public abstract class FObj extends FONode implements Constants {
             flags &= F_NONE_ALLOWED;
         }
 
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public boolean hasNext() {
             return (currentNode != null)
                 && ((currentIndex == 0)
@@ -717,32 +699,24 @@ public abstract class FObj extends FONode implements Constants {
                             && currentNode.siblings[1] != null));
         }
 
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public boolean hasPrevious() {
             return (currentIndex != 0)
                 || (currentNode.siblings != null
                     && currentNode.siblings[0] != null);
         }
         
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public int nextIndex() {
             return currentIndex + 1;
         }
 
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public int previousIndex() {
             return currentIndex - 1;
         }
 
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public void remove() {
             if ((flags & F_REMOVE_ALLOWED) == F_REMOVE_ALLOWED) {
                 parentNode.removeChild(currentNode);
@@ -762,9 +736,7 @@ public abstract class FObj extends FONode implements Constants {
             }
         }
 
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public FONode lastNode() {
             while (currentNode != null
                     && currentNode.siblings != null
@@ -775,28 +747,21 @@ public abstract class FObj extends FONode implements Constants {
             return currentNode;
         }
         
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public FONode firstNode() {
             currentNode = parentNode.firstChild;
             currentIndex = 0;
             return currentNode;
         }
         
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public FONode nextNode() {
             return (FONode) next();
         }
         
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public FONode previousNode() {
             return (FONode) previous();
         }
     }
-
 }
diff --git a/src/java/org/apache/fop/fo/FObjMixed.java b/src/java/org/apache/fop/fo/FObjMixed.java
index eb64c8f61..698fc58f2 100644
--- a/src/java/org/apache/fop/fo/FObjMixed.java
+++ b/src/java/org/apache/fop/fo/FObjMixed.java
@@ -24,23 +24,25 @@ import org.xml.sax.Locator;
 import org.apache.fop.apps.FOPException;
 
 /**
- * Base class for representation of mixed content formatting objects
- * (i.e., those that can contain both child FO's and text nodes/PCDATA).
- * It should not be instantiated directly.
+ * Abstract base class for representation of mixed content formatting objects
+ * (= those that can contain both child {@link FONode}s and <code>#PCDATA</code>).
  */
 public abstract class FObjMixed extends FObj {
     
-    /** Represents accumulated, pending FO text. See flushText(). */
+    /** Represents accumulated, pending FO text. See {@link #flushText()}. */
     protected FOText ft = null;
     
     /** Used for white-space handling; start CharIterator at node ... */
     protected FONode currentTextNode;
     
-    /** Used in creating pointers between subsequent FOText nodes
-     *  in the same Block (for handling text-transform) */
+    /** Used in creating pointers between subsequent {@link FOText} nodes
+     *  in the same {@link org.apache.fop.fo.flow.Block} 
+     *  (for handling text-transform) */
     protected FOText lastFOTextProcessed = null;
     
     /**
+     * Base constructor
+     * 
      * @param parent FONode that is the parent of this object
      */
     protected FObjMixed(FONode parent) {
@@ -75,8 +77,9 @@ public abstract class FObjMixed extends FObj {
     /**
      * Handles white-space for the node that is passed in, 
      * starting at its current text-node
-     * (used by RetrieveMarker to trigger 'end-of-node' white-space
-     *  handling)
+     * (used by {@link org.apache.fop.fo.flow.RetrieveMarker} 
+     *  to trigger 'end-of-node' white-space handling)
+     *  
      * @param fobj  the node for which to handle white-space
      */
     protected static void handleWhiteSpaceFor(FObjMixed fobj) {
@@ -86,8 +89,8 @@ public abstract class FObjMixed extends FObj {
     
     /**
      * Adds accumulated text as one FOText instance, unless
-     * the one instance's char array contains more than 
-     * Short.MAX_VALUE characters. In the latter case the 
+     * the one instance's <code>char</code> array contains more than 
+     * <code>Short.MAX_VALUE</code> characters. In the latter case the 
      * instance is split up into more manageable chunks.
      * 
      * @throws FOPException if there is a problem during processing
@@ -145,9 +148,7 @@ public abstract class FObjMixed extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void addChildNode(FONode child) throws FOPException {
         flushText();
         if (!inMarker()) {
@@ -166,6 +167,8 @@ public abstract class FObjMixed extends FObj {
     }
     
     /**
+     * Returns a {@link CharIterator} over this FO's character content
+     * 
      * @return iterator for this object
      */
     public CharIterator charIterator() {
diff --git a/src/java/org/apache/fop/fo/XMLObj.java b/src/java/org/apache/fop/fo/XMLObj.java
index 42fb1b9a1..da610f0e3 100644
--- a/src/java/org/apache/fop/fo/XMLObj.java
+++ b/src/java/org/apache/fop/fo/XMLObj.java
@@ -54,7 +54,9 @@ public abstract class XMLObj extends FONode implements ObjectBuiltListener {
     protected String name;
 
     /**
-     * @param parent the parent formatting object
+     * Base constructor
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     public XMLObj(FONode parent) {
         super(parent);
@@ -62,7 +64,7 @@ public abstract class XMLObj extends FONode implements ObjectBuiltListener {
 
     /**
      * {@inheritDoc}
-     * here, blocks XSL FO's from having non-FO parents.
+     * <br>Here, blocks XSL-FO's from having non-FO parents.
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
         throws ValidationException {
@@ -71,9 +73,7 @@ public abstract class XMLObj extends FONode implements ObjectBuiltListener {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void processNode(String elementName, Locator locator, 
         Attributes attlist, PropertyList propertyList) throws FOPException {
             setLocator(locator);
@@ -90,6 +90,7 @@ public abstract class XMLObj extends FONode implements ObjectBuiltListener {
 
     /**
      * Returns the dimensions of the generated area in pts.
+     * 
      * @param view Point2D instance to receive the dimensions
      * @return the requested dimensions in pts.
      */
@@ -99,6 +100,7 @@ public abstract class XMLObj extends FONode implements ObjectBuiltListener {
     
     /**
      * Retrieve the intrinsic alignment-adjust of the child element.
+     * 
      * @return the intrinsic alignment-adjust.
      */
     public Length getIntrinsicAlignmentAdjust() {
@@ -150,6 +152,7 @@ public abstract class XMLObj extends FONode implements ObjectBuiltListener {
     
     /**
      * Add the top-level element to the DOM document
+     * 
      * @param doc DOM document
      * @param svgRoot non-XSL-FO element to be added as the root of this document
      */
@@ -160,6 +163,7 @@ public abstract class XMLObj extends FONode implements ObjectBuiltListener {
 
     /**
      * Create an empty DOM document
+     * 
      * @return DOM document
      */
     public Document createBasicDocument() {
@@ -187,9 +191,7 @@ public abstract class XMLObj extends FONode implements ObjectBuiltListener {
         return doc;
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void addChildNode(FONode child) {
         if (child instanceof XMLObj) {
             ((XMLObj)child).addElement(doc, element);
@@ -203,6 +205,7 @@ public abstract class XMLObj extends FONode implements ObjectBuiltListener {
 
     /**
      * Add parsed characters to this object
+     * 
      * @param data array of characters contaning the text to add
      * @param start starting array element to add
      * @param length number of characters from the array to add
diff --git a/src/java/org/apache/fop/fo/XMLWhiteSpaceHandler.java b/src/java/org/apache/fop/fo/XMLWhiteSpaceHandler.java
index 8e5e4f297..bfebf6233 100644
--- a/src/java/org/apache/fop/fo/XMLWhiteSpaceHandler.java
+++ b/src/java/org/apache/fop/fo/XMLWhiteSpaceHandler.java
@@ -220,8 +220,6 @@ public class XMLWhiteSpaceHandler {
      * firstTextNode (when a nested FO is encountered)
      * @param fo    the FO for which to handle white-space
      * @param firstTextNode the node at which to start
-     * @param nextChild the child-node that will be added to the list after
-     *                  the last text-node
      */
     public void handleWhiteSpace(FObjMixed fo, FONode firstTextNode) {
         handleWhiteSpace(fo, firstTextNode, null);
diff --git a/src/java/org/apache/fop/fo/flow/AbstractGraphics.java b/src/java/org/apache/fop/fo/flow/AbstractGraphics.java
index a58cc08f2..19cea1510 100644
--- a/src/java/org/apache/fop/fo/flow/AbstractGraphics.java
+++ b/src/java/org/apache/fop/fo/flow/AbstractGraphics.java
@@ -26,15 +26,18 @@ import org.apache.fop.fo.FObj;
 import org.apache.fop.fo.GraphicsProperties;
 import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.properties.CommonBorderPaddingBackground;
+import org.apache.fop.fo.properties.KeepProperty;
 import org.apache.fop.fo.properties.LengthRangeProperty;
 import org.apache.fop.fo.properties.SpaceProperty;
 
 /**
- * Common base class for instream-foreign-object and external-graphics
- * flow formatting objects.
+ * Common base class for the <a href="http://www.w3.org/TR/xsl/#fo_instream-foreign-object">
+ * <code>fo:instream-foreign-object</code></a>
+ * and <a href="http://www.w3.org/TR/xsl/#fo_external-graphic">
+ * <code>fo:external-graphic</code></a> flow formatting objects.
  */
 public abstract class AbstractGraphics extends FObj implements GraphicsProperties {
-    
+
     // The value of properties relevant for fo:instream-foreign-object
     // and external-graphics.
     private CommonBorderPaddingBackground commonBorderPaddingBackground;
@@ -50,6 +53,8 @@ public abstract class AbstractGraphics extends FObj implements GraphicsPropertie
     private Length height;
     private String id;
     private LengthRangeProperty inlineProgressionDimension;
+    private KeepProperty keepWithNext;
+    private KeepProperty keepWithPrevious;
     private SpaceProperty lineHeight;
     private int overflow;
     private int scaling;
@@ -61,8 +66,6 @@ public abstract class AbstractGraphics extends FObj implements GraphicsPropertie
     //     private CommonMarginInline commonMarginInline;
     //     private CommonRelativePosition commonRelativePosition;
     //     private String contentType;
-    //     private KeepProperty keepWithNext;
-    //     private KeepProperty keepWithPrevious;
     //     private int scalingMethod;
     // End of property values
 
@@ -77,9 +80,7 @@ public abstract class AbstractGraphics extends FObj implements GraphicsPropertie
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         commonBorderPaddingBackground = pList.getBorderPaddingBackgroundProps();
         alignmentAdjust = pList.get(PR_ALIGNMENT_ADJUST).getLength();
@@ -94,6 +95,8 @@ public abstract class AbstractGraphics extends FObj implements GraphicsPropertie
         height = pList.get(PR_HEIGHT).getLength();
         id = pList.get(PR_ID).getString();
         inlineProgressionDimension = pList.get(PR_INLINE_PROGRESSION_DIMENSION).getLengthRange();
+        keepWithNext = pList.get(PR_KEEP_WITH_NEXT).getKeep();
+        keepWithPrevious = pList.get(PR_KEEP_WITH_PREVIOUS).getKeep();
         lineHeight = pList.get(PR_LINE_HEIGHT).getSpace();
         overflow = pList.get(PR_OVERFLOW).getEnum();
         scaling = pList.get(PR_SCALING).getEnum();
@@ -108,60 +111,52 @@ public abstract class AbstractGraphics extends FObj implements GraphicsPropertie
         return id;
     }
 
-    /**
-     * @return the Common Border, Padding, and Background Properties.
-     */
+    /** @return the {@link CommonBorderPaddingBackground} */
     public CommonBorderPaddingBackground getCommonBorderPaddingBackground() {
         return commonBorderPaddingBackground;
     }
 
-    /**
-     * @return the "line-height" property.
-     */
+    /** @return the "line-height" property */
     public SpaceProperty getLineHeight() {
         return lineHeight;
     }
 
-    /** {@inheritDoc} */
+    /** @return the "inline-progression-dimension" property */
     public LengthRangeProperty getInlineProgressionDimension() {
         return inlineProgressionDimension;
     }
 
-    /** {@inheritDoc} */
+    /** @return the "block-progression-dimension" property */
     public LengthRangeProperty getBlockProgressionDimension() {
         return blockProgressionDimension;
     }
 
-    /**
-     * @return the "height" property.
-     */
+    /** @return the "height" property */
     public Length getHeight() {
         return height;
     }
 
-    /**
-     * @return the "width" property.
-     */
+    /** @return the "width" property */
     public Length getWidth() {
         return width;
     }
 
-    /** {@inheritDoc} */
+    /** @return the "content-height" property */
     public Length getContentHeight() {
         return contentHeight;
     }
 
-    /** {@inheritDoc} */
+    /** @return the "content-width" property */
     public Length getContentWidth() {
         return contentWidth;
     }
 
-    /** {@inheritDoc} */
+    /** @return the "scaling" property */
     public int getScaling() {
         return scaling;
     }
 
-    /** {@inheritDoc} */
+    /** @return the "overflow" property */
     public int getOverflow() {
         return overflow;
     }
@@ -176,9 +171,7 @@ public abstract class AbstractGraphics extends FObj implements GraphicsPropertie
         return textAlign;
     }
 
-    /**
-     * @return the "alignment-adjust" property
-     */
+    /** @return the "alignment-adjust" property */
     public Length getAlignmentAdjust() {
         if (alignmentAdjust.getEnum() == EN_AUTO) {
             final Length intrinsicAlignmentAdjust = this.getIntrinsicAlignmentAdjust();
@@ -188,40 +181,38 @@ public abstract class AbstractGraphics extends FObj implements GraphicsPropertie
         }
         return alignmentAdjust;
     }
-    
-    /**
-     * @return the "alignment-baseline" property
-     */
+
+    /** @return the "alignment-baseline" property */
     public int getAlignmentBaseline() {
         return alignmentBaseline;
     }
-    
-    /**
-     * @return the "baseline-shift" property
-     */
+
+    /** @return the "baseline-shift" property */
     public Length getBaselineShift() {
         return baselineShift;
     }
-    
-    /**
-     * @return the "dominant-baseline" property
-     */
+
+    /** @return the "dominant-baseline" property */
     public int getDominantBaseline() {
         return dominantBaseline;
     }
-    
-    /**
-     * @return the graphics intrinsic width in millipoints
-     */
+
+    /** @return the "keep-with-next" property */
+    public KeepProperty getKeepWithNext() {
+        return keepWithNext;
+    }
+
+    /** @return the "keep-with-previous" property */
+    public KeepProperty getKeepWithPrevious() {
+        return keepWithPrevious;
+    }
+
+    /** @return the graphic's intrinsic width in millipoints */
     public abstract int getIntrinsicWidth();
 
-    /**
-     * @return the graphics intrinsic height in millipoints
-     */
+    /** @return the graphic's intrinsic height in millipoints */
     public abstract int getIntrinsicHeight();
 
-    /**
-     * @return the graphics intrinsic alignment-adjust
-     */
+    /** @return the graphic's intrinsic alignment-adjust */
     public abstract Length getIntrinsicAlignmentAdjust();
 }
diff --git a/src/java/org/apache/fop/fo/flow/AbstractListItemPart.java b/src/java/org/apache/fop/fo/flow/AbstractListItemPart.java
index f99f9d947..092358891 100644
--- a/src/java/org/apache/fop/fo/flow/AbstractListItemPart.java
+++ b/src/java/org/apache/fop/fo/flow/AbstractListItemPart.java
@@ -29,7 +29,9 @@ import org.apache.fop.fo.ValidationException;
 import org.apache.fop.fo.properties.KeepProperty;
 
 /**
- * Common superclass for list-item-label and list-item-body.
+ * Common superclass for <a href="http://www.w3.org/TR/xsl/#fo_list-item-label">
+ * <code>fo:list-item-label</code></a> and <a href="http://www.w3.org/TR/xsl/#fo_list-item-body">
+ * <code>fo:list-item-body</code></a>.
  */
 public abstract class AbstractListItemPart extends FObj {
     // The value of properties relevant for fo:list-item-label and fo:list-item-body.
@@ -42,15 +44,15 @@ public abstract class AbstractListItemPart extends FObj {
     private boolean blockItemFound = false;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public AbstractListItemPart(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         keepTogether = pList.get(PR_KEEP_TOGETHER).getKeep();
@@ -58,7 +60,7 @@ public abstract class AbstractListItemPart extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: marker* (%block;)+
+     * <br>XSL Content Model: marker* (%block;)+
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
         throws ValidationException {
@@ -75,9 +77,7 @@ public abstract class AbstractListItemPart extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         if (!this.blockItemFound) {
             String contentModel = "marker* (%block;)+";
diff --git a/src/java/org/apache/fop/fo/flow/AbstractPageNumberCitation.java b/src/java/org/apache/fop/fo/flow/AbstractPageNumberCitation.java
index e9a1176d6..b45f21348 100644
--- a/src/java/org/apache/fop/fo/flow/AbstractPageNumberCitation.java
+++ b/src/java/org/apache/fop/fo/flow/AbstractPageNumberCitation.java
@@ -36,7 +36,10 @@ import org.apache.fop.fo.properties.CommonTextDecoration;
 import org.apache.fop.fo.properties.SpaceProperty;
 
 /**
- * Base class modelling the fo:page-number-citation object.
+ * Common base class for the <a href="http://www.w3.org/TR/xsl/#fo_page-number-citation">
+ * <code>fo:page-number-citation</code></a> and 
+ * <a href="http://www.w3.org/TR/xsl/#fo_page-number-citation-last">
+ * <code>fo:page-number-citation-last</code></a> objects.
  */
 public abstract class AbstractPageNumberCitation extends FObj {
     
@@ -73,15 +76,15 @@ public abstract class AbstractPageNumberCitation extends FObj {
     private Color color;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public AbstractPageNumberCitation(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         commonBorderPaddingBackground = pList.getBorderPaddingBackgroundProps();
@@ -110,7 +113,7 @@ public abstract class AbstractPageNumberCitation extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: empty
+     * <br>XSL Content Model: empty
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -119,7 +122,7 @@ public abstract class AbstractPageNumberCitation extends FObj {
         }
     }
 
-    /** @return the Common Font Properties. */
+    /** @return the {@link CommonFont} */
     public CommonFont getCommonFont() {
         return commonFont;
     }
@@ -134,42 +137,32 @@ public abstract class AbstractPageNumberCitation extends FObj {
         return textDecoration; 
     }
     
-    /**
-     * @return the "alignment-adjust" property
-     */
+    /** @return the "alignment-adjust" property */
     public Length getAlignmentAdjust() {
         return alignmentAdjust;
     }
     
-    /**
-     * @return the "alignment-baseline" property
-     */
+    /** @return the "alignment-baseline" property */
     public int getAlignmentBaseline() {
         return alignmentBaseline;
     }
     
-    /**
-     * @return the "baseline-shift" property
-     */
+    /** @return the "baseline-shift" property */
     public Length getBaselineShift() {
         return baselineShift;
     }
     
-    /**
-     * @return the "dominant-baseline" property
-     */
+    /** @return the "dominant-baseline" property */
     public int getDominantBaseline() {
         return dominantBaseline;
     }
     
-    /** @return the Common Border, Padding, and Background Properties. */
+    /** @return the {@link CommonBorderPaddingBackground} */
     public CommonBorderPaddingBackground getCommonBorderPaddingBackground() {
         return commonBorderPaddingBackground;
     }
 
-    /**
-     * @return the "line-height" property
-     */
+    /** @return the "line-height" property */
     public SpaceProperty getLineHeight() {
         return lineHeight;
     }
diff --git a/src/java/org/apache/fop/fo/flow/BidiOverride.java b/src/java/org/apache/fop/fo/flow/BidiOverride.java
index 892f4a3c5..492e6c4ba 100644
--- a/src/java/org/apache/fop/fo/flow/BidiOverride.java
+++ b/src/java/org/apache/fop/fo/flow/BidiOverride.java
@@ -29,7 +29,8 @@ import org.apache.fop.fo.ValidationException;
 import org.apache.fop.fo.properties.SpaceProperty;
 
 /**
- * Class modelling the fo:bidi-override object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_bidi-override">
+ * <code>fo:bidi-override</code></a> object.
  */
 public class BidiOverride extends FObjMixed {
 
@@ -52,6 +53,8 @@ public class BidiOverride extends FObjMixed {
     // End of property values
 
     /**
+     * Base constructor
+     * 
      * @param parent FONode that is the parent of this object
      */
     public BidiOverride(FONode parent) {
@@ -77,9 +80,7 @@ public class BidiOverride extends FObjMixed {
 
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         // prDirection = pList.get(PR_DIRECTION);
         // prLetterSpacing = pList.get(PR_LETTER_SPACING);
@@ -90,11 +91,11 @@ public class BidiOverride extends FObjMixed {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: marker* (#PCDATA|%inline;|%block;)*
-     * Additionally: "An fo:bidi-override that is a descendant of an fo:leader
+     * <br>XSL Content Model: marker* (#PCDATA|%inline;|%block;)*
+     * <br><i>Additionally: "An fo:bidi-override that is a descendant of an fo:leader
      *  or of the fo:inline child of an fo:footnote may not have block-level
      *  children, unless it has a nearer ancestor that is an 
-     *  fo:inline-container."
+     *  fo:inline-container."</i>
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -115,9 +116,7 @@ public class BidiOverride extends FObjMixed {
         }
     }
 
-    /**
-     * @return the "line-height" property.
-     */
+    /** @return the "line-height" property */
     public SpaceProperty getLineHeight() {
         return lineHeight;
     }
@@ -129,6 +128,7 @@ public class BidiOverride extends FObjMixed {
 
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_BIDI_OVERRIDE}
      */
     public int getNameId() {
         return FO_BIDI_OVERRIDE;
diff --git a/src/java/org/apache/fop/fo/flow/Block.java b/src/java/org/apache/fop/fo/flow/Block.java
index 30b4c5495..40175ce49 100644
--- a/src/java/org/apache/fop/fo/flow/Block.java
+++ b/src/java/org/apache/fop/fo/flow/Block.java
@@ -41,7 +41,8 @@ import org.apache.fop.fo.properties.KeepProperty;
 import org.apache.fop.fo.properties.SpaceProperty;
 
  /**
-  * Class modelling the fo:block object.
+  * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_block">
+  * <code>fo:block object</code></a>.
   */
 public class Block extends FObjMixed {
 
@@ -87,6 +88,8 @@ public class Block extends FObjMixed {
     // End of property values
     
     /**
+     * Base constructor
+     * 
      * @param parent FONode that is the parent of this object
      *
      */
@@ -94,9 +97,7 @@ public class Block extends FObjMixed {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         commonBorderPaddingBackground = pList.getBorderPaddingBackgroundProps();
@@ -130,46 +131,35 @@ public class Block extends FObjMixed {
         wrapOption = pList.get(PR_WRAP_OPTION).getEnum();
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void startOfNode() throws FOPException {
         super.startOfNode();
         getFOEventHandler().startBlock(this);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         super.endOfNode();
         getFOEventHandler().endBlock(this);
     }
 
-    /**
-     * @return the Common Margin Properties-Block.
-     */
+    /** @return the {@link CommonMarginBlock} */
     public CommonMarginBlock getCommonMarginBlock() {
         return commonMarginBlock;
     }
 
-    /**
-     * @return the Common Border, Padding, and Background Properties.
-     */
+    /** @return the {@link CommonBorderPaddingBackground} */
     public CommonBorderPaddingBackground getCommonBorderPaddingBackground() {
         return commonBorderPaddingBackground;
     }
 
     /**
-     * @return the Common Font Properties.
-     */
+     * @return the {@link CommonFont} */
     public CommonFont getCommonFont() {
         return commonFont;
     }
 
-    /**
-     * @return the Common Hyphenation Properties.
-     */
+    /** @return the {@link CommonHyphenation} */
     public CommonHyphenation getCommonHyphenation() {
         return commonHyphenation;
     }
@@ -219,79 +209,63 @@ public class Block extends FObjMixed {
         return lineStackingStrategy;
     }
 
-    /**
-     * @return the "color" property.
-     */
+    /** @return the "color" property */
     public Color getColor() {
         return color;
     }
 
-    /**
-     * @return the "line-height" property.
-     */
+    /** @return the "line-height" property */
     public SpaceProperty getLineHeight() {
         return lineHeight;
     }
 
-    /**
-     * @return the "span" property.
-     */
+    /** @return the "span" property */
     public int getSpan() {
         return this.span;
     }
 
-    /**
-     * @return the "text-align" property.
-     */
+    /** @return the "text-align" property */
     public int getTextAlign() {
         return textAlign;
     }
 
-    /**
-     * @return the "text-align-last" property.
-     */
+    /** @return the "text-align-last" property */
     public int getTextAlignLast() {
         return textAlignLast;
     }
 
-    /**
-     * @return the "text-indent" property.
-     */
+    /** @return the "text-indent" property */
     public Length getTextIndent() {
         return textIndent;
     }
 
-    /**
-     * @return the "last-line-end-indent" property.
-     */
+    /** @return the "last-line-end-indent" property */
     public Length getLastLineEndIndent() {
         return lastLineEndIndent;
     }
 
-    /**
-     * @return the "wrap-option" property.
-     */
+    /** @return the "wrap-option" property */
     public int getWrapOption() {
         return wrapOption;
     }
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: marker* initial-property-set? (#PCDATA|%inline;|%block;)*
-     * Additionally: "An fo:bidi-override that is a descendant of an fo:leader
+     * <br>XSL Content Model: marker* initial-property-set? (#PCDATA|%inline;|%block;)*
+     * <br><i>Additionally: "An fo:bidi-override that is a descendant of an fo:leader
      *  or of the fo:inline child of an fo:footnote may not have block-level
      *  children, unless it has a nearer ancestor that is an 
-     *  fo:inline-container."
+     *  fo:inline-container."</i>
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
             throws ValidationException {
         if (FO_URI.equals(nsURI)) {
-            if (localName.equals("marker")) {
+            if ("marker".equals(localName)) {
                 if (blockOrInlineItemFound || initialPropertySetFound) {
                    nodesOutOfOrderError(loc, "fo:marker", 
                         "initial-property-set? (#PCDATA|%inline;|%block;)");
                 }
-            } else if (localName.equals("initial-property-set")) {
+            } else if ("initial-property-set".equals(localName)) {
                 if (initialPropertySetFound) {
                     tooManyNodesError(loc, "fo:initial-property-set");
                 } else if (blockOrInlineItemFound) {
@@ -308,57 +282,37 @@ public class Block extends FObjMixed {
         }
     }
 
-    /**
-     * Accessor for the linefeed-treatment property
-     * 
-     * @return the enum value of linefeed-treatment
-     */
+    /** @return the "linefeed-treatment" property */
     public int getLinefeedTreatment() {
         return linefeedTreatment;
     }
     
-    /**
-     * Accessor for the white-space-treatment property
-     * 
-     * @return the enum value of white-space-treatment
-     */
+    /** @return the "white-space-treatment" property */
     public int getWhitespaceTreatment() {
         return whiteSpaceTreatment;
     }
     
-    /**
-     * Accessor for the white-space-collapse property
-     * 
-     * @return the enum value of white-space-collapse
-     */
+    /** @return the "white-space-collapse" property */
     public int getWhitespaceCollapse() {
         return whiteSpaceCollapse;
     }
     
-    /**
-     * @return Returns the commonRelativePosition.
-     */
+    /** @return the {@link CommonRelativePosition} */
     public CommonRelativePosition getCommonRelativePosition() {
         return this.commonRelativePosition;
     }
 
-    /**
-     * @return Returns the hyphenationKeep.
-     */
+    /** @return the "hyphenation-keep" property */
     public int getHyphenationKeep() {
         return this.hyphenationKeep;
     }
 
-    /**
-     * @return Returns the intrusionDisplace.
-     */
+    /** @return the "intrusion-displace" property */
     public int getIntrusionDisplace() {
         return this.intrusionDisplace;
     }
 
-    /**
-     * @return Returns the lineHeightShiftAdjustment.
-     */
+    /** @return the "line-height-shift-adjustment" property */
     public int getLineHeightShiftAdjustment() {
         return this.lineHeightShiftAdjustment;
     }
@@ -373,9 +327,10 @@ public class Block extends FObjMixed {
         return "block";
     }
 
-    /**
-     * {@inheritDoc}
-     */
+     /**
+      * {@inheritDoc}
+      * @return {@link org.apache.fop.fo.Constants#FO_BLOCK}
+      */
     public int getNameId() {
         return FO_BLOCK;
     }
diff --git a/src/java/org/apache/fop/fo/flow/Character.java b/src/java/org/apache/fop/fo/flow/Character.java
index aad4209f9..7fd98b0ef 100644
--- a/src/java/org/apache/fop/fo/flow/Character.java
+++ b/src/java/org/apache/fop/fo/flow/Character.java
@@ -35,22 +35,13 @@ import org.apache.fop.fo.properties.CommonBorderPaddingBackground;
 import org.apache.fop.fo.properties.CommonFont;
 import org.apache.fop.fo.properties.CommonHyphenation;
 import org.apache.fop.fo.properties.CommonTextDecoration;
+import org.apache.fop.fo.properties.KeepProperty;
 import org.apache.fop.fo.properties.Property;
 import org.apache.fop.fo.properties.SpaceProperty;
 
 /**
- * Class modelling the fo:character object. 
- * Its use is defined by the spec: 
- * "The fo:character flow object represents a character that is mapped to
- *  a glyph for presentation. It is an atomic unit to the formatter.
- *  When the result tree is interpreted as a tree of formatting objects,
- *  a character in the result tree is treated as if it were an empty
- *  element of type fo:character with a character attribute
- *  equal to the Unicode representation of the character.
- *  The semantics of an "auto" value for character properties, which is
- *  typically their initial value,  are based on the Unicode codepoint.
- *  Overrides may be specified in an implementation-specific manner." (6.6.3)
- *
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_character">
+ * <code>fo:character</code></a> object.
  */
 public class Character extends FObj {
     // The value of properties relevant for fo:character.
@@ -63,8 +54,8 @@ public class Character extends FObj {
     private char character;
     private Color color;
     private int dominantBaseline;
-    // private ToBeImplementedProperty glyphOrientationHorizontal;
-    // private ToBeImplementedProperty glyphOrientationVertical;
+    private KeepProperty keepWithNext;
+    private KeepProperty keepWithPrevious;
     private Property letterSpacing;
     private SpaceProperty lineHeight;
     /** Holds the text decoration values. May be null */
@@ -75,11 +66,11 @@ public class Character extends FObj {
     //     private CommonAural commonAural;
     //     private CommonMarginInline commonMarginInline;
     //     private CommonRelativePosition commonRelativePosition;
+    //     private ToBeImplementedProperty glyphOrientationHorizontal;
+    //     private ToBeImplementedProperty glyphOrientationVertical;
     //     private int treatAsWordSpace;
     //     private Length textDepth;
     //     private Length textAltitude;
-    //     private KeepProperty keepWithNext;
-    //     private KeepProperty keepWithPrevious;
     //     private int scoreSpaces;
     //     private int suppressAtLineBreak;
     //     private int textTransform;
@@ -92,15 +83,13 @@ public class Character extends FObj {
     public static final int DOESNOT_FIT = 1;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * @param parent {@link FONode} that is the parent of this object
      */
     public Character(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         commonBorderPaddingBackground = pList.getBorderPaddingBackgroundProps();
@@ -113,18 +102,15 @@ public class Character extends FObj {
         character = pList.get(PR_CHARACTER).getCharacter();
         color = pList.get(PR_COLOR).getColor(getUserAgent());
         dominantBaseline = pList.get(PR_DOMINANT_BASELINE).getEnum();
-        // glyphOrientationHorizontal = pList.get(PR_GLYPH_ORIENTATION_HORIZONTAL);
-        // glyphOrientationVertical = pList.get(PR_GLYPH_ORIENTATION_VERTICAL);
+        keepWithNext = pList.get(PR_KEEP_WITH_NEXT).getKeep();
+        keepWithPrevious = pList.get(PR_KEEP_WITH_PREVIOUS).getKeep();
         letterSpacing = pList.get(PR_LETTER_SPACING);
         lineHeight = pList.get(PR_LINE_HEIGHT).getSpace();
         textDecoration = pList.getTextDecorationProps();
-        // textShadow = pList.get(PR_TEXT_SHADOW);
         wordSpacing = pList.get(PR_WORD_SPACING);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void startOfNode() throws FOPException {
         super.startOfNode();
         getFOEventHandler().character(this);
@@ -132,7 +118,7 @@ public class Character extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: empty
+     * <br>XSL Content Model: empty
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -141,86 +127,62 @@ public class Character extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public CharIterator charIterator() {
         return new FOCharIterator(this);
     }
 
-    /**
-     * @return the Common Border, Padding, and Background Properties.
-     */
+    /** @return the Common Border, Padding, and Background Properties */
     public CommonBorderPaddingBackground getCommonBorderPaddingBackground() {
         return commonBorderPaddingBackground;
     }
 
-    /**
-     * @return the Common Font Properties.
-     */
+    /** @return the Common Font Properties */
     public CommonFont getCommonFont() {
         return commonFont;
     }
 
-    /**
-     * @return the Common Hyphenation Properties.
-     */
+    /** @return the Common Hyphenation Properties */
     public CommonHyphenation getCommonHyphenation() {
         return commonHyphenation;
     }
 
-    /**
-     * @return the "character" property.
-     */
+    /** @return the "character" property */
     public char getCharacter() {
         return character;
     }
 
-    /**
-     * @return the "color" property.
-     */
+    /** @return the "color" property */
     public Color getColor() {
         return color;
     }
 
-    /**
-     * @return the "alignment-adjust" property
-     */
+    /** @return the "alignment-adjust" property */
     public Length getAlignmentAdjust() {
         return alignmentAdjust;
     }
     
-    /**
-     * @return the "alignment-baseline" property
-     */
+    /** @return the "alignment-baseline" property */
     public int getAlignmentBaseline() {
         return alignmentBaseline;
     }
     
-    /**
-     * @return the "baseline-shift" property
-     */
+    /** @return the "baseline-shift" property */
     public Length getBaselineShift() {
         return baselineShift;
     }
     
-    /**
-     * @return the "dominant-baseline" property
-     */
+    /** @return the "dominant-baseline" property */
     public int getDominantBaseline() {
         return dominantBaseline;
     }
     
-    /**
-     * @return the "letter-spacing" property.
-     */
+    /** @return the "letter-spacing" property */
     public Property getLetterSpacing() {
         return letterSpacing; 
     }
 
-    /**
-     * @return the "line-height" property.
-     */
+    /** @return the "line-height" property */
     public SpaceProperty getLineHeight() {
         return lineHeight;
     }
@@ -230,13 +192,21 @@ public class Character extends FObj {
         return textDecoration; 
     }
     
-    /**
-     * @return the "word-spacing" property.
-     */
+    /** @return the "word-spacing" property */
     public Property getWordSpacing() {
         return wordSpacing; 
     }
 
+    /** @return the "keep-with-next" property */
+    public KeepProperty getKeepWithNext() {
+        return keepWithNext;
+    }
+    
+    /** @return the "keep-with-previous" property */
+    public KeepProperty getKeepWithPrevious() {
+        return keepWithPrevious;
+    }
+    
     /** {@inheritDoc} */
     public String getLocalName() {
         return "character";
@@ -244,6 +214,7 @@ public class Character extends FObj {
     
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_CHARACTER}
      */
     public int getNameId() {
         return FO_CHARACTER;
diff --git a/src/java/org/apache/fop/fo/flow/ExternalGraphic.java b/src/java/org/apache/fop/fo/flow/ExternalGraphic.java
index 07f765e52..bfe54cbd9 100644
--- a/src/java/org/apache/fop/fo/flow/ExternalGraphic.java
+++ b/src/java/org/apache/fop/fo/flow/ExternalGraphic.java
@@ -58,7 +58,8 @@ public class ExternalGraphic extends AbstractGraphics {
     private Length intrinsicAlignmentAdjust;
     
     /**
-     * Create a new External graphic node.
+     * Create a new ExternalGraphic node that is a child
+     * of the given {@link FONode}.
      *
      * @param parent the parent of this node
      */
@@ -134,7 +135,10 @@ public class ExternalGraphic extends AbstractGraphics {
         return "external-graphic";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_EXTERNAL_GRAPHIC}
+     */
     public int getNameId() {
         return FO_EXTERNAL_GRAPHIC;
     }
diff --git a/src/java/org/apache/fop/fo/flow/Float.java b/src/java/org/apache/fop/fo/flow/Float.java
index 57d3b4ee1..90bc423fd 100644
--- a/src/java/org/apache/fop/fo/flow/Float.java
+++ b/src/java/org/apache/fop/fo/flow/Float.java
@@ -29,7 +29,8 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * Class modelling the fo:float object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_float">
+ * <code>fo:float</code></a> object.
  */
 public class Float extends FObj {
     // The value of properties relevant for fo:float (commented out for performance.
@@ -40,7 +41,9 @@ public class Float extends FObj {
     static boolean notImplementedWarningGiven = false;
     
     /**
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Base constructor
+     * 
+     * @param parent    the parent {@link FONode}
      */
     public Float(FONode parent) {
         super(parent);
@@ -52,16 +55,14 @@ public class Float extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         // No active properties -> Nothing to do.
     }
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: (%block;)+
+     * <br>XSL Content Model: (%block;)+
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -72,9 +73,7 @@ public class Float extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         if (firstChild == null) {
             missingChildElementError("(%block;)+");
@@ -88,6 +87,7 @@ public class Float extends FObj {
     
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_FLOAT}
      */
     public int getNameId() {
         return FO_FLOAT;
diff --git a/src/java/org/apache/fop/fo/flow/Footnote.java b/src/java/org/apache/fop/fo/flow/Footnote.java
index c15a7e0ee..54e457db8 100644
--- a/src/java/org/apache/fop/fo/flow/Footnote.java
+++ b/src/java/org/apache/fop/fo/flow/Footnote.java
@@ -28,7 +28,8 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * Class modelling the fo:footnote object.
+ * Class modelling the <a href=http://www.w3.org/TR/xsl/#fo_footnote">
+ * <code>fo:footnote</code></a> object.
  */
 public class Footnote extends FObj {
     // The value of properties relevant for fo:footnote (commented out for performance).
@@ -39,29 +40,28 @@ public class Footnote extends FObj {
     private FootnoteBody footnoteBody;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public Footnote(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         // No active properties -> do nothing.
     }
     
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void startOfNode() throws FOPException {
         getFOEventHandler().startFootnote(this);
     }
 
     /**
      * Make sure content model satisfied, if so then tell the
-     * FOEventHandler that we are at the end of the flow.
+     * {@link org.apache.fop.fo.FOEventHandler} that we are at the end of the footnote.
+     * 
      * {@inheritDoc}
      */
     protected void endOfNode() throws FOPException {
@@ -74,7 +74,7 @@ public class Footnote extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: (inline,footnote-body)
+     * <br>XSL Content Model: (inline,footnote-body)
      * @todo implement additional constraint: A fo:footnote is not permitted
      *      to have a fo:float, fo:footnote, or fo:marker as a descendant.
      * @todo implement additional constraint: A fo:footnote is not 
@@ -100,20 +100,19 @@ public class Footnote extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void addChildNode(FONode child) {
-        if (((FObj)child).getNameId() == FO_INLINE) {
+        if (child.getNameId() == FO_INLINE) {
             footnoteCitation = (Inline) child;
-        } else if (((FObj)child).getNameId() == FO_FOOTNOTE_BODY) {
+        } else if (child.getNameId() == FO_FOOTNOTE_BODY) {
             footnoteBody = (FootnoteBody) child;
         }
     }
 
     /**
      * Public accessor for inline FO
-     * @return the Inline child
+     * 
+     * @return the {@link Inline} child
      */
     public Inline getFootnoteCitation() {
         return footnoteCitation;
@@ -121,7 +120,8 @@ public class Footnote extends FObj {
 
     /**
      * Public accessor for footnote-body FO
-     * @return the FootnoteBody child
+     * 
+     * @return the {@link FootnoteBody} child
      */
     public FootnoteBody getFootnoteBody() {
         return footnoteBody;
@@ -134,6 +134,7 @@ public class Footnote extends FObj {
     
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_FOOTNOTE}
      */
     public int getNameId() {
         return FO_FOOTNOTE;
diff --git a/src/java/org/apache/fop/fo/flow/FootnoteBody.java b/src/java/org/apache/fop/fo/flow/FootnoteBody.java
index 967d15215..21c5a3efd 100644
--- a/src/java/org/apache/fop/fo/flow/FootnoteBody.java
+++ b/src/java/org/apache/fop/fo/flow/FootnoteBody.java
@@ -29,7 +29,8 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * Class modelling the fo:footnote-body object.
+ * Class modelling the <a href=http://www.w3.org/TR/xsl/#fo_footnote-body">
+ * <code>fo:footnote-body</code></a> object.
  */
 public class FootnoteBody extends FObj {
     // The value of properties relevant for fo:footnote-body (commented out for perforance).
@@ -37,28 +38,27 @@ public class FootnoteBody extends FObj {
     // End of property values
 
     /**
+     * Base constructor
+     * 
      * @param parent FONode that is the parent of this object
      */
     public FootnoteBody(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void startOfNode() throws FOPException {
         getFOEventHandler().startFootnoteBody(this);
     }
 
     /**
-     * Make sure content model satisfied, if so then tell the
-     * FOEventHandler that we are at the end of the flow.
+     * Make sure the content model is satisfied, if so then tell the
+     * {@link org.apache.fop.fo.FOEventHandler} that we are at the 
+     * end of the footnote-body.
      * {@inheritDoc}
      */
     protected void endOfNode() throws FOPException {
@@ -70,7 +70,7 @@ public class FootnoteBody extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: (%block;)+
+     * <br>XSL Content Model: (%block;)+
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -88,6 +88,7 @@ public class FootnoteBody extends FObj {
     
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_FOOTNOTE_BODY}
      */
     public int getNameId() {
         return FO_FOOTNOTE_BODY;
diff --git a/src/java/org/apache/fop/fo/flow/InitialPropertySet.java b/src/java/org/apache/fop/fo/flow/InitialPropertySet.java
index 6d0e495b7..6b2a1b50c 100644
--- a/src/java/org/apache/fop/fo/flow/InitialPropertySet.java
+++ b/src/java/org/apache/fop/fo/flow/InitialPropertySet.java
@@ -30,7 +30,8 @@ import org.apache.fop.fo.ValidationException;
 import org.apache.fop.fo.properties.SpaceProperty;
 
 /**
- * Class modelling the fo:initial-property-set object.
+ * Class modelling the <a href=http://www.w3.org/TR/xsl/#fo_initial-property-set">
+ * <code>fo:initial-property-set</code></a> object.
  */
 public class InitialPropertySet extends FObj {
     // The value of properties relevant for fo:initial-property-set.
@@ -51,15 +52,15 @@ public class InitialPropertySet extends FObj {
     // End of property values
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public InitialPropertySet(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         // letterSpacing = pList.get(PR_LETTER_SPACING);
@@ -69,7 +70,7 @@ public class InitialPropertySet extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: empty
+     * <br>XSL Content Model: empty
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -78,9 +79,7 @@ public class InitialPropertySet extends FObj {
         }
     }
 
-    /**
-     * @return the "line-height" property.
-     */
+    /** @return the "line-height" property */
     public SpaceProperty getLineHeight() {
         return lineHeight;
     }
@@ -92,6 +91,7 @@ public class InitialPropertySet extends FObj {
     
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_INITIAL_PROPERTY_SET}
      */
     public int getNameId() {
         return FO_INITIAL_PROPERTY_SET;
diff --git a/src/java/org/apache/fop/fo/flow/Inline.java b/src/java/org/apache/fop/fo/flow/Inline.java
index 50662d9f1..a770b0f06 100644
--- a/src/java/org/apache/fop/fo/flow/Inline.java
+++ b/src/java/org/apache/fop/fo/flow/Inline.java
@@ -28,7 +28,8 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * Class modelling the fo:inline formatting object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_inline">
+ * <code>fo:inline</code></a> formatting object.
  */
 public class Inline extends InlineLevel {
     // The value of properties relevant for fo:inline.
@@ -50,15 +51,15 @@ public class Inline extends InlineLevel {
     private boolean canHaveBlockLevelChildren = true;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public Inline(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         alignmentAdjust = pList.get(PR_ALIGNMENT_ADJUST).getLength();
@@ -67,9 +68,7 @@ public class Inline extends InlineLevel {
         dominantBaseline = pList.get(PR_DOMINANT_BASELINE).getEnum();
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void startOfNode() throws FOPException {
        super.startOfNode();
        
@@ -94,9 +93,7 @@ public class Inline extends InlineLevel {
        getFOEventHandler().startInline(this);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         super.endOfNode();
         getFOEventHandler().endInline(this);
@@ -104,10 +101,10 @@ public class Inline extends InlineLevel {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: marker* (#PCDATA|%inline;|%block;)*
-     * Additionally: " An fo:inline that is a descendant of an fo:leader
+     * <br>XSL Content Model: marker* (#PCDATA|%inline;|%block;)*
+     * <br><i>Additionally: " An fo:inline that is a descendant of an fo:leader
      *  or fo:footnote may not have block-level children, unless it has a
-     *  nearer ancestor that is an fo:inline-container." (paraphrased)
+     *  nearer ancestor that is an fo:inline-container." (paraphrased)</i>
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -127,30 +124,22 @@ public class Inline extends InlineLevel {
         }
     }
 
-    /**
-     * @return the "alignment-adjust" property
-     */
+    /** @return the "alignment-adjust" property */
     public Length getAlignmentAdjust() {
         return alignmentAdjust;
     }
     
-    /**
-     * @return the "alignment-baseline" property
-     */
+    /** @return the "alignment-baseline" property */
     public int getAlignmentBaseline() {
         return alignmentBaseline;
     }
     
-    /**
-     * @return the "baseline-shift" property
-     */
+    /** @return the "baseline-shift" property */
     public Length getBaselineShift() {
         return baselineShift;
     }
     
-    /**
-     * @return the "dominant-baseline" property
-     */
+    /** @return the "dominant-baseline" property */
     public int getDominantBaseline() {
         return dominantBaseline;
     }
@@ -160,7 +149,10 @@ public class Inline extends InlineLevel {
         return "inline";
     }
     
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_INLINE}
+     */
     public int getNameId() {
         return FO_INLINE;
     }
diff --git a/src/java/org/apache/fop/fo/flow/InlineContainer.java b/src/java/org/apache/fop/fo/flow/InlineContainer.java
index 3c142afe9..c26730b3a 100644
--- a/src/java/org/apache/fop/fo/flow/InlineContainer.java
+++ b/src/java/org/apache/fop/fo/flow/InlineContainer.java
@@ -23,14 +23,20 @@ import org.xml.sax.Locator;
 
 import org.apache.fop.apps.FOPException;
 import org.apache.fop.datatypes.Length;
+import org.apache.fop.datatypes.Numeric;
 import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.FObj;
 import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
+import org.apache.fop.fo.properties.CommonBorderPaddingBackground;
+import org.apache.fop.fo.properties.CommonMarginInline;
+import org.apache.fop.fo.properties.KeepProperty;
+import org.apache.fop.fo.properties.LengthRangeProperty;
 import org.apache.fop.fo.properties.SpaceProperty;
 
 /**
- * Class modelling the fo:inline-container object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_inline-container">
+ * <code>fo:inline-container</code></a> object.
  */
 public class InlineContainer extends FObj {
     
@@ -38,52 +44,60 @@ public class InlineContainer extends FObj {
     private Length alignmentAdjust;
     private int alignmentBaseline;
     private Length baselineShift;
-    // private ToBeImplementedProperty clip;
+    private LengthRangeProperty blockProgressionDimension;
+    private CommonBorderPaddingBackground commonBorderPaddingBackground;
+    private CommonMarginInline commonMarginInline;
+    private int clip;
     private int dominantBaseline;
+    private LengthRangeProperty inlineProgressionDimension;
+    private KeepProperty keepTogether;
     private SpaceProperty lineHeight;
+    private int overflow;
+    private Numeric referenceOrientation;
+    private int writingMode;
     // Unused but valid items, commented out for performance:
-    //     private CommonBorderPaddingBackground commonBorderPaddingBackground;
-    //     private CommonMarginInline commonMarginInline;
     //     private CommonRelativePosition commonRelativePosition;
-    //     private LengthRangeProperty blockProgressionDimension;
     //     private int displayAlign;
     //     private Length height;
-    //     private LengthRangeProperty inlineProgressionDimension;
-    //     private KeepProperty keepTogether;
     //     private KeepProperty keepWithNext;
     //     private KeepProperty keepWithPrevious;
-    //     private int overflow;
-    //     private Numeric referenceOrientation;
     //     private Length width;
-    //     private int writingMode;
     // End of property values
 
     /** used for FO validation */
     private boolean blockItemFound = false;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public InlineContainer(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         alignmentAdjust = pList.get(PR_ALIGNMENT_ADJUST).getLength();
         alignmentBaseline = pList.get(PR_ALIGNMENT_BASELINE).getEnum();
         baselineShift = pList.get(PR_BASELINE_SHIFT).getLength();
-        // clip = pList.get(PR_CLIP);
+        blockProgressionDimension = pList.get(PR_BLOCK_PROGRESSION_DIMENSION).getLengthRange();
+        commonBorderPaddingBackground = pList.getBorderPaddingBackgroundProps();
+        commonMarginInline = pList.getMarginInlineProps();
+        clip = pList.get(PR_CLIP).getEnum();
         dominantBaseline = pList.get(PR_DOMINANT_BASELINE).getEnum();
+        inlineProgressionDimension = pList.get(PR_INLINE_PROGRESSION_DIMENSION).getLengthRange();
+        keepTogether = pList.get(PR_KEEP_TOGETHER).getKeep();
         lineHeight = pList.get(PR_LINE_HEIGHT).getSpace();
+        overflow = pList.get(PR_OVERFLOW).getEnum();
+        referenceOrientation = pList.get(PR_REFERENCE_ORIENTATION).getNumeric();
+        writingMode = pList.get(PR_WRITING_MODE).getEnum();
     }
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: marker* (%block;)+
+     * <br>XSL Content Model: marker* (%block;)+
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -100,50 +114,83 @@ public class InlineContainer extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         if (!blockItemFound) {
             missingChildElementError("marker* (%block;)+");
         }
     }
 
-    /**
-     * @return the "alignment-adjust" property
-     */
+    /** @return the "alignment-adjust" property */
     public Length getAlignmentAdjust() {
         return alignmentAdjust;
     }
     
-    /**
-     * @return the "alignment-baseline" property
-     */
+    /** @return the "alignment-baseline" property */
     public int getAlignmentBaseline() {
         return alignmentBaseline;
     }
     
-    /**
-     * @return the "baseline-shift" property
-     */
+    /** @return the "baseline-shift" property */
     public Length getBaselineShift() {
         return baselineShift;
     }
     
-    /**
-     * @return the "dominant-baseline" property
-     */
+    /** @return the "block-progression-dimension" property */
+    public LengthRangeProperty getBlockProgressionDimension() {
+        return blockProgressionDimension;
+    }
+    
+    /** @return the "clip" property */
+    public int getClip() {
+        return clip;
+    }
+    
+    /**@return Returns the {@link CommonBorderPaddingBackground} */
+    public CommonBorderPaddingBackground getCommonBorderPaddingBackground() {
+        return this.commonBorderPaddingBackground;
+    }
+
+    /** @return Returns the {@link CommonMarginInline} */
+    public CommonMarginInline getCommonMarginInline() {
+        return this.commonMarginInline;
+    }
+
+    /** @return the "dominant-baseline" property */
     public int getDominantBaseline() {
         return dominantBaseline;
     }
     
-    /**
-     * @return the "line-height" property.
-     */
+    /** @return the "keep-together" property */
+    public KeepProperty getKeepTogether() {
+        return keepTogether;
+    }
+    
+    /** @return the "inline-progression-dimension" property */
+    public LengthRangeProperty getInlineProgressionDimension() {
+        return inlineProgressionDimension;
+    }
+    
+    /** @return the "line-height" property */
     public SpaceProperty getLineHeight() {
         return lineHeight;
     }
 
+    /** @return the "overflow" property */
+    public int getOverflow() {
+        return overflow;
+    }
+    
+    /** @return the "reference-orientation" property */
+    public int getReferenceOrientation() {
+        return referenceOrientation.getValue();
+    }
+    
+    /** @return the "writing-mode" property */
+    public int getWritingMode() {
+        return writingMode;
+    }
+    
     /** {@inheritDoc} */
     public String getLocalName() {
         return "inline-container";
@@ -151,6 +198,7 @@ public class InlineContainer extends FObj {
     
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_INLINE_CONTAINER}
      */
     public int getNameId() {
         return FO_INLINE_CONTAINER;
diff --git a/src/java/org/apache/fop/fo/flow/InlineLevel.java b/src/java/org/apache/fop/fo/flow/InlineLevel.java
index 096a2ed66..92af98d3c 100644
--- a/src/java/org/apache/fop/fo/flow/InlineLevel.java
+++ b/src/java/org/apache/fop/fo/flow/InlineLevel.java
@@ -25,8 +25,6 @@ import org.apache.fop.apps.FOPException;
 import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.FObjMixed;
 import org.apache.fop.fo.PropertyList;
-import org.apache.fop.fo.properties.CommonAccessibility;
-import org.apache.fop.fo.properties.CommonAural;
 import org.apache.fop.fo.properties.CommonBorderPaddingBackground;
 import org.apache.fop.fo.properties.CommonFont;
 import org.apache.fop.fo.properties.CommonMarginInline;
@@ -40,71 +38,69 @@ import org.apache.fop.fo.properties.SpaceProperty;
 public abstract class InlineLevel extends FObjMixed {
     
     // The value of properties relevant for inline-level FOs.
-    protected CommonBorderPaddingBackground commonBorderPaddingBackground;
-    protected CommonAccessibility commonAccessibility;
-    protected CommonMarginInline commonMarginInline;
-    protected CommonAural commonAural;
-    protected CommonFont commonFont;
-    protected Color color;
-    protected SpaceProperty lineHeight;
-    protected int visibility;
+    private CommonBorderPaddingBackground commonBorderPaddingBackground;
+    private CommonMarginInline commonMarginInline;
+    private CommonFont commonFont;
+    private Color color;
+    private KeepProperty keepWithNext;
+    private KeepProperty keepWithPrevious;
+    private SpaceProperty lineHeight;
     // End of property values
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     protected InlineLevel(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         commonBorderPaddingBackground = pList.getBorderPaddingBackgroundProps();
-        commonAccessibility = pList.getAccessibilityProps();
         commonMarginInline = pList.getMarginInlineProps();
-        commonAural = pList.getAuralProps();
         commonFont = pList.getFontProps();
         color = pList.get(PR_COLOR).getColor(getUserAgent());
+        keepWithNext = pList.get(PR_KEEP_WITH_NEXT).getKeep();
+        keepWithPrevious = pList.get(PR_KEEP_WITH_PREVIOUS).getKeep();
         lineHeight = pList.get(PR_LINE_HEIGHT).getSpace();
-        visibility = pList.get(PR_VISIBILITY).getEnum();
     }
 
-    /**
-     * @return the Common Margin Properties-Inline.
-     */
+    /** @return the {@link CommonMarginInline} */
     public CommonMarginInline getCommonMarginInline() {
         return commonMarginInline;
     }
 
-    /**
-     * @return the Common Border, Padding, and Background Properties.
-     */
+    /** @return the {@link CommonBorderPaddingBackground} */
     public CommonBorderPaddingBackground getCommonBorderPaddingBackground() {
         return commonBorderPaddingBackground;
     } 
 
-    /**
-     * @return the Common Font Properties.
-     */
+    /** @return the {@link CommonFont} */
     public CommonFont getCommonFont() {
         return commonFont;
     }
 
-    /**
-     * @return the "color" property.
-     */
+    /** @return the "color" property */
     public Color getColor() {
         return color;
     }
 
-    /**
-     * @return the "line-height" property
-     */
+    /** @return the "line-height" property */
     public SpaceProperty getLineHeight() {
         return lineHeight;
     }
     
+    /** @return the "keep-with-next" property */
+    public KeepProperty getKeepWithNext() {
+        return keepWithNext;
+    }
+    
+    /** @return the "keep-with-previous" property */
+    public KeepProperty getKeepWithPrevious() {
+        return keepWithPrevious;
+    }
+    
 }
diff --git a/src/java/org/apache/fop/fo/flow/InstreamForeignObject.java b/src/java/org/apache/fop/fo/flow/InstreamForeignObject.java
index 802f59c30..3583087d4 100644
--- a/src/java/org/apache/fop/fo/flow/InstreamForeignObject.java
+++ b/src/java/org/apache/fop/fo/flow/InstreamForeignObject.java
@@ -33,7 +33,8 @@ import org.apache.fop.fo.ValidationException;
 import org.apache.fop.fo.XMLObj;
 
 /**
- * Class modelling the fo:instream-foreign-object object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_instream-foreign-object">
+ * <code>fo:instream-foreign-object</code></a> object.
  * This is an atomic inline object that contains XML data.
  */
 public class InstreamForeignObject extends AbstractGraphics {
@@ -45,13 +46,14 @@ public class InstreamForeignObject extends AbstractGraphics {
     //Additional value
     private Point2D intrinsicDimensions;
     private boolean instrisicSizeDetermined;
-    
+
     private Length intrinsicAlignmentAdjust;
     
     /**
-     * constructs an instream-foreign-object object (called by Maker).
+     * Constructs an instream-foreign-object object 
+     * (called by {@link org.apache.fop.fo.ElementMapping.Maker}).
      *
-     * @param parent the parent formatting object
+     * @param parent the parent {@link FONode}
      */
     public InstreamForeignObject(FONode parent) {
         super(parent);
@@ -59,7 +61,8 @@ public class InstreamForeignObject extends AbstractGraphics {
 
     /**
      * Make sure content model satisfied, if so then tell the
-     * FOEventHandler that we are at the end of the flow.
+     * {@link org.apache.fop.fo.FOEventHandler} that we are at 
+     * the end of the instream-foreign-object.
      * {@inheritDoc}
      */
     protected void endOfNode() throws FOPException {
@@ -71,10 +74,10 @@ public class InstreamForeignObject extends AbstractGraphics {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: one (1) non-XSL namespace child
+     * <br>XSL Content Model: one (1) non-XSL namespace child
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
-                throws ValidationException {
+        throws ValidationException {
         if (FO_URI.equals(nsURI)) {
             invalidChildError(loc, nsURI, localName);
         } else if (firstChild != null) {
@@ -87,7 +90,10 @@ public class InstreamForeignObject extends AbstractGraphics {
         return "instream-foreign-object";
     }
     
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_INSTREAM_FOREIGN_OBJECT}
+     */
     public int getNameId() {
         return FO_INSTREAM_FOREIGN_OBJECT;
     }
@@ -139,7 +145,7 @@ public class InstreamForeignObject extends AbstractGraphics {
         super.addChildNode(child);
     }
 
-    /** @return the XMLObj child node of the instream-foreign-object. */
+    /** @return the {@link XMLObj} child node of the instream-foreign-object. */
     public XMLObj getChildXMLObj() {
         return (XMLObj) firstChild;
     }
diff --git a/src/java/org/apache/fop/fo/flow/Leader.java b/src/java/org/apache/fop/fo/flow/Leader.java
index 82584b614..b73534d87 100644
--- a/src/java/org/apache/fop/fo/flow/Leader.java
+++ b/src/java/org/apache/fop/fo/flow/Leader.java
@@ -26,8 +26,9 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.properties.LengthRangeProperty;
 
 /**
- * Class modelling fo:leader object.
- * The main property of fo:leader is leader-pattern.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_leader">
+ * <code>fo:leader</code></a> object.
+ * The main property of <code>fo:leader</code> is leader-pattern.
  * The following patterns are treated: rule, space, dots and use-content.
  * @todo implement validateChildNode()
  */
@@ -53,15 +54,15 @@ public class Leader extends InlineLevel {
     // End of property values
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public Leader(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         alignmentAdjust = pList.get(PR_ALIGNMENT_ADJUST).getLength();
@@ -95,72 +96,52 @@ public class Leader extends InlineLevel {
         // textShadow = pList.get(PR_TEXT_SHADOW);
     }
 
-    /**
-     * @return the "rule-style" property.
-     */
+    /** @return the "rule-style" property */
     public int getRuleStyle() {
         return ruleStyle;
     }
 
-    /**
-     * @return the "rule-thickness" property.
-     */
+    /** @return the "rule-thickness" property */
     public Length getRuleThickness() {
         return ruleThickness;
     }
 
-    /**
-     * @return the "leader-alignment" property.
-     */
+    /** @return the "leader-alignment" property */
     public int getLeaderAlignment() {
         return leaderAlignment;
     }
 
-    /**
-     * @return the "leader-length" property.
-     */
+    /** @return the "leader-length" property */
     public LengthRangeProperty getLeaderLength() {
         return leaderLength;
     }
 
-    /**
-     * @return the "leader-pattern" property.
-     */
+    /** @return the "leader-pattern" property */
     public int getLeaderPattern() {
         return leaderPattern;
     }
 
-    /**
-     * @return the "leader-pattern-width" property.
-     */
+    /** @return the "leader-pattern-width" property */
     public Length getLeaderPatternWidth() {
         return leaderPatternWidth;
     }
 
-    /**
-     * @return the "alignment-adjust" property
-     */
+    /** @return the "alignment-adjust" property */
     public Length getAlignmentAdjust() {
         return alignmentAdjust;
     }
     
-    /**
-     * @return the "alignment-baseline" property
-     */
+    /** @return the "alignment-baseline" property */
     public int getAlignmentBaseline() {
         return alignmentBaseline;
     }
     
-    /**
-     * @return the "baseline-shift" property
-     */
+    /** @return the "baseline-shift" property */
     public Length getBaselineShift() {
         return baselineShift;
     }
     
-    /**
-     * @return the "dominant-baseline" property
-     */
+    /** @return the "dominant-baseline" property */
     public int getDominantBaseline() {
         return dominantBaseline;
     }
@@ -172,6 +153,7 @@ public class Leader extends InlineLevel {
 
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_LEADER}
      */
     public int getNameId() {
         return FO_LEADER;
diff --git a/src/java/org/apache/fop/fo/flow/ListBlock.java b/src/java/org/apache/fop/fo/flow/ListBlock.java
index a196e92de..8c7777e6a 100644
--- a/src/java/org/apache/fop/fo/flow/ListBlock.java
+++ b/src/java/org/apache/fop/fo/flow/ListBlock.java
@@ -32,7 +32,8 @@ import org.apache.fop.fo.properties.CommonMarginBlock;
 import org.apache.fop.fo.properties.KeepProperty;
 
 /**
- * Class modelling the fo:list-block object.
+ * Class modelling the <a href=http://www.w3.org/TR/xsl/#fo_list-block">
+ * <code>fo:list-block</code></a> object.
  */
 public class ListBlock extends FObj {
     // The value of properties relevant for fo:list-block.
@@ -60,15 +61,15 @@ public class ListBlock extends FObj {
     private boolean hasListItem = false;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public ListBlock(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         commonBorderPaddingBackground = pList.getBorderPaddingBackgroundProps();
@@ -83,17 +84,16 @@ public class ListBlock extends FObj {
         orphanContentLimit = pList.get(PR_X_ORPHAN_CONTENT_LIMIT).getLength();
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void startOfNode() throws FOPException {
         super.startOfNode();
         getFOEventHandler().startList(this);
     }
     
     /**
-     * Make sure content model satisfied, if so then tell the
-     * FOEventHandler that we are at the end of the flow.
+     * Make sure the content model is satisfied, if so then tell the
+     * {@link org.apache.fop.fo.FOEventHandler} that we are at the end 
+     * of the list-block.
      * {@inheritDoc}
      */
     protected void endOfNode() throws FOPException {
@@ -105,7 +105,7 @@ public class ListBlock extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: marker* (list-item)+
+     * <br>XSL Content Model: marker* (list-item)+
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
             throws ValidationException {
@@ -122,30 +122,22 @@ public class ListBlock extends FObj {
         }
     }
 
-    /**
-     * @return the Common Margin Properties-Block.
-     */
+    /** @return the {@link CommonMarginBlock} */
     public CommonMarginBlock getCommonMarginBlock() {
         return commonMarginBlock;
     }
 
-    /**
-     * @return the Common Border, Padding, and Background Properties.
-     */
+    /** @return the {@link CommonBorderPaddingBackground} */
     public CommonBorderPaddingBackground getCommonBorderPaddingBackground() {
         return commonBorderPaddingBackground;
     }
 
-    /**
-     * @return the "break-after" property.
-     */
+    /** @return the "break-after" property */
     public int getBreakAfter() {
         return breakAfter;
     }
 
-    /**
-     * @return the "break-before" property.
-     */
+    /** @return the "break-before" property */
     public int getBreakBefore() {
         return breakBefore;
     }
@@ -180,7 +172,10 @@ public class ListBlock extends FObj {
         return "list-block";
     }
     
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_LIST_BLOCK}
+     */
     public int getNameId() {
         return FO_LIST_BLOCK;
     }
diff --git a/src/java/org/apache/fop/fo/flow/ListItem.java b/src/java/org/apache/fop/fo/flow/ListItem.java
index cf0e05c56..398d91558 100644
--- a/src/java/org/apache/fop/fo/flow/ListItem.java
+++ b/src/java/org/apache/fop/fo/flow/ListItem.java
@@ -31,7 +31,8 @@ import org.apache.fop.fo.properties.CommonMarginBlock;
 import org.apache.fop.fo.properties.KeepProperty;
 
 /**
- * Class modelling the fo:list-item object.
+ * Class modelling the <a href=http://www.w3.org/TR/xsl/#fo_list-item">
+ * <code>fo:list-item</code></a> object.
  */
 public class ListItem extends FObj {
     // The value of properties relevant for fo:list-item.
@@ -54,15 +55,15 @@ public class ListItem extends FObj {
     private ListItemBody body = null;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public ListItem(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         commonBorderPaddingBackground = pList.getBorderPaddingBackgroundProps();
@@ -74,17 +75,13 @@ public class ListItem extends FObj {
         keepWithPrevious = pList.get(PR_KEEP_WITH_PREVIOUS).getKeep();
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void startOfNode() throws FOPException {
         super.startOfNode();
         getFOEventHandler().startListItem(this);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         if (label == null || body == null) {
             missingChildElementError("marker* (list-item-label,list-item-body)");
@@ -94,7 +91,7 @@ public class ListItem extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: marker* (list-item-label,list-item-body)
+     * <br>XSL Content Model: marker* (list-item-label,list-item-body)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
         throws ValidationException {
@@ -125,7 +122,7 @@ public class ListItem extends FObj {
      *    (i.e., add to childNodes instead)
      */
     public void addChildNode(FONode child) {
-        int nameId = ((FObj)child).getNameId();
+        int nameId = child.getNameId();
         
         if (nameId == FO_LIST_ITEM_LABEL) {
             label = (ListItemLabel) child;
@@ -136,52 +133,42 @@ public class ListItem extends FObj {
         }
     }
 
-    /**
-     * @return the Common Margin Properties-Block.
-     */
+    /** @return the {@link CommonMarginBlock} */
     public CommonMarginBlock getCommonMarginBlock() {
         return commonMarginBlock;
     }
 
-    /**
-     * @return the Common Border, Padding, and Background Properties.
-     */
+    /** @return the {@link CommonBorderPaddingBackground} */
     public CommonBorderPaddingBackground getCommonBorderPaddingBackground() {
         return commonBorderPaddingBackground;
     }
 
-    /**
-     * @return the "break-after" property.
-     */
+    /** @return the "break-after" property */
     public int getBreakAfter() {
         return breakAfter;
     }
 
-    /**
-     * @return the "break-before" property.
-     */
+    /** @return the "break-before" property */
     public int getBreakBefore() {
         return breakBefore;
     }
 
-    /** @return the "keep-with-next" property.  */
+    /** @return the "keep-with-next" property */
     public KeepProperty getKeepWithNext() {
         return keepWithNext;
     }
 
-    /** @return the "keep-with-previous" property.  */
+    /** @return the "keep-with-previous" property  */
     public KeepProperty getKeepWithPrevious() {
         return keepWithPrevious;
     }
 
-    /** @return the "keep-together" property.  */
+    /** @return the "keep-together" property  */
     public KeepProperty getKeepTogether() {
         return keepTogether;
     }
 
-    /**
-     * @return the label of the list item
-     */
+    /** @return the label of the list item */
     public ListItemLabel getLabel() {
         return label;
     }
@@ -200,6 +187,7 @@ public class ListItem extends FObj {
     
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_LIST_ITEM}
      */
     public int getNameId() {
         return FO_LIST_ITEM;
diff --git a/src/java/org/apache/fop/fo/flow/ListItemBody.java b/src/java/org/apache/fop/fo/flow/ListItemBody.java
index 3d5d4562e..226cacd12 100644
--- a/src/java/org/apache/fop/fo/flow/ListItemBody.java
+++ b/src/java/org/apache/fop/fo/flow/ListItemBody.java
@@ -23,7 +23,8 @@ import org.apache.fop.apps.FOPException;
 import org.apache.fop.fo.FONode;
 
 /**
- * Class modelling the fo:list-item-body object.
+ * Class modelling the <a href=http://www.w3.org/TR/xsl/#fo_list-item-body">
+ * <code>fo:list-item-body object</code></a>.
  */
 public class ListItemBody extends AbstractListItemPart {
 
@@ -34,17 +35,13 @@ public class ListItemBody extends AbstractListItemPart {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void startOfNode() throws FOPException {
         super.startOfNode();
         getFOEventHandler().startListBody();
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         super.endOfNode();
         getFOEventHandler().endListBody();
@@ -57,6 +54,7 @@ public class ListItemBody extends AbstractListItemPart {
     
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_LIST_ITEM_BODY}
      */
     public int getNameId() {
         return FO_LIST_ITEM_BODY;
diff --git a/src/java/org/apache/fop/fo/flow/ListItemLabel.java b/src/java/org/apache/fop/fo/flow/ListItemLabel.java
index dcdf1b3a1..7fbbe77d3 100644
--- a/src/java/org/apache/fop/fo/flow/ListItemLabel.java
+++ b/src/java/org/apache/fop/fo/flow/ListItemLabel.java
@@ -23,28 +23,27 @@ import org.apache.fop.apps.FOPException;
 import org.apache.fop.fo.FONode;
 
 /**
- * Class modelling the fo:list-item-label object.
+ * Class modelling the <a href=http://www.w3.org/TR/xsl/#fo_list-item-label">
+ * <code>fo:list-item-label</code></a> object.
  */
 public class ListItemLabel extends AbstractListItemPart {
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public ListItemLabel(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void startOfNode() throws FOPException {
         super.startOfNode();
         getFOEventHandler().startListLabel();
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         super.endOfNode();
         getFOEventHandler().endListLabel();
@@ -57,6 +56,7 @@ public class ListItemLabel extends AbstractListItemPart {
     
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_LIST_ITEM_LABEL}
      */
     public int getNameId() {
         return FO_LIST_ITEM_LABEL;
diff --git a/src/java/org/apache/fop/fo/flow/Marker.java b/src/java/org/apache/fop/fo/flow/Marker.java
index 168b18180..7eda2101e 100644
--- a/src/java/org/apache/fop/fo/flow/Marker.java
+++ b/src/java/org/apache/fop/fo/flow/Marker.java
@@ -36,7 +36,8 @@ import org.apache.fop.fo.ValidationException;
 import org.apache.fop.fo.properties.Property;
 
 /**
- * Class modelling the fo:marker object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_marker">
+ * <code>fo:marker<code></a> object.
  */
 public class Marker extends FObjMixed {
     // The value of properties relevant for fo:marker.
@@ -48,15 +49,14 @@ public class Marker extends FObjMixed {
 
     /**
      * Create a marker fo.
-     * @param parent the parent fo node
+     * 
+     * @param parent the parent {@link FONode}
      */
     public Marker(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         if (findAncestor(FO_FLOW) < 0) {
             invalidChildError(locator, getParent().getName(), FO_URI, getName(), 
@@ -71,9 +71,11 @@ public class Marker extends FObjMixed {
     }
     
     /**
-     * retrieve the property list of foNode
-     * @param foNode the FO node whose property list is requested
-     * @return the MarkerPropertyList of foNode
+     * Retrieve the property list of the given {@link FONode} 
+     * descendant
+     * 
+     * @param foNode the {@link FONode} whose property list is requested
+     * @return the {@link MarkerPropertyList} for the given node
      */
     protected MarkerPropertyList getPropertyListFor(FONode foNode) {
         return (MarkerPropertyList) 
@@ -104,10 +106,10 @@ public class Marker extends FObjMixed {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: (#PCDATA|%inline;|%block;)*
-     * Additionally: "An fo:marker may contain any formatting objects that 
+     * <br>XSL Content Model: (#PCDATA|%inline;|%block;)*
+     * <br><i>Additionally: "An fo:marker may contain any formatting objects that
      * are permitted as a replacement of any fo:retrieve-marker that retrieves
-     * the fo:marker's children."
+     * the fo:marker's children."</i>
      * @todo implement "additional" constraint, possibly within fo:retrieve-marker
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
@@ -119,13 +121,12 @@ public class Marker extends FObjMixed {
         }
     }
     
+    /** {@inheritDoc} */
     protected boolean inMarker() {
         return true;
     }
     
-    /**
-     * Return the "marker-class-name" property.
-     */
+    /** @return the "marker-class-name" property */
     public String getMarkerClassName() {
         return markerClassName;
     }
@@ -137,6 +138,7 @@ public class Marker extends FObjMixed {
     
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_MARKER}
      */
     public int getNameId() {
         return FO_MARKER;
@@ -150,7 +152,7 @@ public class Marker extends FObjMixed {
     }
 
     /**
-     * An implementation of PropertyList which only stores the explicitly
+     * An implementation of {@link PropertyList} which only stores the explicitly
      * specified properties/attributes as bundles of name-value-namespace
      * strings
      */
@@ -163,7 +165,7 @@ public class Marker extends FObjMixed {
         /**
          * Overriding default constructor
          * 
-         * @param fobj  the FObj to attach
+         * @param fobj  the {@link FObj} to attach
          * @param parentPropertyList    ignored
          */
         public MarkerPropertyList(FObj fobj, PropertyList parentPropertyList) {
@@ -175,10 +177,10 @@ public class Marker extends FObjMixed {
         }
         
         /**
-         * Override that doesn't convert the attributes to Property instances,
-         * but simply stores the attributes for later processing;
+         * Override that doesn't convert the attributes to {@link Property}
+         * instances, but simply stores the attributes for later processing.
          * 
-         * @see org.apache.fop.fo.PropertyList#addAttributesToList(Attributes)
+         * {@inheritDoc}
          */
         public void addAttributesToList(Attributes attributes) 
                     throws ValidationException {
@@ -201,23 +203,17 @@ public class Marker extends FObjMixed {
             }
         }
         
-        /**
-         * Null implementation; not used by this type of PropertyList
-         */
+        /** Null implementation; not used by this type of {@link PropertyList} */
         public void putExplicit(int propId, Property value) {
             //nop
         }
 
-        /**
-         * Null implementation; not used by this type of PropertyList
-         */
+        /** Null implementation; not used by this type of {@link PropertyList} */
         public Property getExplicit(int propId) {
             return null;
         }
 
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public int getLength() {
             if (attribs == null) {
                 return 0;
@@ -226,9 +222,7 @@ public class Marker extends FObjMixed {
             }
         }
 
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public String getURI(int index) {
             if (attribs != null 
                     && index < attribs.length
@@ -240,9 +234,7 @@ public class Marker extends FObjMixed {
             }
         }
 
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public String getLocalName(int index) {
             if (attribs != null 
                     && index < attribs.length
@@ -254,9 +246,7 @@ public class Marker extends FObjMixed {
             }
         }
 
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public String getQName(int index) {
             if (attribs != null 
                     && index < attribs.length
@@ -268,16 +258,12 @@ public class Marker extends FObjMixed {
             }
         }
 
-        /**
-         * Default implementation; not used
-         */
+        /** Default implementation; not used */
         public String getType(int index) {
             return "CDATA";
         }
 
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public String getValue(int index) {
             if (attribs != null 
                     && index < attribs.length
@@ -289,9 +275,7 @@ public class Marker extends FObjMixed {
             }
         }
 
-        /**
-         * {@inheritDoc} 
-         */
+        /** {@inheritDoc} */
         public int getIndex(String name, String namespace) {
             int index = -1;
             if (attribs != null && name != null && namespace != null) {
@@ -306,9 +290,7 @@ public class Marker extends FObjMixed {
             return index;
         }
 
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public int getIndex(String qname) {
             int index = -1;
             if (attribs != null && qname != null) {
@@ -322,23 +304,17 @@ public class Marker extends FObjMixed {
             return index;
         }
 
-        /**
-         * Default implementation; not used
-         */
+        /** Default implementation; not used */
         public String getType(String name, String namespace) {
             return "CDATA";
         }
 
-        /**
-         * Default implementation; not used
-         */
+        /** Default implementation; not used */
         public String getType(String qname) {
             return "CDATA";
         }
 
-        /**
-         * {@inheritDoc} 
-         */
+        /** {@inheritDoc} */
         public String getValue(String name, String namespace) {
             int index = getIndex(name, namespace);
             if (index > 0) {
@@ -347,9 +323,7 @@ public class Marker extends FObjMixed {
             return null;
         }
 
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public String getValue(String qname) {
             int index = getIndex(qname);
             if (index > 0) {
@@ -359,9 +333,7 @@ public class Marker extends FObjMixed {
         }
     }
     
-    /**
-     * Convenience inner class
-     */
+    /** Convenience inner class */
     private static final class MarkerAttribute {
         
         private static Map attributeCache = 
@@ -390,7 +362,9 @@ public class Marker extends FObjMixed {
         /**
          * Convenience method, reduces the number
          * of distinct MarkerAttribute instances
-         * 
+         *
+         * @param namespace the attribute namespace
+         * @param qname the fully qualified name of the attribute
          * @param name  the attribute name
          * @param value the attribute value
          * @return the single MarkerAttribute instance corresponding to 
@@ -409,9 +383,7 @@ public class Marker extends FObjMixed {
             }
         }
         
-        /**
-         * {@inheritDoc}
-         */
+        /** {@inheritDoc} */
         public boolean equals(Object o) {
             if (o instanceof MarkerAttribute) {
                 MarkerAttribute attr = (MarkerAttribute) o;
diff --git a/src/java/org/apache/fop/fo/flow/MultiCase.java b/src/java/org/apache/fop/fo/flow/MultiCase.java
index e568fba46..284d82d63 100644
--- a/src/java/org/apache/fop/fo/flow/MultiCase.java
+++ b/src/java/org/apache/fop/fo/flow/MultiCase.java
@@ -25,7 +25,8 @@ import org.apache.fop.fo.FObj;
 import org.apache.fop.fo.PropertyList;
 
 /**
- * Class modelling the fo:multi-case object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_multi-case">
+ * <code>fo:multi-case</code></a> object.
  * @todo implement validateChildNode()
  */
 public class MultiCase extends FObj {
@@ -40,7 +41,9 @@ public class MultiCase extends FObj {
     static boolean notImplementedWarningGiven = false;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public MultiCase(FONode parent) {
         super(parent);
@@ -52,9 +55,7 @@ public class MultiCase extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         startingState = pList.get(PR_STARTING_STATE).getEnum();
@@ -62,9 +63,7 @@ public class MultiCase extends FObj {
         // caseTitle = pList.get(PR_CASE_TITLE);
     }
 
-    /**
-     * Return the "starting-state" property.
-     */
+    /** @return the "starting-state" property */
     public int getStartingState() {
         return startingState;
     }
@@ -76,6 +75,7 @@ public class MultiCase extends FObj {
 
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_MULTI_CASE}
      */
     public int getNameId() {
         return FO_MULTI_CASE;
diff --git a/src/java/org/apache/fop/fo/flow/MultiProperties.java b/src/java/org/apache/fop/fo/flow/MultiProperties.java
index bd3bd893e..ef015a9c1 100644
--- a/src/java/org/apache/fop/fo/flow/MultiProperties.java
+++ b/src/java/org/apache/fop/fo/flow/MultiProperties.java
@@ -28,7 +28,8 @@ import org.apache.fop.fo.FObj;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * Class modelling the fo:multi-properties object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_multi-properties">
+ * <code>fo:multi-properties</code></a> object.
  */
 public class MultiProperties extends FObj {
     // The value of properties relevant for fo:multi-properties.
@@ -43,7 +44,9 @@ public class MultiProperties extends FObj {
     boolean hasWrapper = false;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public MultiProperties(FONode parent) {
         super(parent);
@@ -55,9 +58,7 @@ public class MultiProperties extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         if (!hasMultiPropertySet || !hasWrapper) {
             missingChildElementError("(multi-property-set+, wrapper)");
@@ -66,7 +67,7 @@ public class MultiProperties extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: (multi-property-set+, wrapper)
+     * <br>XSL Content Model: (multi-property-set+, wrapper)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
         throws ValidationException {
@@ -96,6 +97,7 @@ public class MultiProperties extends FObj {
 
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_MULTI_PROPERTIES}
      */
     public int getNameId() {
         return FO_MULTI_PROPERTIES;
diff --git a/src/java/org/apache/fop/fo/flow/MultiPropertySet.java b/src/java/org/apache/fop/fo/flow/MultiPropertySet.java
index caa31f7b9..0736976b4 100644
--- a/src/java/org/apache/fop/fo/flow/MultiPropertySet.java
+++ b/src/java/org/apache/fop/fo/flow/MultiPropertySet.java
@@ -29,7 +29,8 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * Class modelling the fo:multi-property-set object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_multi-property-set">
+ * <code>fo:multi-property-set</code></a> object.
  */
 public class MultiPropertySet extends FObj {
     // The value of properties relevant for fo:multi-property-set.
@@ -39,7 +40,9 @@ public class MultiPropertySet extends FObj {
     static boolean notImplementedWarningGiven = false;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public MultiPropertySet(FONode parent) {
         super(parent);
@@ -51,9 +54,7 @@ public class MultiPropertySet extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         // activeState = pList.get(PR_ACTIVE_STATE);
@@ -61,7 +62,7 @@ public class MultiPropertySet extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: empty
+     * <br>XSL Content Model: empty
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -77,6 +78,7 @@ public class MultiPropertySet extends FObj {
     
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_MULTI_PROPERTY_SET}
      */
     public int getNameId() {
         return FO_MULTI_PROPERTY_SET;
diff --git a/src/java/org/apache/fop/fo/flow/MultiSwitch.java b/src/java/org/apache/fop/fo/flow/MultiSwitch.java
index 03f404aa3..81cb2aff9 100644
--- a/src/java/org/apache/fop/fo/flow/MultiSwitch.java
+++ b/src/java/org/apache/fop/fo/flow/MultiSwitch.java
@@ -29,7 +29,8 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * Class modelling the fo:multi-switch object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_multi-switch">
+ * <code>fo:multi-switch</code></a> object.
  */
 public class MultiSwitch extends FObj {
     // The value of properties relevant for fo:multi-switch.
@@ -41,7 +42,9 @@ public class MultiSwitch extends FObj {
     static boolean notImplementedWarningGiven = false;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public MultiSwitch(FONode parent) {
         super(parent);
@@ -53,18 +56,14 @@ public class MultiSwitch extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         // autoRestore = pList.get(PR_AUTO_RESTORE);
     }
 
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         if (firstChild == null) {
             missingChildElementError("(multi-case+)");
@@ -73,7 +72,7 @@ public class MultiSwitch extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: (multi-case+)
+     * <br>XSL Content Model: (multi-case+)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -91,6 +90,7 @@ public class MultiSwitch extends FObj {
 
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_MULTI_SWITCH}
      */
     public int getNameId() {
         return FO_MULTI_SWITCH;
diff --git a/src/java/org/apache/fop/fo/flow/MultiToggle.java b/src/java/org/apache/fop/fo/flow/MultiToggle.java
index 66442c2a7..bcb1f806a 100644
--- a/src/java/org/apache/fop/fo/flow/MultiToggle.java
+++ b/src/java/org/apache/fop/fo/flow/MultiToggle.java
@@ -30,7 +30,8 @@ import org.apache.fop.fo.ValidationException;
 
 
 /**
- * Class modelling the fo:multi-toggle property.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_multi-toggle">
+ * <code>fo:multi-toggle<code></a> property.
  */
 public class MultiToggle extends FObj {
     // The value of properties relevant for fo:multi-toggle (commented out for performance).
@@ -41,7 +42,9 @@ public class MultiToggle extends FObj {
     static boolean notImplementedWarningGiven = false;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public MultiToggle(FONode parent) {
         super(parent);
@@ -53,9 +56,7 @@ public class MultiToggle extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         // prSwitchTo = pList.get(PR_SWITCH_TO);
 
@@ -63,7 +64,7 @@ public class MultiToggle extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: (#PCDATA|%inline;|%block;)*
+     * <br>XSL Content Model: (#PCDATA|%inline;|%block;)*
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -81,6 +82,7 @@ public class MultiToggle extends FObj {
     
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_MULTI_TOGGLE}
      */
     public int getNameId() {
         return FO_MULTI_TOGGLE;
diff --git a/src/java/org/apache/fop/fo/flow/PageNumber.java b/src/java/org/apache/fop/fo/flow/PageNumber.java
index cc51dd28a..3b91c6b44 100644
--- a/src/java/org/apache/fop/fo/flow/PageNumber.java
+++ b/src/java/org/apache/fop/fo/flow/PageNumber.java
@@ -36,7 +36,8 @@ import org.apache.fop.fo.properties.CommonTextDecoration;
 import org.apache.fop.fo.properties.SpaceProperty;
 
 /**
- * Class modelling the fo:page-number object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_page-number">
+ * <code>fo:page-number</code></a> object.
  */
 public class PageNumber extends FObj {
     // The value of properties relevant for fo:page-number.
@@ -71,15 +72,15 @@ public class PageNumber extends FObj {
     private Color color;
     
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public PageNumber(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
         commonBorderPaddingBackground = pList.getBorderPaddingBackgroundProps();
@@ -97,24 +98,20 @@ public class PageNumber extends FObj {
         color = pList.get(Constants.PR_COLOR).getColor(getUserAgent());
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void startOfNode() throws FOPException {
         super.startOfNode();
         getFOEventHandler().startPageNumber(this);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         getFOEventHandler().endPageNumber(this);
     }
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: empty
+     * <br>XSL Content Model: empty
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -143,37 +140,27 @@ public class PageNumber extends FObj {
         return textDecoration; 
     }
 
-    /**
-     * @return the "alignment-adjust" property
-     */
+    /** @return the "alignment-adjust" property */
     public Length getAlignmentAdjust() {
         return alignmentAdjust;
     }
     
-    /**
-     * @return the "alignment-baseline" property
-     */
+    /** @return the "alignment-baseline" property */
     public int getAlignmentBaseline() {
         return alignmentBaseline;
     }
     
-    /**
-     * @return the "baseline-shift" property
-     */
+    /** @return the "baseline-shift" property */
     public Length getBaselineShift() {
         return baselineShift;
     }
     
-    /**
-     * @return the "dominant-baseline" property
-     */
+    /** @return the "dominant-baseline" property */
     public int getDominantBaseline() {
         return dominantBaseline;
     }
     
-    /**
-     * @return the "line-height" property
-     */
+    /** @return the "line-height" property */
     public SpaceProperty getLineHeight() {
         return lineHeight;
     }
@@ -183,7 +170,10 @@ public class PageNumber extends FObj {
         return "page-number";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_PAGE_NUMBER}
+     */
     public int getNameId() {
         return FO_PAGE_NUMBER;
     }
diff --git a/src/java/org/apache/fop/fo/flow/PageNumberCitation.java b/src/java/org/apache/fop/fo/flow/PageNumberCitation.java
index feea07433..b31bc9a11 100644
--- a/src/java/org/apache/fop/fo/flow/PageNumberCitation.java
+++ b/src/java/org/apache/fop/fo/flow/PageNumberCitation.java
@@ -23,7 +23,8 @@ import org.apache.fop.apps.FOPException;
 import org.apache.fop.fo.FONode;
 
 /**
- * Class modelling the fo:page-number-citation object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_page-number-citation">
+ * <code>fo:page-number-citation</code></a> object.
  * This inline fo is replaced with the text for a page number.
  * The page number used is the page that contains the start of the
  * block referenced with the ref-id attribute.
@@ -32,7 +33,8 @@ public class PageNumberCitation extends AbstractPageNumberCitation {
 
     /**
      * Main constructor
-     * @param parent FONode that is the parent of this object
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public PageNumberCitation(FONode parent) {
         super(parent);
@@ -55,7 +57,10 @@ public class PageNumberCitation extends AbstractPageNumberCitation {
         return "page-number-citation";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_PAGE_NUMBER_CITATION}
+     */
     public int getNameId() {
         return FO_PAGE_NUMBER_CITATION;
     }
diff --git a/src/java/org/apache/fop/fo/flow/PageNumberCitationLast.java b/src/java/org/apache/fop/fo/flow/PageNumberCitationLast.java
index a9b5b90df..9e98c06be 100644
--- a/src/java/org/apache/fop/fo/flow/PageNumberCitationLast.java
+++ b/src/java/org/apache/fop/fo/flow/PageNumberCitationLast.java
@@ -23,7 +23,8 @@ import org.apache.fop.apps.FOPException;
 import org.apache.fop.fo.FONode;
 
 /**
- * Class modelling the fo:page-number-citation-last object from XSL 1.1.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_page-number-citation-last">
+ * <code>fo:page-number-citation-last</code></a> object from XSL 1.1.
  * This inline fo is replaced with the text for a page number.
  * The page number used is the page that contains the end of the
  * block referenced with the ref-id attribute.
@@ -33,7 +34,8 @@ public class PageNumberCitationLast extends AbstractPageNumberCitation {
 
     /**
      * Main constructor
-     * @param parent the parent FO node
+     * 
+     * @param parent the parent {@link FONode}
      */
     public PageNumberCitationLast(FONode parent) {
         super(parent);
@@ -56,7 +58,10 @@ public class PageNumberCitationLast extends AbstractPageNumberCitation {
         return "page-number-citation-last";
     }
     
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_PAGE_NUMBER_CITATION_LAST}
+     */
     public int getNameId() {
         return FO_PAGE_NUMBER_CITATION_LAST;
     }
diff --git a/src/java/org/apache/fop/fo/flow/RetrieveMarker.java b/src/java/org/apache/fop/fo/flow/RetrieveMarker.java
index ea6b6f1c5..0283dc7da 100644
--- a/src/java/org/apache/fop/fo/flow/RetrieveMarker.java
+++ b/src/java/org/apache/fop/fo/flow/RetrieveMarker.java
@@ -21,8 +21,6 @@ package org.apache.fop.fo.flow;
 
 import java.util.Iterator;
 
-import org.xml.sax.Locator;
-
 import org.apache.fop.apps.FOPException;
 import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.FOText;
@@ -32,6 +30,7 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 import org.apache.fop.fo.flow.table.Table;
 import org.apache.fop.fo.flow.table.TableFObj;
+import org.xml.sax.Locator;
 
 /**
  * Class modelling the fo:retrieve-marker object.
@@ -48,9 +47,10 @@ public class RetrieveMarker extends FObjMixed {
     private PropertyList propertyList;
 
     /**
-     * Create a retrieve marker object.
-     * @param parent FONode that is the parent of this object
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Create a new RetrieveMarker instance that is a
+     * child of the given {@link FONode}.
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     public RetrieveMarker(FONode parent) {
         super(parent);
@@ -59,26 +59,27 @@ public class RetrieveMarker extends FObjMixed {
     /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         if (findAncestor(FO_STATIC_CONTENT) < 0) {
-            invalidChildError(locator, getParent().getName(), FO_URI, getName(), 
+            invalidChildError(locator, getParent().getName(), FO_URI, getName(),
                 "rule.retrieveMarkerDescendatOfStaticContent");
         }
 
         retrieveClassName = pList.get(PR_RETRIEVE_CLASS_NAME).getString();
         retrievePosition = pList.get(PR_RETRIEVE_POSITION).getEnum();
         retrieveBoundary = pList.get(PR_RETRIEVE_BOUNDARY).getEnum();
-        
+
         if (retrieveClassName == null || retrieveClassName.equals("")) {
             missingPropertyError("retrieve-class-name");
         }
-        
+
         propertyList = pList.getParentPropertyList();
+        super.bind(pList);
     }
-    
+
     /**
      * {@inheritDoc}
      * XSL Content Model: empty
      */
-    protected void validateChildNode(Locator loc, String nsURI, String localName) 
+    protected void validateChildNode(Locator loc, String nsURI, String localName)
                 throws ValidationException {
         if (FO_URI.equals(nsURI)) {
             invalidChildError(loc, nsURI, localName);
@@ -105,7 +106,7 @@ public class RetrieveMarker extends FObjMixed {
     public int getRetrieveBoundary() {
         return retrieveBoundary;
     }
-    
+
     private PropertyList createPropertyListFor(FObj fo, PropertyList parent) {
         return getFOEventHandler().getPropertyListMaker().make(fo, parent);
     }
@@ -120,7 +121,7 @@ public class RetrieveMarker extends FObjMixed {
                 Marker.MarkerPropertyList pList;
                 PropertyList newPropertyList = createPropertyListFor(
                             (FObj) newChild, parentPropertyList);
-                
+
                 pList = marker.getPropertyListFor(child);
                 newChild.processNode(
                         child.getLocalName(),
@@ -159,7 +160,7 @@ public class RetrieveMarker extends FObjMixed {
             }
         }
     }
-    
+
     /**
      * Clone the FO nodes in the parent iterator,
      * attach the new nodes to the new parent,
@@ -178,7 +179,7 @@ public class RetrieveMarker extends FObjMixed {
             FONode child;
             while (parentIter.hasNext()) {
                 child = (FONode) parentIter.next();
-                cloneSingleNode(child, newParent, 
+                cloneSingleNode(child, newParent,
                         marker, parentPropertyList);
             }
         }
@@ -191,14 +192,14 @@ public class RetrieveMarker extends FObjMixed {
             currentTextNode = null;
             firstChild = null;
         }
-        cloneSubtree(marker.getChildNodes(), this, 
+        cloneSubtree(marker.getChildNodes(), this,
                         marker, propertyList);
         handleWhiteSpaceFor(this);
     }
 
     /**
      * Clone the subtree of the given marker
-     * 
+     *
      * @param marker the marker that is to be cloned
      */
     public void bindMarker(Marker marker) {
@@ -213,7 +214,6 @@ public class RetrieveMarker extends FObjMixed {
         } else if (log.isDebugEnabled()) {
             log.debug("Empty marker retrieved...");
         }
-        return;
     }
 
     /** {@inheritDoc} */
@@ -221,7 +221,10 @@ public class RetrieveMarker extends FObjMixed {
         return "retrieve-marker";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_RETRIEVE_MARKER}
+     */
     public int getNameId() {
         return FO_RETRIEVE_MARKER;
     }    
diff --git a/src/java/org/apache/fop/fo/flow/Wrapper.java b/src/java/org/apache/fop/fo/flow/Wrapper.java
index 87582fb47..4b1cfeeac 100644
--- a/src/java/org/apache/fop/fo/flow/Wrapper.java
+++ b/src/java/org/apache/fop/fo/flow/Wrapper.java
@@ -28,8 +28,9 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * Class modelling the fo:wrapper object.
- * The wrapper object serves as a property holder for 
+ * Class modelling the <a href=http://www.w3.org/TR/xsl/#fo_wrapper">
+ * <code>fo:wrapper</code></a> object.
+ * The <code>fo:wrapper</code> object serves as a property holder for 
  * its child node objects.
  */
 public class Wrapper extends FObjMixed {
@@ -41,7 +42,9 @@ public class Wrapper extends FObjMixed {
     private boolean inlineChildrenAllowed = false;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Base constructor
+     * 
+     * @param parent {@link FONode} that is the parent of this object
      */
     public Wrapper(FONode parent) {
         super(parent);
@@ -101,7 +104,10 @@ public class Wrapper extends FObjMixed {
         return "wrapper";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_WRAPPER}
+     */
     public int getNameId() {
         return FO_WRAPPER;
     }
diff --git a/src/java/org/apache/fop/fo/flow/table/Table.java b/src/java/org/apache/fop/fo/flow/table/Table.java
index c1ef3857c..69d5fbb9d 100644
--- a/src/java/org/apache/fop/fo/flow/table/Table.java
+++ b/src/java/org/apache/fop/fo/flow/table/Table.java
@@ -39,7 +39,8 @@ import org.apache.fop.fo.properties.LengthRangeProperty;
 import org.apache.fop.fo.properties.TableColLength;
 
 /**
- * Class modelling the fo:table object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_table">
+ * <code>fo:table</code></a> object.
  */
 public class Table extends TableFObj implements ColumnNumberManagerHolder {
 
@@ -96,7 +97,10 @@ public class Table extends TableFObj implements ColumnNumberManagerHolder {
     private PropertyList propList;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Construct a Table instance with the given {@link FONode}
+     * as parent.
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     public Table(FONode parent) {
         super(parent);
@@ -163,7 +167,7 @@ public class Table extends TableFObj implements ColumnNumberManagerHolder {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: (marker*,table-column*,table-header?,table-footer?,table-body+)
+     * <br>XSL Content Model: (marker*,table-column*,table-header?,table-footer?,table-body+)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName)
                 throws ValidationException {
@@ -255,7 +259,7 @@ public class Table extends TableFObj implements ColumnNumberManagerHolder {
             if (!inMarker()) {
                 addColumnNode((TableColumn) child);
             } else {
-                columns.add((TableColumn) child);
+                columns.add(child);
             }
             break;
         case FO_TABLE_HEADER:
@@ -344,7 +348,6 @@ public class Table extends TableFObj implements ColumnNumberManagerHolder {
      * used for determining initial values for column-number
      * 
      * @param col   the column to add
-     * @throws FOPException
      */
     private void addColumnNode(TableColumn col) {
 
@@ -518,7 +521,10 @@ public class Table extends TableFObj implements ColumnNumberManagerHolder {
         return "table";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_TABLE}
+     */
     public int getNameId() {
         return FO_TABLE;
     }
diff --git a/src/java/org/apache/fop/fo/flow/table/TableAndCaption.java b/src/java/org/apache/fop/fo/flow/table/TableAndCaption.java
index 6dabf37db..7c45c21f2 100644
--- a/src/java/org/apache/fop/fo/flow/table/TableAndCaption.java
+++ b/src/java/org/apache/fop/fo/flow/table/TableAndCaption.java
@@ -28,7 +28,8 @@ import org.apache.fop.fo.FObj;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * Class modelling the fo:table-and-caption property.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_table-and-caption">
+ * <code>fo:table-and-caption</code></a> property.
  * @todo needs implementation
  */
 public class TableAndCaption extends FObj {
@@ -56,6 +57,8 @@ public class TableAndCaption extends FObj {
     private boolean tableFound = false;
 
     /**
+     * Create a TableAndCaption instance with the given {@link FONode}
+     * as parent.
      * @param parent FONode that is the parent of this object
      */
     public TableAndCaption(FONode parent) {
@@ -81,7 +84,7 @@ public class TableAndCaption extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: marker* table-caption? table
+     * <br>XSL Content Model: marker* table-caption? table
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -120,6 +123,7 @@ public class TableAndCaption extends FObj {
 
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_TABLE_AND_CAPTION}
      */
     public int getNameId() {
         return FO_TABLE_AND_CAPTION;
diff --git a/src/java/org/apache/fop/fo/flow/table/TableBody.java b/src/java/org/apache/fop/fo/flow/table/TableBody.java
index 4e1673568..0214e7336 100644
--- a/src/java/org/apache/fop/fo/flow/table/TableBody.java
+++ b/src/java/org/apache/fop/fo/flow/table/TableBody.java
@@ -33,7 +33,8 @@ import org.apache.fop.fo.ValidationException;
 import org.apache.fop.fo.properties.CommonBorderPaddingBackground;
 
 /**
- * Class modelling the fo:table-body object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_table-body">
+ * <code>fo:table-body</code></a> object.
  */
 public class TableBody extends TableCellContainer {
     // The value of properties relevant for fo:table-body.
@@ -63,23 +64,21 @@ public class TableBody extends TableCellContainer {
     private List rowGroups = new LinkedList();
 
     /**
+     * Create a TableBody instance with the given {@link FONode}
+     * as parent.
      * @param parent FONode that is the parent of the object
      */
     public TableBody(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         commonBorderPaddingBackground = pList.getBorderPaddingBackgroundProps();
         super.bind(pList);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void processNode(String elementName, Locator locator,
                             Attributes attlist, PropertyList pList)
                     throws FOPException {
@@ -99,17 +98,13 @@ public class TableBody extends TableCellContainer {
         super.processNode(elementName, locator, attlist, pList);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void startOfNode() throws FOPException {
         super.startOfNode();
         getFOEventHandler().startBody(this);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void endOfNode() throws FOPException {
 
         if (!inMarker()) {
@@ -150,8 +145,8 @@ public class TableBody extends TableCellContainer {
     }
 
     /**
-     * {@inheritDoc} String, String)
-     * XSL Content Model: marker* (table-row+|table-cell+)
+     * {@inheritDoc}
+     * <br>XSL Content Model: marker* (table-row+|table-cell+)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName)
         throws ValidationException {
@@ -180,9 +175,7 @@ public class TableBody extends TableCellContainer {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void addChildNode(FONode child) throws FOPException {
         if (!inMarker()) {
             switch (child.getNameId()) {
@@ -236,7 +229,9 @@ public class TableBody extends TableCellContainer {
     }
 
     /**
-     * @return the Common Border, Padding, and Background Properties.
+     * Get the {@link CommonBorderPaddingBackground} instance attached
+     * to this TableBody.
+     * @return the {@link CommonBorderPaddingBackground} instance.
      */
     public CommonBorderPaddingBackground getCommonBorderPaddingBackground() {
         return commonBorderPaddingBackground;
@@ -249,6 +244,7 @@ public class TableBody extends TableCellContainer {
 
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_TABLE_BODY}
      */
     public int getNameId() {
         return FO_TABLE_BODY;
diff --git a/src/java/org/apache/fop/fo/flow/table/TableCaption.java b/src/java/org/apache/fop/fo/flow/table/TableCaption.java
index 416ef16ed..80fccb236 100644
--- a/src/java/org/apache/fop/fo/flow/table/TableCaption.java
+++ b/src/java/org/apache/fop/fo/flow/table/TableCaption.java
@@ -30,7 +30,8 @@ import org.apache.fop.fo.ValidationException;
 
 
 /**
- * Class modelling the fo:table-caption object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_table-caption">
+ * <code>fo:table-caption</code></a> object.
  */
 public class TableCaption extends FObj {
     // The value of properties relevant for fo:table-caption.
@@ -51,7 +52,9 @@ public class TableCaption extends FObj {
     static boolean notImplementedWarningGiven = false;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Create a TableCaption instance with the given {@link FONode}
+     * as parent.
+     * @param parent {@link FONode} that is the parent of this object
      */
     public TableCaption(FONode parent) {
         super(parent);
@@ -63,16 +66,12 @@ public class TableCaption extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         super.bind(pList);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         if (firstChild == null) {
             missingChildElementError("marker* (%block;)");
@@ -81,7 +80,7 @@ public class TableCaption extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: marker* (%block;)
+     * <br>XSL Content Model: marker* (%block;)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
             throws ValidationException {
@@ -105,6 +104,7 @@ public class TableCaption extends FObj {
 
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_TABLE_CAPTION}
      */
     public int getNameId() {
         return FO_TABLE_CAPTION;
diff --git a/src/java/org/apache/fop/fo/flow/table/TableCell.java b/src/java/org/apache/fop/fo/flow/table/TableCell.java
index 78e35eb52..b1dfd86c3 100644
--- a/src/java/org/apache/fop/fo/flow/table/TableCell.java
+++ b/src/java/org/apache/fop/fo/flow/table/TableCell.java
@@ -30,7 +30,8 @@ import org.apache.fop.fo.properties.CommonBorderPaddingBackground;
 import org.apache.fop.fo.properties.LengthRangeProperty;
 
 /**
- * Class modelling the fo:table-cell object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_table-cell">
+ * <code>fo:table-cell</code></a> object.
  */
 public class TableCell extends TableFObj {
     // The value of properties relevant for fo:table-cell.
@@ -60,7 +61,9 @@ public class TableCell extends TableFObj {
     private boolean blockItemFound = false;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Create a TableCell instance with the given {@link FONode}
+     * as parent.
+     * @param parent {@link FONode} that is the parent of this object
      */
     public TableCell(FONode parent) {
         super(parent);
@@ -87,9 +90,7 @@ public class TableCell extends TableFObj {
         width = pList.get(PR_WIDTH).getLength();
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void startOfNode() throws FOPException {
         super.startOfNode();
         getFOEventHandler().startCell(this);
@@ -115,7 +116,7 @@ public class TableCell extends TableFObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: marker* (%block;)+
+     * <br>XSL Content Model: marker* (%block;)+
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName)
         throws ValidationException {
@@ -146,25 +147,32 @@ public class TableCell extends TableFObj {
     }
 
     /**
-     * @return the Common Border, Padding, and Background Properties.
+     * Get the {@link CommonBorderPaddingBackground} instance
+     * attached to this TableCell.
+     * @return the {@link CommonBorderPaddingBackground} instance
      */
     public CommonBorderPaddingBackground getCommonBorderPaddingBackground() {
         return this.commonBorderPaddingBackground;
     }
 
     /**
+     * Get the value for the <code>column-number</code> property.
      * @return the "column-number" property.
      */
     public int getColumnNumber() {
         return columnNumber;
     }
 
-    /** @return true if "empty-cells" is "show" */
+    /**
+     * Get the value for the <code>empty-cells</code> property.
+     * @return true if "empty-cells" is "show"
+     */
     public boolean showEmptyCells() {
         return (this.emptyCells == EN_SHOW);
     }
 
     /**
+     * Get the value for the <code>number-columns-spanned</code> property
      * @return the "number-columns-spanned" property.
      */
     public int getNumberColumnsSpanned() {
@@ -172,6 +180,7 @@ public class TableCell extends TableFObj {
     }
 
     /**
+     * Get the value for the <code>number-rows-spanned</code> property
      * @return the "number-rows-spanned" property.
      */
     public int getNumberRowsSpanned() {
@@ -179,30 +188,41 @@ public class TableCell extends TableFObj {
     }
 
     /**
+     * Get the value for the <code>block-progression-dimension</code> property
      * @return the "block-progression-dimension" property.
      */
     public LengthRangeProperty getBlockProgressionDimension() {
         return blockProgressionDimension;
     }
 
-    /** @return the display-align property. */
+    /**
+     * Get the value for the <code>display-align</code> property
+     * @return the display-align property.
+     */
     public int getDisplayAlign() {
         return displayAlign;
     }
 
     /**
+     * Get the value for the <code>width</code> property
      * @return the "width" property.
      */
     public Length getWidth() {
         return width;
     }
 
-    /** @return true if the cell starts a row. */
+    /**
+     * Get the value for the <code>starts-row</code> property
+     * @return true if the cell starts a row.
+     */
     public boolean startsRow() {
         return (startsRow == EN_TRUE);
     }
 
-    /** @return true if the cell ends a row. */
+    /**
+     * Get the value for the <code>ends-row</code> property
+     * @return true if the cell ends a row.
+     */
     public boolean endsRow() {
         return (endsRow == EN_TRUE);
     }
@@ -214,6 +234,7 @@ public class TableCell extends TableFObj {
 
     /**
      * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_TABLE_CELL}
      */
     public final int getNameId() {
         return FO_TABLE_CELL;
diff --git a/src/java/org/apache/fop/fo/flow/table/TableColumn.java b/src/java/org/apache/fop/fo/flow/table/TableColumn.java
index e6f6b420e..0ace2c311 100644
--- a/src/java/org/apache/fop/fo/flow/table/TableColumn.java
+++ b/src/java/org/apache/fop/fo/flow/table/TableColumn.java
@@ -34,7 +34,8 @@ import org.apache.fop.fo.properties.TableColLength;
 import org.apache.fop.layoutmgr.table.CollapsingBorderModel;
 
 /**
- * Class modelling the fo:table-column object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_table-column">
+ * <code>fo:table-column</code></a> object.
  */
 public class TableColumn extends TableFObj {
     // The value of properties relevant for fo:table-column.
@@ -51,13 +52,19 @@ public class TableColumn extends TableFObj {
     private PropertyList pList = null;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Create a TableColumn instance with the given {@link FONode}
+     * as parent.
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     public TableColumn(FONode parent) {
         this(parent, false);
     }
 
     /**
+     * Create a TableColumn instance with the given {@link FONode}
+     * as parent
+     *
      * @param parent FONode that is the parent of this object
      * @param implicit true if this table-column has automatically been created (does not
      * correspond to an explicit fo:table-column in the input document)
@@ -68,9 +75,7 @@ public class TableColumn extends TableFObj {
     }
 
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         commonBorderPaddingBackground = pList.getBorderPaddingBackgroundProps();
         columnNumber = pList.get(PR_COLUMN_NUMBER).getNumeric().getValue();
@@ -117,9 +122,7 @@ public class TableColumn extends TableFObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void startOfNode() throws FOPException {
         super.startOfNode();
         getFOEventHandler().startColumn(this);
@@ -146,7 +149,7 @@ public class TableColumn extends TableFObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: empty
+     * <br>XSL Content Model: empty
      */
     protected void validateChildNode(Locator loc,
                         String nsURI, String localName)
@@ -157,13 +160,17 @@ public class TableColumn extends TableFObj {
     }
 
     /**
-     * @return the Common Border, Padding, and Background Properties.
+     * Get the {@link CommonBorderPaddingBackground} instance
+     * attached to this TableColumn.
+     * @return the {@link CommonBorderPaddingBackground} instance
      */
     public CommonBorderPaddingBackground getCommonBorderPaddingBackground() {
         return commonBorderPaddingBackground;
     }
 
     /**
+     * Get a {@link Length} instance corresponding to the
+     * <code>column-width</code> property.
      * @return the "column-width" property.
      */
     public Length getColumnWidth() {
@@ -179,6 +186,7 @@ public class TableColumn extends TableFObj {
     }
 
     /**
+     * Get the value of the <code>column-number</code> property
      * @return the "column-number" property.
      */
     public int getColumnNumber() {
@@ -187,7 +195,7 @@ public class TableColumn extends TableFObj {
 
     /**
      * Used for setting the column-number for an implicit column
-     * @param columnNumber
+     * @param columnNumber the number to set
      */
     protected void setColumnNumber(int columnNumber) {
         this.columnNumber = columnNumber;
@@ -208,7 +216,10 @@ public class TableColumn extends TableFObj {
         return "table-column";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_TABLE_COLUMN}
+     */
     public int getNameId() {
         return FO_TABLE_COLUMN;
     }
@@ -244,10 +255,10 @@ public class TableColumn extends TableFObj {
     /**
      * Retrieve a property value through its Id; used by
      * from-table-column() function
-     * 
+     *
      * @param propId    the id for the property to retrieve
      * @return the requested Property
-     * @throws PropertyException if there is a problem evaluating the property 
+     * @throws PropertyException if there is a problem evaluating the property
      */
     public Property getProperty(int propId) throws PropertyException {
         return this.pList.get(propId);
diff --git a/src/java/org/apache/fop/fo/flow/table/TableFooter.java b/src/java/org/apache/fop/fo/flow/table/TableFooter.java
index e886d2ee1..d05824e95 100644
--- a/src/java/org/apache/fop/fo/flow/table/TableFooter.java
+++ b/src/java/org/apache/fop/fo/flow/table/TableFooter.java
@@ -25,36 +25,33 @@ import org.apache.fop.fo.FONode;
 
 
 /**
- * Class modelling the fo:table-footer object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_table-footer">
+ * <code>fo:table-footer</code></a> object.
  */
 public class TableFooter extends TableBody {
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Create a TableFooter instance with the given {@link FONode}
+     * as parent.
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     public TableFooter(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void startOfNode() throws FOPException {
         super.startOfNode();
-        //getFOEventHandler().startBody(this);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void endOfNode() throws FOPException {
-//      getFOEventHandler().endFooter(this);
         if (!(tableRowsFound || tableCellsFound)) {
             missingChildElementError("marker* (table-row+|table-cell+)");
         } else {
             finishLastRowGroup();
         }
-//      convertCellsToRows();
     }
 
     /** {@inheritDoc} */
@@ -62,7 +59,10 @@ public class TableFooter extends TableBody {
         return "table-footer";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_TABLE_FOOTER}
+     */
     public int getNameId() {
         return FO_TABLE_FOOTER;
     }
diff --git a/src/java/org/apache/fop/fo/flow/table/TableHeader.java b/src/java/org/apache/fop/fo/flow/table/TableHeader.java
index e248a0f7e..252ba1b8b 100644
--- a/src/java/org/apache/fop/fo/flow/table/TableHeader.java
+++ b/src/java/org/apache/fop/fo/flow/table/TableHeader.java
@@ -25,36 +25,32 @@ import org.apache.fop.fo.FONode;
 
 
 /**
- * Class modelling the fo:table-header object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_table-header">
+ * <code>fo:table-header</code></a> object.
  */
 public class TableHeader extends TableBody {
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Create a TableHeader instance with the given {@link FONode}
+     * as parent.
+     * @param parent {@link FONode} that is the parent of this object
      */
     public TableHeader(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void startOfNode() throws FOPException {
         super.startOfNode();
-        //getFOEventHandler().startHeader(this);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void endOfNode() throws FOPException {
-//      getFOEventHandler().endHeader(this);
         if (!(tableRowsFound || tableCellsFound)) {
             missingChildElementError("marker* (table-row+|table-cell+)");
         } else {
             finishLastRowGroup();
         }
-//      convertCellsToRows();
     }
 
     /** {@inheritDoc} */
@@ -62,7 +58,10 @@ public class TableHeader extends TableBody {
         return "table-header";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_TABLE_HEADER}
+     */
     public int getNameId() {
         return FO_TABLE_HEADER;
     }
diff --git a/src/java/org/apache/fop/fo/flow/table/TableRow.java b/src/java/org/apache/fop/fo/flow/table/TableRow.java
index e5261614b..bf7b16dca 100644
--- a/src/java/org/apache/fop/fo/flow/table/TableRow.java
+++ b/src/java/org/apache/fop/fo/flow/table/TableRow.java
@@ -32,7 +32,8 @@ import org.apache.fop.fo.properties.KeepProperty;
 import org.apache.fop.fo.properties.LengthRangeProperty;
 
 /**
- * Class modelling the fo:table-row object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_table-row">
+ * <code>fo:table-row</code></a> object.
  */
 public class TableRow extends TableCellContainer {
     // The value of properties relevant for fo:table-row.
@@ -52,7 +53,9 @@ public class TableRow extends TableCellContainer {
     // End of property values
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Create a TableRow instance with the given {@link FONode}
+     * as parent.
+     * @param parent {@link FONode} that is the parent of this object
      */
     public TableRow(FONode parent) {
         super(parent);
@@ -83,9 +86,7 @@ public class TableRow extends TableCellContainer {
         super.processNode(elementName, locator, attlist, pList);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void addChildNode(FONode child) throws FOPException {
         if (!inMarker()) {
             TableCell cell = (TableCell) child;
@@ -95,17 +96,13 @@ public class TableRow extends TableCellContainer {
         super.addChildNode(child);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void startOfNode() throws FOPException {
         super.startOfNode();
         getFOEventHandler().startRow(this);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void endOfNode() throws FOPException {
         if (firstChild == null) {
             missingChildElementError("(table-cell+)");
@@ -119,7 +116,7 @@ public class TableRow extends TableCellContainer {
 
     /**
      * {@inheritDoc} String, String)
-     * XSL Content Model: (table-cell+)
+     * <br>XSL Content Model: (table-cell+)
      */
     protected void validateChildNode(Locator loc, String nsURI,
                                      String localName)
@@ -141,7 +138,7 @@ public class TableRow extends TableCellContainer {
         return true;
     }
 
-    /** {inheritDoc} */
+    /** {@inheritDoc} */
     protected void setCollapsedBorders() {
         TableBody body = (TableBody) parent;
         createBorder(CommonBorderPaddingBackground.START, body);
@@ -231,7 +228,10 @@ public class TableRow extends TableCellContainer {
         return "table-row";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_TABLE_ROW}
+     */
     public int getNameId() {
         return FO_TABLE_ROW;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/AbstractPageSequence.java b/src/java/org/apache/fop/fo/pagination/AbstractPageSequence.java
index 578d74c4d..f0928a8ca 100644
--- a/src/java/org/apache/fop/fo/pagination/AbstractPageSequence.java
+++ b/src/java/org/apache/fop/fo/pagination/AbstractPageSequence.java
@@ -26,15 +26,15 @@ import org.apache.fop.fo.FObj;
 import org.apache.fop.fo.PropertyList;
 
 /**
- * Abstract base class for the fo:page-sequence formatting object and the fox:external-document
- * extension object.
+ * Abstract base class for the <a href="http://www.w3.org/TR/xsl/#fo_page-sequence">
+ * <code>fo:page-sequence</code></a> formatting object and the
+ * <a href="http://xmlgraphics.apache.org/fop/0.95/extensions.html#external-document">
+ * <code>fox:external-document</code></a> extension object.
  */
 public abstract class AbstractPageSequence extends FObj {
     
     // The value of properties relevant for fo:page-sequence.
-    /** the initial-page-number value */
     protected Numeric initialPageNumber;
-    /** the force-page-count value */
     protected int forcePageCount;
     private String format;
     private int letterValue;
@@ -45,13 +45,13 @@ public abstract class AbstractPageSequence extends FObj {
 
     private PageNumberGenerator pageNumberGenerator;
 
-    /** the first page number generated by the page sequence */
     protected int startingPageNumber = 0;
 
     /**
-     * Create a page sequence FO node.
+     * Create an AbstractPageSequence that is a child
+     * of the given parent {@link FONode}.
      *
-     * @param parent the parent FO node
+     * @param parent the parent {@link FONode}
      */
     public AbstractPageSequence(FONode parent) {
         super(parent);
@@ -76,10 +76,6 @@ public abstract class AbstractPageSequence extends FObj {
 
     }
 
-    /** {@inheritDoc} */
-    protected void endOfNode() throws FOPException {
-    }
-
     /**
      * Initialize the current page number for the start of the page sequence.
      */
@@ -132,18 +128,25 @@ public abstract class AbstractPageSequence extends FObj {
         return (Root)this.getParent();
     }
 
-    /** @return the force-page-count value */
+    /**
+     * Get the value of the <code>force-page-count</code> property.
+     * @return the force-page-count value
+     */
     public int getForcePageCount() {
         return forcePageCount;
     }
 
-    /** @return the initial-page-number property value */
+    /**
+     * Get the value of the <code>initial-page-number</code> property.
+     * @return the initial-page-number property value
+     */
     public Numeric getInitialPageNumber() {
         return initialPageNumber;
     }
     
     /**
-     * @return the "reference-orientation" property.
+     * Get the value of the <code>reference-orientation</code> property.
+     * @return the "reference-orientation" property
      * @since XSL 1.1
      */
     public int getReferenceOrientation() {
diff --git a/src/java/org/apache/fop/fo/pagination/ColorProfile.java b/src/java/org/apache/fop/fo/pagination/ColorProfile.java
index 6067b55c5..0af1aa42d 100644
--- a/src/java/org/apache/fop/fo/pagination/ColorProfile.java
+++ b/src/java/org/apache/fop/fo/pagination/ColorProfile.java
@@ -19,16 +19,18 @@
 
 package org.apache.fop.fo.pagination;
 
-import org.xml.sax.Locator;
-
 import org.apache.fop.apps.FOPException;
 import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.FObj;
 import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
+import org.xml.sax.Locator;
+
 /**
- * The fo:color-profile formatting object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_color-profile">
+ * <code>fo:color-profile</code></a> object.
+ *
  * This loads the color profile when needed and resolves a requested color.
  */
 public class ColorProfile extends FObj {
@@ -39,9 +41,9 @@ public class ColorProfile extends FObj {
     // End of property values
 
     /**
-     * Creates a new color-profile element.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Base constructor
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     public ColorProfile(FONode parent) {
         super(parent);
@@ -56,7 +58,7 @@ public class ColorProfile extends FObj {
 
     /**
      * {@inheritDoc}
-        XSL 1.0/FOP: EMPTY (no child nodes permitted)
+     * <br>XSL 1.0/FOP: EMPTY (no child nodes permitted)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -66,8 +68,7 @@ public class ColorProfile extends FObj {
     }
 
     /**
-     * Return the "color-profile-name" property.
-     * @return the color-profile-name property
+     * @return the "color-profile-name" property.
      */
     public String getColorProfileName() {
         return colorProfileName;
@@ -78,7 +79,10 @@ public class ColorProfile extends FObj {
         return "color-profile";
     }
     
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_COLOR_PROFILE}
+     */
     public int getNameId() {
         return FO_COLOR_PROFILE;
     }
@@ -86,7 +90,7 @@ public class ColorProfile extends FObj {
     /** 
      * Get src attribute
      * 
-     * @return Value of color-profile src attribute
+     * @return value of color-profile src attribute
      */
     public String getSrc() {
         return this.src;
diff --git a/src/java/org/apache/fop/fo/pagination/ConditionalPageMasterReference.java b/src/java/org/apache/fop/fo/pagination/ConditionalPageMasterReference.java
index a13808324..7c76109f4 100644
--- a/src/java/org/apache/fop/fo/pagination/ConditionalPageMasterReference.java
+++ b/src/java/org/apache/fop/fo/pagination/ConditionalPageMasterReference.java
@@ -29,7 +29,9 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * A conditional-page-master-reference formatting object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_conditional-page-master-reference">
+ * <code>fo:conditional-page-master-reference</code></a> object.
+ * 
  * This is a reference to a page master with a set of conditions.
  * The conditions must be satisfied for the referenced master to
  * be used.
@@ -45,9 +47,10 @@ public class ConditionalPageMasterReference extends FObj {
     // End of property values
     
     /**
-     * Creates a new conditional-page-master-reference element.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Create a ConditionalPageMasterReference instance that is a
+     * child of the given {@link FONode}.
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     public ConditionalPageMasterReference(FONode parent) {
         super(parent);
@@ -76,13 +79,11 @@ public class ConditionalPageMasterReference extends FObj {
     
     /**
      * {@inheritDoc}
-     * XSL Content Model: empty
+     * <br>XSL Content Model: empty
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
-                throws ValidationException {
-        if (FO_URI.equals(nsURI)) {
-            invalidChildError(loc, nsURI, localName);
-        }
+           throws ValidationException {
+       invalidChildError(loc, nsURI, localName);
     }
 
     /**
@@ -150,12 +151,18 @@ public class ConditionalPageMasterReference extends FObj {
         return true;
     }
 
-    /** @return the "master-reference" property. */
+    /**
+     * Get the value for the <code>master-reference</code> property.
+     * @return the "master-reference" property
+     */
     public String getMasterReference() {
         return masterReference;
     }
     
-    /** @return the page-position property value */
+    /**
+     * Get the value for the <code>page-position</code> property.
+     * @return the page-position property value
+     */
     public int getPagePosition() {
         return this.pagePosition;
     }
@@ -165,7 +172,10 @@ public class ConditionalPageMasterReference extends FObj {
         return "conditional-page-master-reference";
     }
     
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_CONDITIONAL_PAGE_MASTER_REFERENCE}
+     */
     public int getNameId() {
         return FO_CONDITIONAL_PAGE_MASTER_REFERENCE;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/Declarations.java b/src/java/org/apache/fop/fo/pagination/Declarations.java
index 3eec2897a..eb24cffe0 100644
--- a/src/java/org/apache/fop/fo/pagination/Declarations.java
+++ b/src/java/org/apache/fop/fo/pagination/Declarations.java
@@ -31,7 +31,9 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * Declarations formatting object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_declarations">
+ * <code>fo:declarations</code></a> object.
+ *
  * A declarations formatting object holds a set of color-profiles
  * and optionally additional non-XSL namespace elements.
  * The color-profiles are held in a hashmap for use with color-profile
@@ -42,7 +44,6 @@ public class Declarations extends FObj {
     private Map colorProfiles = null;
 
     /**
-     * Creates a new declarations element.
      * @param parent FONode that is the parent of this object
      */
     public Declarations(FONode parent) {
@@ -57,13 +58,13 @@ public class Declarations extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL 1.0: (color-profile)+ (and non-XSL NS nodes)
-     * FOP/XSL 1.1: (color-profile)* (and non-XSL NS nodes)
+     * <br>XSL 1.0: (color-profile)+ (and non-XSL NS nodes)
+     * <br>FOP/XSL 1.1: (color-profile)* (and non-XSL NS nodes)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
         if (FO_URI.equals(nsURI)) {
-            if (!localName.equals("color-profile")) {   
+            if (!localName.equals("color-profile")) {
                 invalidChildError(loc, nsURI, localName);
             }
         } // anything outside of XSL namespace is OK.
@@ -112,7 +113,10 @@ public class Declarations extends FObj {
         return "declarations";
     }
     
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_DECLARATIONS}
+     */
     public int getNameId() {
         return FO_DECLARATIONS;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/Flow.java b/src/java/org/apache/fop/fo/pagination/Flow.java
index 2ee77ff0a..8e114c47f 100644
--- a/src/java/org/apache/fop/fo/pagination/Flow.java
+++ b/src/java/org/apache/fop/fo/pagination/Flow.java
@@ -28,7 +28,9 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * Class modelling the fo:flow object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_flow">
+ * <code>fo:flow</code></a> object.
+ *
  */
 public class Flow extends FObj {
     // The value of properties relevant for fo:flow.
@@ -39,7 +41,8 @@ public class Flow extends FObj {
     private boolean blockItemFound = false;
 
     /**
-     * @param parent FONode that is the parent of this object
+     * Create a Flow instance that is a child of the given {@link FONode}.
+     * @param parent the {@link FONode} that is the parent of this object
      */
     public Flow(FONode parent) {
         super(parent);
@@ -86,7 +89,7 @@ public class Flow extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: marker* (%block;)+
+     * <br>XSL Content Model: marker* (%block;)+
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -103,7 +106,10 @@ public class Flow extends FObj {
         }
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return true (Flow can generate reference areas)
+     */
     public boolean generatesReferenceAreas() {
         return true;
     }
@@ -118,7 +124,10 @@ public class Flow extends FObj {
         return "flow";
     }
     
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_FLOW}
+     */
     public int getNameId() {
         return FO_FLOW;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/LayoutMasterSet.java b/src/java/org/apache/fop/fo/pagination/LayoutMasterSet.java
index 1b57be57d..7f081579d 100644
--- a/src/java/org/apache/fop/fo/pagination/LayoutMasterSet.java
+++ b/src/java/org/apache/fop/fo/pagination/LayoutMasterSet.java
@@ -32,7 +32,9 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * The layout-master-set formatting object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_layout-master-set">
+ * <code>fo:layout-master-set</code></a> object.
+ *
  * This class maintains the set of simple page master and
  * page sequence masters.
  * The masters are stored so that the page sequence can obtain
@@ -46,9 +48,10 @@ public class LayoutMasterSet extends FObj {
     private Map pageSequenceMasters;
 
     /**
-     * Creates a new layout-master-set element.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Create a LayoutMasterSet instance that is a child of the given
+     * parent {@link FONode}.
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     public LayoutMasterSet(FONode parent) {
         super(parent);
@@ -76,7 +79,7 @@ public class LayoutMasterSet extends FObj {
 
     /**
      * {@inheritDoc}
-        XSL/FOP: (simple-page-master|page-sequence-master)+
+     * <br>XSL/FOP: (simple-page-master|page-sequence-master)+
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
             throws ValidationException {
@@ -205,7 +208,10 @@ public class LayoutMasterSet extends FObj {
         return "layout-master-set";
     }
     
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_LAYOUT_MASTER_SET}
+     */
     public int getNameId() {
         return FO_LAYOUT_MASTER_SET;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/PageSequenceMaster.java b/src/java/org/apache/fop/fo/pagination/PageSequenceMaster.java
index b6c8c0f6b..a16514705 100644
--- a/src/java/org/apache/fop/fo/pagination/PageSequenceMaster.java
+++ b/src/java/org/apache/fop/fo/pagination/PageSequenceMaster.java
@@ -32,7 +32,9 @@ import org.apache.fop.fo.ValidationException;
 import org.apache.fop.layoutmgr.BlockLevelEventProducer;
 
 /**
- * The page-sequence-master formatting object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_page-sequence-master">
+ * <code>fo:page-sequence-master</code></a> object.
+ *
  * This class handles a list of subsequence specifiers
  * which are simple or complex references to page-masters.
  */
@@ -54,17 +56,16 @@ public class PageSequenceMaster extends FObj {
     // but the actual FO's are MasterReferences.
 
     /**
-     * Creates a new page-sequence-master element.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Create a PageSequenceMaster instance that is a child of the
+     * given {@link FONode}.
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     public PageSequenceMaster(FONode parent) {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         masterName = pList.get(PR_MASTER_NAME).getString();
         
@@ -73,18 +74,14 @@ public class PageSequenceMaster extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void startOfNode() throws FOPException {
         subSequenceSpecifiers = new java.util.ArrayList();
         layoutMasterSet = parent.getRoot().getLayoutMasterSet();
         layoutMasterSet.addPageSequenceMaster(masterName, this);
     }
     
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         if (firstChild == null) {
             missingChildElementError("(single-page-master-reference|"
@@ -94,22 +91,22 @@ public class PageSequenceMaster extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL/FOP: (single-page-master-reference|repeatable-page-master-reference|
+     * <br>XSL/FOP: (single-page-master-reference|repeatable-page-master-reference|
      *     repeatable-page-master-alternatives)+
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
-                throws ValidationException {
+        throws ValidationException {
         if (FO_URI.equals(nsURI)) {
-            if (!localName.equals("single-page-master-reference") 
-                && !localName.equals("repeatable-page-master-reference")
-                && !localName.equals("repeatable-page-master-alternatives")) {   
+            if (!"single-page-master-reference".equals(localName) 
+                && !"repeatable-page-master-reference".equals(localName)
+                && !"repeatable-page-master-alternatives".equals(localName)) {   
                     invalidChildError(loc, nsURI, localName);
             }
         }
     }
 
     /**
-     * Adds a new subsequence specifier to the page sequence master.
+     * Adds a new suqsequence specifier to the page sequence master.
      * @param pageMasterReference the subsequence to add
      */
     protected void addSubsequenceSpecifier(SubSequenceSpecifier pageMasterReference) {
@@ -165,20 +162,14 @@ public class PageSequenceMaster extends FObj {
     
     /** @return true if the page-sequence-master has a page-master with page-position="last" */
     public boolean hasPagePositionLast() {
-        if (currentSubSequence != null) {
-            return currentSubSequence.hasPagePositionLast();
-        } else {
-            return false;
-        }
+        return (currentSubSequence != null
+                && currentSubSequence.hasPagePositionLast());
     }
     
     /** @return true if the page-sequence-master has a page-master with page-position="only" */
     public boolean hasPagePositionOnly() {
-        if (currentSubSequence != null) {
-            return currentSubSequence.hasPagePositionOnly();
-        } else {
-            return false;
-        }
+        return (currentSubSequence != null
+                && currentSubSequence.hasPagePositionOnly());
     }
     
     /**
@@ -240,7 +231,10 @@ public class PageSequenceMaster extends FObj {
         return "page-sequence-master";
     }
     
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_PAGE_SEQUENCE_MASTER}
+     */
     public int getNameId() {
         return FO_PAGE_SEQUENCE_MASTER;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/PageSequenceWrapper.java b/src/java/org/apache/fop/fo/pagination/PageSequenceWrapper.java
index 0b3cff276..f8a37d8c0 100644
--- a/src/java/org/apache/fop/fo/pagination/PageSequenceWrapper.java
+++ b/src/java/org/apache/fop/fo/pagination/PageSequenceWrapper.java
@@ -22,15 +22,15 @@ package org.apache.fop.fo.pagination;
 import org.xml.sax.Locator;
 
 import org.apache.fop.apps.FOPException;
-import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.FObj;
+import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * The fo:page-sequence-wrapper formatting object, first introduced
- * in the XSL 1.1 WD.  Prototype version only, subject to change as
- * XSL 1.1 WD evolves.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_page-sequence-wrapper">
+ * <code>fo:page-sequence-wrapper</code></a> object, first introduced
+ * in the XSL 1.1 WD.
  */
 public class PageSequenceWrapper extends FObj {
     // The value of properties relevant for this FO
@@ -39,8 +39,10 @@ public class PageSequenceWrapper extends FObj {
     // End of property values
     
     /**
-     * Creates a new page-sequence-wrapper element.
-     * @param parent FONode that is the parent of this object
+     * Create a PageSequenceWrapper instance that is a child of
+     * the given parent {@link FONode}.
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     public PageSequenceWrapper(FONode parent) {
         super(parent);
@@ -55,7 +57,7 @@ public class PageSequenceWrapper extends FObj {
 
     /**
      * {@inheritDoc}
-        XSL/FOP: (bookmark+)
+     *  <br>XSL/FOP: (bookmark+)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -67,12 +69,18 @@ public class PageSequenceWrapper extends FObj {
         }
     }
 
-    /** @return the "index-class" property. */
+    /**
+     * Get the value of the <code>index-class</code> property.
+     * @return the "index-class" property
+     */
     public String getIndexClass() {
         return indexClass;
     }
 
-    /** @return the "index-key" property. */
+    /**
+     * Get the value of the <code>index-key</code> property.
+     * @return the "index-key" property
+     */
     public String getIndexKey() {
         return indexKey;
     }
@@ -82,7 +90,10 @@ public class PageSequenceWrapper extends FObj {
         return "page-sequence-wrapper";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_PAGE_SEQUENCE_WRAPPER}
+     */
     public int getNameId() {
         return FO_PAGE_SEQUENCE_WRAPPER;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/Region.java b/src/java/org/apache/fop/fo/pagination/Region.java
index ded86514b..753e8f735 100644
--- a/src/java/org/apache/fop/fo/pagination/Region.java
+++ b/src/java/org/apache/fop/fo/pagination/Region.java
@@ -30,10 +30,11 @@ import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.FObj;
 import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
+import org.apache.fop.fo.expr.PropertyException;
 import org.apache.fop.fo.properties.CommonBorderPaddingBackground;
 
 /**
- * This is an abstract base class for pagination regions
+ * This is an abstract base class for pagination regions.
  */
 public abstract class Region extends FObj {
     // The value of properties relevant for fo:region
@@ -49,9 +50,9 @@ public abstract class Region extends FObj {
     private SimplePageMaster layoutMaster;
 
     /**
-     * Creates a new Region.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Base constructor
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     protected Region(FONode parent) {
         super(parent);
@@ -81,7 +82,7 @@ public abstract class Region extends FObj {
         }
         
         //TODO do we need context for getBPPaddingAndBorder() and getIPPaddingAndBorder()?
-        if ((getCommonBorderPaddingBackground().getBPPaddingAndBorder(false, null) != 0 
+        if ((getCommonBorderPaddingBackground().getBPPaddingAndBorder(false, null) != 0
                 || getCommonBorderPaddingBackground().getIPPaddingAndBorder(false, null) != 0)) {
             getFOValidationEventProducer().nonZeroBorderPaddingOnRegion(this, getName(),
                     regionName, true, getLocator());
@@ -90,7 +91,7 @@ public abstract class Region extends FObj {
 
     /**
      * {@inheritDoc} String, String)
-     * XSL Content Model: empty
+     * <br>XSL Content Model: empty
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
diff --git a/src/java/org/apache/fop/fo/pagination/RegionAfter.java b/src/java/org/apache/fop/fo/pagination/RegionAfter.java
index 2852358b5..91aadce76 100644
--- a/src/java/org/apache/fop/fo/pagination/RegionAfter.java
+++ b/src/java/org/apache/fop/fo/pagination/RegionAfter.java
@@ -29,14 +29,15 @@ import org.apache.fop.datatypes.LengthBase;
 import org.apache.fop.datatypes.SimplePercentBaseContext;
 
 /**
- * The fo:region-after element.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_region-after">
+ * <code>fo:region-after</code></a> object.
  */
 public class RegionAfter extends RegionBA {
 
     /**
-     * Creates a new region-after element.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Create a RegionAfter instance that is a child of the
+     * given parent {@link FONode}.
+     * @param parent    the {@link FONode} that is to be the parent
      */
     public RegionAfter(FONode parent) {
         super(parent);
@@ -92,7 +93,10 @@ public class RegionAfter extends RegionBA {
         return "region-after";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_REGION_AFTER}
+     */
     public int getNameId() {
         return FO_REGION_AFTER;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/RegionBA.java b/src/java/org/apache/fop/fo/pagination/RegionBA.java
index 279164a96..4cedee6d1 100644
--- a/src/java/org/apache/fop/fo/pagination/RegionBA.java
+++ b/src/java/org/apache/fop/fo/pagination/RegionBA.java
@@ -28,7 +28,9 @@ import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.PropertyList;
 
 /**
- * Abstract base class for fo:region-before and fo:region-after.
+ * Abstract base class for <a href="http://www.w3.org/TR/xsl/#fo_region-before">
+ * <code>fo:region-before</code></a> and <a href="http://www.w3.org/TR/xsl/#fo_region-after">
+ * <code>fo:region-after</code></a>.
  */
 public abstract class RegionBA extends SideRegion {
     // The value of properties relevant for fo:region-[before|after].
@@ -36,9 +38,9 @@ public abstract class RegionBA extends SideRegion {
     // End of property values
     
     /**
-     * Creates a new region (before or after).
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Create a RegionBA instance that is a child of the
+     * given parent {@link FONode}.
+     * @param parent    the {@link FONode} that is to be the parent
      */
     protected RegionBA(FONode parent) {
         super(parent);
@@ -51,7 +53,8 @@ public abstract class RegionBA extends SideRegion {
     }
 
     /**
-     * @return the "precedence" property.
+     * Get the value of the <code>precedence</code> property.
+     * @return the "precedence" property
      */
     public int getPrecedence() {
         return precedence;
diff --git a/src/java/org/apache/fop/fo/pagination/RegionBefore.java b/src/java/org/apache/fop/fo/pagination/RegionBefore.java
index 076737252..fbcf7e8e7 100644
--- a/src/java/org/apache/fop/fo/pagination/RegionBefore.java
+++ b/src/java/org/apache/fop/fo/pagination/RegionBefore.java
@@ -29,14 +29,15 @@ import org.apache.fop.datatypes.SimplePercentBaseContext;
 import org.apache.fop.fo.FONode;
 
 /**
- * The fo:region-before element.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_region-before">
+ * <code>fo:region-before</code></a> object.
  */
 public class RegionBefore extends RegionBA {
 
     /**
-     * Creates a new region-before element.
-     * @param parent the parent element
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Create a RegionBefore instance that is a child of the
+     * given parent {@link FONode}.
+     * @param parent    the {@link FONode} that is to be the parent
      */
     public RegionBefore(FONode parent) {
         super(parent);
@@ -90,7 +91,10 @@ public class RegionBefore extends RegionBA {
         return "region-before";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_REGION_BEFORE}
+     */
     public int getNameId() {
         return FO_REGION_BEFORE;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/RegionBody.java b/src/java/org/apache/fop/fo/pagination/RegionBody.java
index 9700e72fc..c9dd792db 100644
--- a/src/java/org/apache/fop/fo/pagination/RegionBody.java
+++ b/src/java/org/apache/fop/fo/pagination/RegionBody.java
@@ -33,7 +33,8 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.properties.CommonMarginBlock;
 
 /**
- * The fo:region-body element.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_region-body">
+ * <code>fo:region-body</code></a> object.
  */
 public class RegionBody extends Region {
     // The value of properties relevant for fo:region-body.
@@ -43,9 +44,9 @@ public class RegionBody extends Region {
     // End of property values
 
     /**
-     * Creates a new region-body element.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Create a RegionBody instance that is a child of the
+     * given parent {@link FONode}.
+     * @param parent    the {@link FONode} that is to be the parent
      */
     public RegionBody(FONode parent) {
         super(parent);
@@ -58,7 +59,7 @@ public class RegionBody extends Region {
         columnCount = pList.get(PR_COLUMN_COUNT).getNumeric();
         columnGap = pList.get(PR_COLUMN_GAP).getLength();
         
-        if ((getColumnCount() != 1) && (getOverflow() == EN_SCROLL)) {
+        if ((getColumnCount() > 1) && (getOverflow() == EN_SCROLL)) {
             /* This is an error (See XSL Rec, fo:region-body description).
              * The Rec allows for acting as if "1" is chosen in
              * these cases, but we will need to be able to change Numeric
@@ -70,15 +71,16 @@ public class RegionBody extends Region {
     }
 
     /**
-     * Return the Common Margin Properties-Block.
-     * @return the Common Margin Properties-Block.
+     * Return the {@link CommonMarginBlock} instance attached to
+     * this instance.
+     * @return the {@link CommonMarginBlock} instance
      */
     public CommonMarginBlock getCommonMarginBlock() {
         return commonMarginBlock;
     }
 
     /**
-     * Return the "column-count" property.
+     * Return the value of the <code>column-count<code> property.
      * @return the "column-count" property.
      */
     public int getColumnCount() {
@@ -86,7 +88,7 @@ public class RegionBody extends Region {
     }
 
     /**
-     * Return the "column-gap" property.
+     * Return the value of the <code>column-gap</code> property.
      * @return the "column-gap" property.
      */
     public int getColumnGap() {
@@ -151,7 +153,10 @@ public class RegionBody extends Region {
         return "region-body";
     }
     
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_REGION_BODY}
+     */
     public int getNameId() {
         return FO_REGION_BODY;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/RegionEnd.java b/src/java/org/apache/fop/fo/pagination/RegionEnd.java
index 13f65d71a..1b1abd53c 100644
--- a/src/java/org/apache/fop/fo/pagination/RegionEnd.java
+++ b/src/java/org/apache/fop/fo/pagination/RegionEnd.java
@@ -22,20 +22,22 @@ package org.apache.fop.fo.pagination;
 // Java
 import java.awt.Rectangle;
 
+// FOP
+import org.apache.fop.fo.FONode;
 import org.apache.fop.datatypes.FODimension;
 import org.apache.fop.datatypes.LengthBase;
 import org.apache.fop.datatypes.SimplePercentBaseContext;
-import org.apache.fop.fo.FONode;
 
 /**
- * The fo:region-end element.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_region-end">
+ * <code>fo:region-end</code></a> object.
  */
 public class RegionEnd extends RegionSE {
 
     /**
-     * Creates a new region-end element.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Create a RegionEnd instance that is a child of the
+     * given parent {@link FONode}.
+     * @param parent    the {@link FONode} that is to be the parent
      */
     public RegionEnd(FONode parent) {
         super(parent);
@@ -90,7 +92,10 @@ public class RegionEnd extends RegionSE {
         return "region-end";
     }
     
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_REGION_END}
+     */
     public int getNameId() {
         return FO_REGION_END;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/RegionSE.java b/src/java/org/apache/fop/fo/pagination/RegionSE.java
index 183b44342..15f61096b 100644
--- a/src/java/org/apache/fop/fo/pagination/RegionSE.java
+++ b/src/java/org/apache/fop/fo/pagination/RegionSE.java
@@ -28,16 +28,18 @@ import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.PropertyList;
 
 /**
- * Abstract base class for fo:region-start and fo:region-end.
+ * Abstract base class for <a href="http://www.w3.org/TR/xsl/#fo_region-start">
+ * <code>fo:region-start</code></a> and <a href="http://www.w3.org/TR/xsl/#fo_region-end">
+ * <code>fo:region-end</code></a>.
  */
 public abstract class RegionSE extends SideRegion {
     // The value of properties relevant for fo:region-[start|end].
     // End of property values
 
     /**
-     * Creates a new region (start or end).
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Create a RegionSE instance that is a child of the
+     * given parent {@link FONode}.
+     * @param parent    the {@link FONode} that is to be the parent
      */
     protected RegionSE(FONode parent) {
         super(parent);
diff --git a/src/java/org/apache/fop/fo/pagination/RegionStart.java b/src/java/org/apache/fop/fo/pagination/RegionStart.java
index 7a69cfdac..e11a8f201 100644
--- a/src/java/org/apache/fop/fo/pagination/RegionStart.java
+++ b/src/java/org/apache/fop/fo/pagination/RegionStart.java
@@ -29,14 +29,15 @@ import org.apache.fop.datatypes.LengthBase;
 import org.apache.fop.datatypes.SimplePercentBaseContext;
 
 /**
- * The fo:region-start element.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_region-start">
+ * <code>fo:region-start</code></a> object.
  */
 public class RegionStart extends RegionSE {
 
     /**
-     * Creates a new region-start element.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Create a RegionStart instance that is a child of the
+     * given parent {@link FONode}.
+     * @param parent    the {@link FONode} that is to be the parent
      */
     public RegionStart(FONode parent) {
         super(parent);
@@ -88,7 +89,10 @@ public class RegionStart extends RegionSE {
         return "region-start";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_REGION_START}
+     */
     public int getNameId() {
         return FO_REGION_START;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/RepeatablePageMasterAlternatives.java b/src/java/org/apache/fop/fo/pagination/RepeatablePageMasterAlternatives.java
index 509b81f21..5c06dd40d 100644
--- a/src/java/org/apache/fop/fo/pagination/RepeatablePageMasterAlternatives.java
+++ b/src/java/org/apache/fop/fo/pagination/RepeatablePageMasterAlternatives.java
@@ -32,7 +32,8 @@ import org.apache.fop.fo.ValidationException;
 import org.apache.fop.fo.properties.Property;
 
 /**
- * A repeatable-page-master-alternatives formatting object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_repeatable-page-master-alternatives">
+ * <code>fo:repeatable-page-master-alternatives</code></a> object.
  * This contains a list of conditional-page-master-reference
  * and the page master is found from the reference that
  * matches the page number and emptyness.
@@ -52,9 +53,9 @@ public class RepeatablePageMasterAlternatives extends FObj
     private boolean hasPagePositionOnly = false;
 
     /**
-     * Creates a new repeatable-page-master-alternatives element.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Base constructor
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     public RepeatablePageMasterAlternatives(FONode parent) {
         super(parent);
@@ -69,7 +70,7 @@ public class RepeatablePageMasterAlternatives extends FObj
     protected void startOfNode() throws FOPException {
         conditionalPageMasterRefs = new java.util.ArrayList();
 
-        assert parent.getName().equals("fo:page-sequence-master"); //Validation by the parent 
+        assert parent.getName().equals("fo:page-sequence-master"); //Validation by the parent
         PageSequenceMaster pageSequenceMaster = (PageSequenceMaster)parent;
         pageSequenceMaster.addSubsequenceSpecifier(this);
     }
@@ -83,7 +84,7 @@ public class RepeatablePageMasterAlternatives extends FObj
 
     /**
      * {@inheritDoc}
-        XSL/FOP: (conditional-page-master-reference+)
+     * <br>XSL/FOP: (conditional-page-master-reference+)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -94,7 +95,10 @@ public class RepeatablePageMasterAlternatives extends FObj
         }
     }
 
-    /** @return the "maximum-repeats" property. */
+    /**
+     * Get the value of the <code>maximum-repeats</code> property?
+     * @return the "maximum-repeats" property
+     */
     public int getMaximumRepeats() {
         if (maximumRepeats.getEnum() == EN_NO_LIMIT) {
             return INFINITE;
@@ -180,7 +184,10 @@ public class RepeatablePageMasterAlternatives extends FObj
         return "repeatable-page-master-alternatives";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_REPEATABLE_PAGE_MASTER_ALTERNATIVES}
+     */
     public int getNameId() {
         return FO_REPEATABLE_PAGE_MASTER_ALTERNATIVES;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/RepeatablePageMasterReference.java b/src/java/org/apache/fop/fo/pagination/RepeatablePageMasterReference.java
index 87dc248c0..1cf77675d 100644
--- a/src/java/org/apache/fop/fo/pagination/RepeatablePageMasterReference.java
+++ b/src/java/org/apache/fop/fo/pagination/RepeatablePageMasterReference.java
@@ -30,7 +30,8 @@ import org.apache.fop.fo.ValidationException;
 import org.apache.fop.fo.properties.Property;
 
 /**
- * A repeatable-page-master-reference formatting object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_repeatable-page-master-reference">
+ * <code>fo:repeatable-page-master-reference</code></a> object.
  * This handles a reference with a specified number of repeating
  * instances of the referenced page master (may have no limit).
  */
@@ -47,9 +48,9 @@ public class RepeatablePageMasterReference extends FObj
     private int numberConsumed = 0;
 
     /**
-     * Creates a new repeatable-page-master-reference element.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Base constructor
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     public RepeatablePageMasterReference(FONode parent) {
         super(parent);
@@ -78,13 +79,11 @@ public class RepeatablePageMasterReference extends FObj
  
     /**
      * {@inheritDoc}
-     * XSL Content Model: empty
+     * <br>XSL Content Model: empty
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
-                throws ValidationException {
-        if (FO_URI.equals(nsURI)) {
-            invalidChildError(loc, nsURI, localName);
-        }
+        throws ValidationException {
+        invalidChildError(loc, nsURI, localName);
     }
 
     /** {@inheritDoc} */
@@ -103,7 +102,10 @@ public class RepeatablePageMasterReference extends FObj
         return masterReference;
     }
 
-    /** @return the "maximum-repeats" property. */
+    /**
+     * Get the value of the <code>maximum-repeats</code> property.
+     * @return the "maximum-repeats" property
+     */
     public int getMaximumRepeats() {
         if (maximumRepeats.getEnum() == EN_NO_LIMIT) {
             return INFINITE;
@@ -149,7 +151,10 @@ public class RepeatablePageMasterReference extends FObj
         return "repeatable-page-master-reference";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_REPEATABLE_PAGE_MASTER_REFERENCE}
+     */
     public int getNameId() {
         return FO_REPEATABLE_PAGE_MASTER_REFERENCE;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/Root.java b/src/java/org/apache/fop/fo/pagination/Root.java
index 1cff9c3d6..04014f6fc 100644
--- a/src/java/org/apache/fop/fo/pagination/Root.java
+++ b/src/java/org/apache/fop/fo/pagination/Root.java
@@ -34,7 +34,9 @@ import org.apache.fop.fo.extensions.destination.Destination;
 import org.apache.fop.fo.pagination.bookmarks.BookmarkTree;
 
 /**
- * The fo:root formatting object. Contains page masters, page-sequences.
+ * Class modeling the <a href="http://www.w3.org/TR/xsl/#fo_root">
+ * <code>fo:root</code></a> formatting object.
+ * Contains page masters, page-sequences.
  */
 public class Root extends FObj {
     // The value of properties relevant for fo:root.
@@ -62,16 +64,14 @@ public class Root extends FObj {
     private FOEventHandler foEventHandler = null;
      
     /**
-     * Creates a new root element.
-     * @param parent the parent node (must be null)
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Base constructor
+     *
+     * @param parent {@link FONode} that is the parent of this object
+     * Note: parent should be null for the fo:root.
      */
     public Root(FONode parent) {
         super(parent);
         pageSequences = new java.util.ArrayList();
-        if (parent != null) {
-            //throw new FOPException("root must be root element");
-        }
     }
 
     /** {@inheritDoc} */
@@ -89,8 +89,8 @@ public class Root extends FObj {
 
     /**
      * {@inheritDoc}
-        XSL 1.0 Spec: (layout-master-set,declarations?,page-sequence+)
-        FOP: (layout-master-set, declarations?, fox:bookmarks?, page-sequence+)
+     * <br>XSL 1.0 Spec: (layout-master-set,declarations?,page-sequence+)
+     * <br>FOP: (layout-master-set, declarations?, fox:bookmarks?, page-sequence+)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
         throws ValidationException {
@@ -138,6 +138,13 @@ public class Root extends FObj {
     }
     
 
+    /** @inheritDoc */
+    protected void validateChildNode(Locator loc, FONode child) throws ValidationException {
+        if (child instanceof AbstractPageSequence) {
+            pageSequenceFound = true;
+        }
+    }
+
     /**
      * Sets the FOEventHandler object that this Root is attached to
      * @param foEventHandler the FOEventHandler object
@@ -295,7 +302,10 @@ public class Root extends FObj {
         return "root";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_ROOT}
+     */
     public int getNameId() {
         return FO_ROOT;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/SimplePageMaster.java b/src/java/org/apache/fop/fo/pagination/SimplePageMaster.java
index 85a5081c8..b296b8579 100644
--- a/src/java/org/apache/fop/fo/pagination/SimplePageMaster.java
+++ b/src/java/org/apache/fop/fo/pagination/SimplePageMaster.java
@@ -36,7 +36,8 @@ import org.apache.fop.fo.ValidationException;
 import org.apache.fop.fo.properties.CommonMarginBlock;
 
 /**
- * A simple-page-master formatting object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_simple-page-master">
+ * <code>fo:simple-page-master</code></a> object.
  * This creates a simple page from the specified regions
  * and attributes.
  */
@@ -63,9 +64,9 @@ public class SimplePageMaster extends FObj {
     private boolean hasRegionEnd = false;
 
     /**
-     * Creates a new simple-page-master element.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Base constructor
+     *
+     * @param parent {@link FONode} that is the parent of this object
      */
     public SimplePageMaster(FONode parent) {
         super(parent);
@@ -109,7 +110,7 @@ public class SimplePageMaster extends FObj {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: (region-body,region-before?,region-after?,region-start?,region-end?)
+     * <br>XSL Content Model: (region-body,region-before?,region-after?,region-start?,region-end?)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
             throws ValidationException {
@@ -262,7 +263,10 @@ public class SimplePageMaster extends FObj {
         return "simple-page-master";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_SIMPLE_PAGE_MASTER}
+     */
     public int getNameId() {
         return FO_SIMPLE_PAGE_MASTER;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/SinglePageMasterReference.java b/src/java/org/apache/fop/fo/pagination/SinglePageMasterReference.java
index 119ec409e..f58f32d1f 100644
--- a/src/java/org/apache/fop/fo/pagination/SinglePageMasterReference.java
+++ b/src/java/org/apache/fop/fo/pagination/SinglePageMasterReference.java
@@ -29,7 +29,8 @@ import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * A single-page-master-reference formatting object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_single-page-master-reference">
+ * <code>fo:single-page-master-reference</code></a> object.
  * This is a reference for a single page. It returns the
  * master name only once until reset.
  */
@@ -46,9 +47,9 @@ public class SinglePageMasterReference extends FObj
     private int state;
 
     /**
-     * Creates a new single-page-master-reference element.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Creates a new SinglePageMasterReference instance that is
+     * a child of the given {@link FONode}.
+     * @param parent {@link FONode} that is the parent of this object
      */
     public SinglePageMasterReference(FONode parent) {
         super(parent);
@@ -72,7 +73,7 @@ public class SinglePageMasterReference extends FObj
     
     /**
      * {@inheritDoc}
-     * XSL Content Model: empty
+     * <br>XSL Content Model: empty
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -127,7 +128,10 @@ public class SinglePageMasterReference extends FObj
         return "single-page-master-reference";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_SINGLE_PAGE_MASTER_REFERENCE}
+     */
     public int getNameId() {
         return FO_SINGLE_PAGE_MASTER_REFERENCE;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/StaticContent.java b/src/java/org/apache/fop/fo/pagination/StaticContent.java
index 184438b6f..9a5e47d8a 100644
--- a/src/java/org/apache/fop/fo/pagination/StaticContent.java
+++ b/src/java/org/apache/fop/fo/pagination/StaticContent.java
@@ -27,12 +27,12 @@ import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * Class modeling the fo:static-content object.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_static-content">
+ * <code>fo:static-content</code></a> object.
  */
 public class StaticContent extends Flow {
 
     /**
-     * Creates a new static-content element.
      * @param parent FONode that is the parent of this object
      */
     public StaticContent(FONode parent) {
@@ -61,7 +61,7 @@ public class StaticContent extends Flow {
 
     /**
      * {@inheritDoc}
-     * XSL Content Model: (%block;)+
+     * <br>XSL Content Model: (%block;)+
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -77,7 +77,10 @@ public class StaticContent extends Flow {
         return "static-content";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_STATIC_CONTENT}
+     */
     public int getNameId() {
         return FO_STATIC_CONTENT;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/SubSequenceSpecifier.java b/src/java/org/apache/fop/fo/pagination/SubSequenceSpecifier.java
index 0bad65a7c..68c8ed9b9 100644
--- a/src/java/org/apache/fop/fo/pagination/SubSequenceSpecifier.java
+++ b/src/java/org/apache/fop/fo/pagination/SubSequenceSpecifier.java
@@ -21,8 +21,8 @@ package org.apache.fop.fo.pagination;
 
 
 /**
- * Classes that implement this interface can be added to a PageSequenceMaster,
- * and are capable of looking up an appropriate PageMaster.
+ * Classes that implement this interface can be added to a {@link PageSequenceMaster},
+ * and are capable of looking up an appropriate {@link SimplePageMaster}.
  */
 public interface SubSequenceSpecifier {
     
diff --git a/src/java/org/apache/fop/fo/pagination/Title.java b/src/java/org/apache/fop/fo/pagination/Title.java
index f6f625ea8..03afcf5f6 100644
--- a/src/java/org/apache/fop/fo/pagination/Title.java
+++ b/src/java/org/apache/fop/fo/pagination/Title.java
@@ -27,7 +27,8 @@ import org.apache.fop.fo.ValidationException;
 import org.apache.fop.fo.flow.InlineLevel;
 
 /**
- * Class modeling the fo:title object.
+ * Class modeling the <a href="http://www.w3.org/TR/xsl/#fo_title">
+ * <code>fo:title</code></a> object.
  */
 public class Title extends InlineLevel {
     // The value of properties relevant for fo:title.
@@ -35,7 +36,6 @@ public class Title extends InlineLevel {
     // End of property values
 
     /**
-     * Creates a new title element.
      * @param parent FONode that is the parent of this object
      */
     public Title(FONode parent) {
@@ -44,10 +44,10 @@ public class Title extends InlineLevel {
 
     /**
      * {@inheritDoc} String, String)
-        XSL/FOP: (#PCDATA|%inline;)*
+     * <br>XSL/FOP: (#PCDATA|%inline;)*
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
-                throws ValidationException {
+        throws ValidationException {
         if (FO_URI.equals(nsURI)) {
             if (!isInlineItem(nsURI, localName)) {
                 invalidChildError(loc, nsURI, localName);
@@ -60,7 +60,10 @@ public class Title extends InlineLevel {
         return "title";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_TITLE}
+     */
     public int getNameId() {
         return FO_TITLE;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/bookmarks/Bookmark.java b/src/java/org/apache/fop/fo/pagination/bookmarks/Bookmark.java
index 7f55ec51b..ac1ef66de 100644
--- a/src/java/org/apache/fop/fo/pagination/bookmarks/Bookmark.java
+++ b/src/java/org/apache/fop/fo/pagination/bookmarks/Bookmark.java
@@ -20,21 +20,19 @@
 package org.apache.fop.fo.pagination.bookmarks;
 
 import java.util.ArrayList;
-import java.util.List;
 
 import org.xml.sax.Locator;
-
 import org.apache.fop.apps.FOPException;
-import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.FObj;
+import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 
 /**
- * The fo:bookmark formatting object, first introduced in the 
- * XSL 1.1 WD.  Prototype version only, subject to change as
- * XSL 1.1 WD evolves.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_bookmark">
+ * <code>fo:bookmark</code></a> object, first introduced in the 
+ * XSL 1.1 WD.
  */
 public class Bookmark extends FObj {
     private BookmarkTitle bookmarkTitle;
@@ -50,7 +48,8 @@ public class Bookmark extends FObj {
 
 
     /**
-     * Create a new bookmark object.
+     * Create a new Bookmark object that is a child of the
+     * given {@link FONode}.
      *
      * @param parent the parent fo node
      */
@@ -58,9 +57,7 @@ public class Bookmark extends FObj {
         super(parent);
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     public void bind(PropertyList pList) throws FOPException {
         externalDestination = pList.get(PR_EXTERNAL_DESTINATION).getString();
         internalDestination = pList.get(PR_INTERNAL_DESTINATION).getString();
@@ -80,7 +77,7 @@ public class Bookmark extends FObj {
 
     /**
      * {@inheritDoc}
-        XSL/FOP: (bookmark-title, bookmark*)
+     * <br>XSL/FOP: (bookmark-title, bookmark*)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -99,18 +96,14 @@ public class Bookmark extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void endOfNode() throws FOPException {
         if (bookmarkTitle == null) {
            missingChildElementError("(bookmark-title, bookmark*)");
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    /** {@inheritDoc} */
     protected void addChildNode(FONode obj) {
         if (obj instanceof BookmarkTitle) {
             bookmarkTitle = (BookmarkTitle)obj;
@@ -155,10 +148,10 @@ public class Bookmark extends FObj {
     }
 
     /**
-     * Returns a list of child bookmarks.
-     * @return the list of child bookmarks
+     * Get the child <code>Bookmark</code>s in an <code>java.util.ArrayList</code>.
+     * @return an <code>ArrayList</code> containing the child Bookmarks
      */
-    public List getChildBookmarks() {
+    public ArrayList getChildBookmarks() {
         return childBookmarks;
     }
 
@@ -167,7 +160,10 @@ public class Bookmark extends FObj {
         return "bookmark";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_BOOKMARK}
+     */
     public int getNameId() {
         return FO_BOOKMARK;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/bookmarks/BookmarkTitle.java b/src/java/org/apache/fop/fo/pagination/bookmarks/BookmarkTitle.java
index c7024f2aa..c4cc73efc 100644
--- a/src/java/org/apache/fop/fo/pagination/bookmarks/BookmarkTitle.java
+++ b/src/java/org/apache/fop/fo/pagination/bookmarks/BookmarkTitle.java
@@ -21,23 +21,24 @@ package org.apache.fop.fo.pagination.bookmarks;
 
 import org.xml.sax.Locator;
 
-import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.FObj;
+import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.PropertyList;
 import org.apache.fop.fo.ValidationException;
 
 /**
- * The fo:bookmark-title formatting object, first introduced in the 
- * XSL 1.1 WD.  Prototype version only, subject to change as XSL 1.1 WD
- * evolves.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_bookmark-title">
+ * <code>fo:bookmark-title</code></a> object, first introduced in the
+ * XSL 1.1 WD.
  */
 public class BookmarkTitle extends FObj {
     private String title = "";
 
     /**
-     * Create a new BookmarkTitle object.
+     * Create a new BookmarkTitle object that is a child
+     * of the given {@link FONode}.
      *
-     * @param parent the fo node parent
+     * @param parent the {@link FONode} parent
      */
     public BookmarkTitle(FONode parent) {
         super(parent);
@@ -45,14 +46,13 @@ public class BookmarkTitle extends FObj {
 
     /**
      * Add the characters to this BookmarkTitle.
-     * The text data inside the BookmarkTitle XML element 
+     * The text data inside the BookmarkTitle xml element 
      * is used for the BookmarkTitle string.
      *
      * @param data the character data
      * @param start the start position in the data array
      * @param end the end position in the character array
-     * @param pList the currently valid property list
-     * @param locator location in FO source file.
+     * @param locator location in fo source file.
      */
     protected void addCharacters(char[] data, int start, int end,
                                  PropertyList pList,
@@ -62,10 +62,10 @@ public class BookmarkTitle extends FObj {
 
     /**
      * {@inheritDoc}
-        XSL/FOP: empty
+     * <br>XSL/FOP: empty
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
-                throws ValidationException {
+        throws ValidationException {
         if (FO_URI.equals(nsURI)) {
             invalidChildError(loc, nsURI, localName);
         }
@@ -85,7 +85,10 @@ public class BookmarkTitle extends FObj {
         return "bookmark-title";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_BOOKMARK_TITLE}
+     */
     public int getNameId() {
         return FO_BOOKMARK_TITLE;
     }
diff --git a/src/java/org/apache/fop/fo/pagination/bookmarks/BookmarkTree.java b/src/java/org/apache/fop/fo/pagination/bookmarks/BookmarkTree.java
index 0f1d8a8b7..9df049251 100644
--- a/src/java/org/apache/fop/fo/pagination/bookmarks/BookmarkTree.java
+++ b/src/java/org/apache/fop/fo/pagination/bookmarks/BookmarkTree.java
@@ -21,7 +21,6 @@ package org.apache.fop.fo.pagination.bookmarks;
 
 // Java
 import java.util.ArrayList;
-import java.util.List;
 
 import org.xml.sax.Locator;
 
@@ -32,17 +31,18 @@ import org.apache.fop.fo.ValidationException;
 import org.apache.fop.fo.pagination.Root;
 
 /**
- * The fo:bookmark-tree formatting object, first introduced in the 
- * XSL 1.1 WD.  Prototype version only, subject to change as XSL 1.1 WD
- * evolves.
+ * Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_bookmark-tree">
+ * <code>fo:bookmark-tree</code></a> object, first introduced in the
+ * XSL 1.1 WD.
  */
 public class BookmarkTree extends FObj {
     private ArrayList bookmarks = new ArrayList();
 
     /**
-     * Creates a new bookmark-tree element.
-     * @param parent the parent node
-     * @see org.apache.fop.fo.FONode#FONode(FONode)
+     * Create a new BookmarkTree object that is a child
+     * of the given {@link FONode}.
+     *
+     * @param parent the {@link FONode} parent
      */
     public BookmarkTree(FONode parent) {
         super(parent);
@@ -55,10 +55,8 @@ public class BookmarkTree extends FObj {
         }
     }
 
-    /**
-     * {@inheritDoc}
-     */
-    protected void endOfNode() throws FOPException {
+    /** {@inheritDoc} */
+        protected void endOfNode() throws FOPException {
         if (bookmarks == null) {
            missingChildElementError("(fo:bookmark+)");
         }
@@ -67,7 +65,7 @@ public class BookmarkTree extends FObj {
 
     /**
      * {@inheritDoc}
-        XSL/FOP: (bookmark+)
+     * <br>XSL/FOP: (bookmark+)
      */
     protected void validateChildNode(Locator loc, String nsURI, String localName) 
                 throws ValidationException {
@@ -79,10 +77,10 @@ public class BookmarkTree extends FObj {
     }
 
     /**
-     * Returns the root bookmarks.
-     * @return the root bookmarks
+     * Get the descendant {@link Bookmark}s.
+     * @return an <code>ArrayList</code> containing the {@link Bookmark} objects.
      */
-    public List getBookmarks() {
+    public ArrayList getBookmarks() {
         return bookmarks;
     }
 
@@ -91,7 +89,10 @@ public class BookmarkTree extends FObj {
         return "bookmark-tree";
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     * @return {@link org.apache.fop.fo.Constants#FO_BOOKMARK_TREE}
+     */
     public int getNameId() {
         return FO_BOOKMARK_TREE;
     }
diff --git a/src/java/org/apache/fop/hyphenation/Hyphenator.java b/src/java/org/apache/fop/hyphenation/Hyphenator.java
index 3d9ef9eb8..a537a9d01 100644
--- a/src/java/org/apache/fop/hyphenation/Hyphenator.java
+++ b/src/java/org/apache/fop/hyphenation/Hyphenator.java
@@ -255,11 +255,13 @@ public class Hyphenator {
                 if (source instanceof StreamSource) {
                     in = ((StreamSource) source).getInputStream();
                 }
-                if (in == null && source.getSystemId() != null) {
-                    in = new java.net.URL(source.getSystemId()).openStream();
-                } else {
-                    throw new UnsupportedOperationException("Cannot load hyphenation pattern file"
+                if (in == null) {
+                    if (source.getSystemId() != null) {
+                        in = new java.net.URL(source.getSystemId()).openStream();
+                    } else {
+                        throw new UnsupportedOperationException("Cannot load hyphenation pattern file"
                             + " with the supplied Source object: " + source);
+                    }
                 }
                 in = new BufferedInputStream(in);
                 try {
diff --git a/src/java/org/apache/fop/layoutmgr/AbstractLayoutManager.java b/src/java/org/apache/fop/layoutmgr/AbstractLayoutManager.java
index 656b5e2df..76c5ad4da 100644
--- a/src/java/org/apache/fop/layoutmgr/AbstractLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/AbstractLayoutManager.java
@@ -60,7 +60,6 @@ public abstract class AbstractLayoutManager extends AbstractBaseLayoutManager
     
     /** child LM and child LM iterator during getNextKnuthElement phase */
     protected LayoutManager curChildLM = null;
-    /** child LM and child LM iterator during getNextKnuthElement phase */
     protected ListIterator childLMiter = null;
     
     private int lastGeneratedPosition = -1;
@@ -231,6 +230,7 @@ public abstract class AbstractLayoutManager extends AbstractBaseLayoutManager
     
     /**
      * @see PageSequenceLayoutManager#getCurrentPage()
+     * @return the {@link Page} instance corresponding to the current page
      */
     public Page getCurrentPage() {
         return getPSLM().getCurrentPage();
@@ -344,7 +344,7 @@ public abstract class AbstractLayoutManager extends AbstractBaseLayoutManager
      * @param targetArea the area to set the attributes on
      */
     protected void transferForeignAttributes(Area targetArea) {
-        Map atts = getFObj().getForeignAttributes();
+        Map atts = fobj.getForeignAttributes();
         targetArea.setForeignAttributes(atts);
     }
     
@@ -373,7 +373,17 @@ public abstract class AbstractLayoutManager extends AbstractBaseLayoutManager
             getPSLM().addIDToPage(fobj.getId());
         }
     }
-    
+
+    /**
+     * Notifies the {@link PageSequenceLayoutManager} that layout
+     * for this LM has ended.
+     */
+    protected void notifyEndOfLayout() {
+        if (fobj != null) {
+            getPSLM().notifyEndOfLayout(fobj.getId());
+        }
+    }
+
     /** {@inheritDoc} */
     public String toString() {
         return (super.toString() + (fobj != null ? "[fobj=" + fobj.toString() + "]" : ""));
diff --git a/src/java/org/apache/fop/layoutmgr/BlockContainerLayoutManager.java b/src/java/org/apache/fop/layoutmgr/BlockContainerLayoutManager.java
index a44669371..0e6c2cb40 100644
--- a/src/java/org/apache/fop/layoutmgr/BlockContainerLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/BlockContainerLayoutManager.java
@@ -442,8 +442,7 @@ public class BlockContainerLayoutManager extends BlockStackingLayoutManager
                     }
                 }
             } else {
-                int maxbpd = context.getStackLimitBP().opt;
-                allocBPD = maxbpd;
+                allocBPD = context.getStackLimitBP().opt;
                 if (!switchedProgressionDirection) {
                     autoHeight = true;
                 }
@@ -601,13 +600,10 @@ public class BlockContainerLayoutManager extends BlockStackingLayoutManager
         }
         
         public boolean isOverflow() {
-            if (isEmpty()) {
-                return false;
-            } else {
-                return (deferredAlg.getPageBreaks().size() > 1)
-                    || (deferredAlg.totalWidth - deferredAlg.totalShrink) 
-                            > deferredAlg.getLineWidth();
-            }
+            return !isEmpty()
+                    && ((deferredAlg.getPageBreaks().size() > 1)
+                        || (deferredAlg.totalWidth - deferredAlg.totalShrink)
+                            > deferredAlg.getLineWidth());
         }
         
         public int getOverflowAmount() {
@@ -879,8 +875,8 @@ public class BlockContainerLayoutManager extends BlockStackingLayoutManager
         viewportBlockArea = null;
         referenceArea = null;
         resetSpaces();
-        
-        getPSLM().notifyEndOfLayout(fobj.getId());
+
+        notifyEndOfLayout();
     }
     
     /**
diff --git a/src/java/org/apache/fop/layoutmgr/BlockLayoutManager.java b/src/java/org/apache/fop/layoutmgr/BlockLayoutManager.java
index 48bf47caf..d129be666 100644
--- a/src/java/org/apache/fop/layoutmgr/BlockLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/BlockLayoutManager.java
@@ -153,6 +153,7 @@ public class BlockLayoutManager extends BlockStackingLayoutManager
         }
 
         /**
+         * @param pos ...
          * @return true if new child lms were added
          */
         protected boolean createNextChildLMs(int pos) {
@@ -210,7 +211,7 @@ public class BlockLayoutManager extends BlockStackingLayoutManager
 
     /** {@inheritDoc} */
     public int getKeepTogetherStrength() {
-        KeepProperty keep = getBlockFO().getKeepTogether(); 
+        KeepProperty keep = getBlockFO().getKeepTogether();
         int strength = KeepUtil.getCombinedBlockLevelKeepStrength(keep);
         strength = Math.max(strength, getParentKeepTogetherStrength());
         return strength;
@@ -392,7 +393,7 @@ public class BlockLayoutManager extends BlockStackingLayoutManager
         resetSpaces();
         
         // Notify end of block layout manager to the PSLM
-        getPSLM().notifyEndOfLayout(getBlockFO().getId());
+        notifyEndOfLayout();
     }
 
     /**
diff --git a/src/java/org/apache/fop/layoutmgr/list/ListBlockLayoutManager.java b/src/java/org/apache/fop/layoutmgr/list/ListBlockLayoutManager.java
index 57114eee2..7be146d0d 100644
--- a/src/java/org/apache/fop/layoutmgr/list/ListBlockLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/list/ListBlockLayoutManager.java
@@ -219,7 +219,7 @@ public class ListBlockLayoutManager extends BlockStackingLayoutManager
         curBlockArea = null;
         resetSpaces();
         
-        getPSLM().notifyEndOfLayout(fobj.getId());
+        notifyEndOfLayout();
     }
 
     /**
diff --git a/src/java/org/apache/fop/layoutmgr/list/ListItemContentLayoutManager.java b/src/java/org/apache/fop/layoutmgr/list/ListItemContentLayoutManager.java
index e3b88b0ac..edee772d6 100644
--- a/src/java/org/apache/fop/layoutmgr/list/ListItemContentLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/list/ListItemContentLayoutManager.java
@@ -172,7 +172,7 @@ public class ListItemContentLayoutManager extends BlockStackingLayoutManager {
 
         curBlockArea = null;
         
-        getPSLM().notifyEndOfLayout(fobj.getId());
+        notifyEndOfLayout();
     }
 
     /**
@@ -236,6 +236,6 @@ public class ListItemContentLayoutManager extends BlockStackingLayoutManager {
     public int getKeepWithPreviousStrength() {
         return KEEP_AUTO;
     }
-    
+
 }
 
diff --git a/src/java/org/apache/fop/layoutmgr/list/ListItemLayoutManager.java b/src/java/org/apache/fop/layoutmgr/list/ListItemLayoutManager.java
index 5e7288f04..d0e8665e7 100644
--- a/src/java/org/apache/fop/layoutmgr/list/ListItemLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/list/ListItemLayoutManager.java
@@ -288,7 +288,7 @@ public class ListItemLayoutManager extends BlockStackingLayoutManager
             if (end[1] + 1 == elementLists[1].size()) {
                 keepWithNextActive = Math.max(keepWithNextActive, keepWithNextPendingOnBody);
             }
-            
+
             // compute penalty height and box height
             int penaltyHeight = step 
                 + getMaxRemainingHeight(fullHeights, partialHeights) 
@@ -557,7 +557,7 @@ public class ListItemLayoutManager extends BlockStackingLayoutManager
         curBlockArea = null;
         resetSpaces();
         
-        getPSLM().notifyEndOfLayout(fobj.getId());
+        notifyEndOfLayout();
     }
 
     /**
diff --git a/src/java/org/apache/fop/layoutmgr/table/TableCellLayoutManager.java b/src/java/org/apache/fop/layoutmgr/table/TableCellLayoutManager.java
index 6067af4bc..430356bec 100644
--- a/src/java/org/apache/fop/layoutmgr/table/TableCellLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/table/TableCellLayoutManager.java
@@ -199,7 +199,7 @@ public class TableCellLayoutManager extends BlockStackingLayoutManager
             p.setP(0);
         }
 
-        getPSLM().notifyEndOfLayout(fobj.getId());
+        notifyEndOfLayout();
 
         setFinished(true);
         return returnList;
@@ -575,7 +575,7 @@ public class TableCellLayoutManager extends BlockStackingLayoutManager
     public int getKeepWithPreviousStrength() {
         return KEEP_AUTO; //TODO FIX ME (table-cell has no keep-with-previous!)
     }
-    
+
     // --------- Property Resolution related functions --------- //
 
     /**
diff --git a/src/java/org/apache/fop/layoutmgr/table/TableLayoutManager.java b/src/java/org/apache/fop/layoutmgr/table/TableLayoutManager.java
index 75189a6b9..0fe47d7b4 100644
--- a/src/java/org/apache/fop/layoutmgr/table/TableLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/table/TableLayoutManager.java
@@ -381,7 +381,7 @@ public class TableLayoutManager extends BlockStackingLayoutManager
         resetSpaces();
         curBlockArea = null;
         
-        getPSLM().notifyEndOfLayout(fobj.getId());
+        notifyEndOfLayout();
     }
 
     /**