PDFBOX-5660: improve javadoc

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

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/documentinterchange/logicalstructure/PDParentTreeValue.java

@@ -22,8 +22,11 @@
 import org.apache.pdfbox.pdmodel.common.COSObjectable;
 
 /**
- * Described in the PDF specification in the ParentTree segment of the table "Entries in the
- * structure tree root". This is either a dictionary or an array.
+ * This is described in the PDF specification in the <b>ParentTree</b> segment of the table "Entries
+ * in the structure tree root". This is either a dictionary or an array. It's a dictionary for
+ * individual objects like an annotation or an XObject, and an array for a page object or a content
+ * stream containing marked-content sequences identified by an MCID. The index in the array is
+ * identical to the MCID. You can pass null if the MCIDs are not continous.
  *
  * @author Tilman Hausherr
  */

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/documentinterchange/logicalstructure/PDStructureTreeRoot.java

@@ -112,9 +112,15 @@ public void setIDTree(PDNameTreeNode<PDStructureElement> idTree)
     }
 
     /**
-     * Returns the parent tree.
-     * 
-     * @return the parent tree
+     * Returns the parent tree.<p>
+     * The keys correspond to a single page of the document or to an individual object, e.g. an
+     * annotation or an XObject, which have a <b>/StructParent</b> or <b>/StructParents</b>
+     * entry.<p>
+     * The values of type {@link PDParentTreeValue} are either a dictionary or an array. It's a
+     * dictionary for individual objects like an annotation or an XObject, and an array for a page
+     * object or a content stream containing marked-content sequences identified by an MCID.
+     *
+     * @return the parent tree.
      */
     public PDNumberTreeNode getParentTree()
     {
@@ -123,8 +129,16 @@ public PDNumberTreeNode getParentTree()
     }
 
     /**
-     * Sets the parent tree.
-     * 
+     * Sets the parent tree.<p>
+     * The keys correspond to a single page of the document or to an individual object, e.g. an
+     * annotation or an XObject, which have a <b>/StructParent</b> or <b>/StructParents</b>
+     * entry.<p>
+     * The values of type {@link PDParentTreeValue} are either a dictionary or an array. It's a
+     * dictionary for individual objects like an annotation or an XObject, and an array for a page
+     * object or a content stream containing marked-content sequences identified by an MCID.
+     * <p>
+     * To create an empty parent tree, call {@code new PDNumberTreeNode(PDParentTreeValue.class)}.
+     *
      * @param parentTree the parent tree
      */
     public void setParentTree(PDNumberTreeNode parentTree)
@@ -133,19 +147,21 @@ public void setParentTree(PDNumberTreeNode parentTree)
     }
 
     /**
-     * Returns the next key in the parent tree.
-     * 
-     * @return the next key in the parent tree
+     * Returns The next key for the parent tree. This is a number greater than any existing key, and
+     * which shall be used for the next entry to be added to the tree.
+     *
+     * @return The next key for the parent tree
      */
     public int getParentTreeNextKey()
     {
         return this.getCOSObject().getInt(COSName.PARENT_TREE_NEXT_KEY);
     }
 
     /**
-     * Sets the next key in the parent tree.
+     * Sets the next key in the parent tree. This is a number greater than any existing key, and
+     * which shall be used for the next entry to be added to the tree.
      * 
-     * @param parentTreeNextkey the next key in the parent tree.
+     * @param parentTreeNextkey The next key in the parent tree.
      */
     public void setParentTreeNextKey(int parentTreeNextkey)
     {