Add some limited XDGF documentation

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

src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFBaseContents.java

@@ -40,7 +40,9 @@ import com.microsoft.schemas.office.visio.x2012.main.PageContentsType;
 import com.microsoft.schemas.office.visio.x2012.main.ShapeSheetType;
 
 /**
- * Container of shapes for a page in a visio document
+ * Container of shapes for a page in a Visio diagram. Shapes are not
+ * necessarily literal shapes in the diagram, but is the term that is
+ * used to describe the basic elements that make up a Visio diagram.
  */
 public class XDGFBaseContents extends XDGFXMLDocumentPart {
 
@@ -105,6 +107,7 @@ public class XDGFBaseContents extends XDGFXMLDocumentPart {
     //
 
     /**
+     * Draws the contents of a page onto a Graphics2D object
      *
      * @param graphics
      */
@@ -129,7 +132,6 @@ public class XDGFBaseContents extends XDGFXMLDocumentPart {
         return Collections.unmodifiableList(_toplevelShapes);
     }
     
-    // get connections
     public List<XDGFConnection> getConnections() {
         return Collections.unmodifiableList(_connections);
     }

src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFCell.java

@@ -31,6 +31,10 @@ import com.microsoft.schemas.office.visio.x2012.main.CellType;
  *
  * The various attributes of a Cell are constrained, and are better defined in
  * the XSD 1.1 visio schema
+ * 
+ * Values of a cell are often the result of a formula computation. Luckily for
+ * you, Visio seems to always write the result to the document file, so unless
+ * the values change we don't need to recompute the values.
  */
 public class XDGFCell {
 
@@ -97,7 +101,10 @@ public class XDGFCell {
         }
     }
 
-    // returns a length, converts it to inches?
+    /**
+     * @param cell
+     * @return A value converted to inches
+     */
     public static Double parseVLength(CellType cell) {
         try {
             return Double.parseDouble(cell.getV());
@@ -116,7 +123,7 @@ public class XDGFCell {
     }
 
     @Internal
-    CellType getXmlObject() {
+    protected CellType getXmlObject() {
         return _cell;
     }
 

src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFConnection.java

@@ -19,6 +19,15 @@ package org.apache.poi.xdgf.usermodel;
 
 import com.microsoft.schemas.office.visio.x2012.main.ConnectType;
 
+/**
+ * Represents connections in a Visio diagram.
+ * 
+ * Note that just because something appears to be visually connected in a
+ * document does not mean that the user actually connected the elements. It
+ * turns out there are a lot of ways that a careless user can neglect to
+ * properly make connections that will not be recorded in the diagram
+ * in a machine readable way.
+ */
 public class XDGFConnection {
 
     // comments on frompart/topart taken from pkgVisio
@@ -126,7 +135,11 @@ public class XDGFConnection {
             return null;
     }
 
-    // see constants above
+    /**
+     * The ToPart property identifies the part of a shape to which another
+     * shape is glued, such as its begin point or endpoint, one of its edges,
+     * or a connection point.
+     */
     public Integer getToPart() {
         if (_connect.isSetToPart())
             return _connect.getToPart();

src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMaster.java

@@ -22,13 +22,14 @@ import org.apache.poi.util.Internal;
 import com.microsoft.schemas.office.visio.x2012.main.MasterType;
 
 /**
- * Provides the API to work with an underlying master
+ * Provides the API to work with an underlying master. Typically, each set of
+ * stencils used in a Visio diagram are found in a separate master for each.
  */
 public class XDGFMaster {
 
     private MasterType _master;
-    private XDGFMasterContents _content;
+    protected XDGFMasterContents _content;
-    XDGFSheet _pageSheet = null;
+    protected XDGFSheet _pageSheet = null;
 
     public XDGFMaster(MasterType master, XDGFMasterContents content,
             XDGFDocument document) {
@@ -41,7 +42,7 @@ public class XDGFMaster {
     }
 
     @Internal
-    MasterType getXmlObject() {
+    protected MasterType getXmlObject() {
         return _master;
     }
 

src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMasterContents.java

@@ -27,9 +27,12 @@ import org.apache.xmlbeans.XmlException;
 
 import com.microsoft.schemas.office.visio.x2012.main.MasterContentsDocument;
 
+/**
+ * Contains the actual contents of the master/stencil
+ */
 public class XDGFMasterContents extends XDGFBaseContents {
 
-    private XDGFMaster _master;
+    protected XDGFMaster _master;
 
     public XDGFMasterContents(PackagePart part, PackageRelationship rel,
             XDGFDocument document) {

src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMasters.java

@@ -36,19 +36,22 @@ import com.microsoft.schemas.office.visio.x2012.main.MasterType;
 import com.microsoft.schemas.office.visio.x2012.main.MastersDocument;
 import com.microsoft.schemas.office.visio.x2012.main.MastersType;
 
+/**
+ * A collection of masters (typically stencils) in a Visio document
+ */
 public class XDGFMasters extends XDGFXMLDocumentPart {
 
     MastersType _mastersObject;
 
     // key: id of master
-    Map<Long, XDGFMaster> _masters = new HashMap<Long, XDGFMaster>();
+    protected Map<Long, XDGFMaster> _masters = new HashMap<Long, XDGFMaster>();
 
     public XDGFMasters(PackagePart part, PackageRelationship rel, XDGFDocument document) {
         super(part, rel, document);
     }
 
     @Internal
-    MastersType getXmlObject() {
+    protected MastersType getXmlObject() {
         return _mastersObject;
     }
 

src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPage.java

@@ -31,10 +31,10 @@ import com.microsoft.schemas.office.visio.x2012.main.PageType;
  */
 public class XDGFPage {
 
-    PageType _page;
+    private PageType _page;
-    XDGFPageContents _content;
+    protected XDGFPageContents _content;
-    XDGFPages _pages;
+    protected XDGFPages _pages;
-    XDGFSheet _pageSheet = null;
+    protected XDGFSheet _pageSheet = null;
 
     public XDGFPage(PageType page, XDGFPageContents content,
             XDGFDocument document, XDGFPages pages) {
@@ -48,7 +48,7 @@ public class XDGFPage {
     }
 
     @Internal
-    PageType getXmlObject() {
+    protected PageType getXmlObject() {
         return _page;
     }
 
@@ -72,7 +72,9 @@ public class XDGFPage {
         return _pages.getPageList().indexOf(this) + 1;
     }
 
-    // height/width of page
+    /**
+     * @return width/height of page
+     */
     public Dimension2dDouble getPageSize() {
         XDGFCell w = _pageSheet.getCell("PageWidth");
         XDGFCell h = _pageSheet.getCell("PageHeight");
@@ -84,7 +86,9 @@ public class XDGFPage {
                 Double.parseDouble(h.getValue()));
     }
 
-    // origin of coordinate system
+    /**
+     * @return origin of coordinate system
+     */
     public Point2D.Double getPageOffset() {
         XDGFCell xoffcell = _pageSheet.getCell("XRulerOrigin");
         XDGFCell yoffcell = _pageSheet.getCell("YRulerOrigin");
@@ -101,7 +105,9 @@ public class XDGFPage {
         return new Point2D.Double(xoffset, yoffset);
     }
 
-    // bounding box of page
+    /**
+     * @return bounding box of page
+     */
     public Rectangle2D getBoundingBox() {
         Dimension2dDouble sz = getPageSize();
         Point2D.Double offset = getPageOffset();

src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPageContents.java

@@ -32,8 +32,8 @@ import com.microsoft.schemas.office.visio.x2012.main.PageContentsDocument;
 
 public class XDGFPageContents extends XDGFBaseContents {
 
-    Map<Long, XDGFMaster> _masters = new HashMap<Long, XDGFMaster>();
+    protected Map<Long, XDGFMaster> _masters = new HashMap<Long, XDGFMaster>();
-    XDGFPage _page;
+    protected XDGFPage _page;
 
     public XDGFPageContents(PackagePart part, PackageRelationship rel, XDGFDocument document) {
         super(part, rel, document);
@@ -71,6 +71,9 @@ public class XDGFPageContents extends XDGFBaseContents {
         }
     }
 
+    /**
+     * @return Parent page
+     */
     public XDGFPage getPage() {
         return _page;
     }

src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPages.java

@@ -90,7 +90,9 @@ public class XDGFPages extends XDGFXMLDocumentPart {
         }
     }
 
-    // ordered by page number
+    /**
+     * @return A list of pages ordered by page number
+     */
     public List<XDGFPage> getPageList() {
         return Collections.unmodifiableList(_pages);
     }

src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFRelation.java

@@ -33,7 +33,7 @@ public class XDGFRelation extends POIXMLRelation {
 
     public static final XDGFRelation DOCUMENT = new XDGFRelation(
             "application/vnd.ms-visio.drawing.main+xml",
-            "http://schemas.microsoft.com/visio/2010/relationships/document",
+            PackageRelationshipTypes.VISIO_CORE_DOCUMENT,
             "/visio/document.xml", null);
 
     public static final XDGFRelation MASTERS = new XDGFRelation(

src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFShape.java

@@ -173,8 +173,6 @@ public class XDGFShape extends XDGFSheet {
      * Shapes that have a 'Master' attribute refer to a specific master in the
      * page, whereas shapes with a 'MasterShape' attribute refer to a subshape
      * of a Master.
-     *
-     *
      */
     protected void setupMaster(XDGFPageContents pageContents,
             XDGFMasterContents master) {
@@ -295,7 +293,9 @@ public class XDGFShape extends XDGFSheet {
         return _geometry.get(idx);
     }
 
-    // only available if this is a shape group
+    /**
+     * Only available if this shape is a shape group, may be null 
+     */
     // -> May be null
     public List<XDGFShape> getShapes() {
         return _shapes;
@@ -334,7 +334,9 @@ public class XDGFShape extends XDGFSheet {
         return _masterShape;
     }
 
-    // returns the parent shape of this shape, if its in a subshape
+    /**
+     * @return The parent shape if this is a subshape, null otherwise
+     */
     public XDGFShape getParentShape() {
         return _parent;
     }
@@ -807,14 +809,20 @@ public class XDGFShape extends XDGFSheet {
                 _masterShape != null ? _masterShape._geometry : null);
     }
 
-    // returns a rectangle in local coordinates
+    /**
+     * @return rectangle in local coordinates
+     */
     public Rectangle2D.Double getBounds() {
         return new Rectangle2D.Double(0, 0, getWidth(), getHeight());
     }
     
-    // returns bounds as a path in local coordinates
+    /**
-    // -> useful if you need to transform to global coordinates
+     * @return returns bounds as a path in local coordinates, which is
-    // -> Don't use for 1d objects, fails for infinite line objects
+     *         userful if you need to transform to global coordinates
+     *         
+     * @warning Don't use this for 1d objects, and will fail for
+     *          infinite line objects
+     */
     public Path2D.Double getBoundsAsPath() {
 
         Double w = getWidth();
@@ -830,7 +838,9 @@ public class XDGFShape extends XDGFSheet {
         return bounds;
     }
 
-    // returns the path in local coordinates
+    /**
+     * @return The outline of the shape in local coordinates
+     */
     public Path2D.Double getPath() {
         for (GeometrySection geoSection : getGeometrySections()) {
             if (geoSection.getNoShow() == true)

src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFSheet.java

@@ -92,7 +92,11 @@ public abstract class XDGFSheet {
         return _document;
     }
 
-    // A cell is really just a setting
+    /**
+     * A cell is really just a setting
+     *
+     * @param cellName The particular setting you want
+     */
     public XDGFCell getCell(String cellName) {
         return _cells.get(cellName);
     }

src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFText.java

@@ -53,9 +53,11 @@ public class XDGFText {
         return ((TextTypeImpl) _text).getStringValue();
     }
     
-    // these are in the shape coordinate system
+    /**
-    // -> See
+     * These are in the shape coordinate system
-    // https://msdn.microsoft.com/en-us/library/hh644132(v=office.12).aspx
+     *
+     * @see https://msdn.microsoft.com/en-us/library/hh644132(v=office.12).aspx
+     */
     public Rectangle2D.Double getTextBounds() {
 
         double txtPinX = _parent.getTxtPinX();
@@ -73,8 +75,10 @@ public class XDGFText {
         return new Rectangle2D.Double(x, y, txtWidth, txtHeight);
     }
 
-    // returns bounds as a path in local coordinates
+    /**
-    // -> useful if you need to transform to global coordinates
+     * @return Text bounds as a path in local coordinates, which is useful
+     *         if you need to transform to global coordinates
+     */
     public Path2D.Double getBoundsAsPath() {
 
         Rectangle2D.Double rect = getTextBounds();
@@ -91,13 +95,18 @@ public class XDGFText {
         return bounds;
     }
     
-    // center of text in local coordinates
+    /**
+     * @return Center of text in local coordinates
+     */
     public Point2D.Double getTextCenter() {
         return new Point2D.Double(_parent.getTxtLocPinX(),
                 _parent.getTxtLocPinY());
     }
 
-    // assumes graphics is set properly to draw in the right style
+    /**
+     * When calling this to draw text, it assumes graphics is set properly
+     * to draw in the right style.
+     */
     public void draw(Graphics2D graphics) {
 
         String textContent = getTextContent();

src/ooxml/java/org/apache/poi/xdgf/usermodel/XmlVisioDocument.java

@@ -28,22 +28,39 @@ import org.apache.poi.POIXMLException;
 import org.apache.poi.openxml4j.exceptions.OpenXML4JException;
 import org.apache.poi.openxml4j.opc.OPCPackage;
 import org.apache.poi.openxml4j.opc.PackagePart;
+import org.apache.poi.openxml4j.opc.PackageRelationshipTypes;
 import org.apache.poi.util.PackageHelper;
 import org.apache.xmlbeans.XmlException;
 
 import com.microsoft.schemas.office.visio.x2012.main.VisioDocumentDocument1;
 import com.microsoft.schemas.office.visio.x2012.main.VisioDocumentType;
 
+/**
+ * This is your high-level starting point for working with Visio XML
+ * documents (.vsdx).
+ * 
+ * Currently, only read support has been implemented, and the API is
+ * not mature and is subject to change.
+ * 
+ * For more information about the visio XML format (with an XSD 1.0
+ * schema), you can find documentation at
+ * https://msdn.microsoft.com/en-us/library/hh645006(v=office.12).aspx
+ * 
+ * That document lacks in some areas, but you can find additional
+ * documentation and an updated XSD 1.1 schema at
+ * https://msdn.microsoft.com/en-us/library/office/jj684209(v=office.15).aspx
+ * 
+ * Each provides different details, but the SharePoint reference
+ * has better documentation and is more useful.
+ */
 public class XmlVisioDocument extends POIXMLDocument {
 
-    public static String CORE_DOCUMENT = "http://schemas.microsoft.com/visio/2010/relationships/document";
+    protected XDGFPages _pages;
-
+    protected XDGFMasters _masters;
-    XDGFPages _pages;
+    protected XDGFDocument _document;
-    XDGFMasters _masters;
-    XDGFDocument _document;
 
     public XmlVisioDocument(OPCPackage pkg) throws IOException {
-        super(pkg, CORE_DOCUMENT);
+        super(pkg, PackageRelationshipTypes.VISIO_CORE_DOCUMENT);
 
         VisioDocumentType document;
 

src/ooxml/java/org/apache/poi/xdgf/usermodel/section/CombinedIterable.java

@@ -23,7 +23,11 @@ import java.util.Map.Entry;
 import java.util.NoSuchElementException;
 import java.util.SortedMap;
 
-// iterates over the base and master
+/**
+ * An iterator used to iterate over the base and master items
+ *
+ * @param <T>
+ */
 public class CombinedIterable<T> implements Iterable<T> {
 
     final SortedMap<Long, T> _baseItems;

src/ooxml/java/org/apache/poi/xdgf/usermodel/shape/ShapeVisitor.java

@@ -32,15 +32,17 @@ import org.apache.poi.xdgf.usermodel.XDGFShape;
  */
 public abstract class ShapeVisitor {
 
-    ShapeVisitorAcceptor _acceptor;
+    protected ShapeVisitorAcceptor _acceptor;
 
     public ShapeVisitor() {
         _acceptor = getAcceptor();
     }
     
-    // is only called on construction of the visitor, allows
+    /**
-    // mixing visitors and acceptors
+     * Is only called on construction of the visitor, allows
-    public ShapeVisitorAcceptor getAcceptor() {
+     * mixing visitors and acceptors
+     */
+    protected ShapeVisitorAcceptor getAcceptor() {
         return new ShapeVisitorAcceptor() {
             @Override
             public boolean accept(XDGFShape shape) {

src/ooxml/java/org/apache/poi/xdgf/util/HierarchyPrinter.java

@@ -30,6 +30,10 @@ import org.apache.poi.xdgf.usermodel.XDGFShape;
 import org.apache.poi.xdgf.usermodel.XmlVisioDocument;
 import org.apache.poi.xdgf.usermodel.shape.ShapeVisitor;
 
+/**
+ * Debugging tool useful when trying to figure out the hierarchy of the
+ * shapes in a Visio diagram
+ */
 public class HierarchyPrinter {
 
     public static void printHierarchy(XDGFPage page, File outDir)

src/ooxml/java/org/apache/poi/xdgf/util/VsdxToPng.java

@@ -34,6 +34,12 @@ import org.apache.poi.xdgf.usermodel.XmlVisioDocument;
 import org.apache.poi.xdgf.usermodel.shape.ShapeDebuggerRenderer;
 import org.apache.poi.xdgf.usermodel.shape.ShapeRenderer;
 
+/**
+ * Converts a Visio diagram to a PNG file.
+ * 
+ * As more elements and styles are added/supported the output will get
+ * better, but it's very rough right now.
+ */
 public class VsdxToPng {
 
     public static void renderToPng(XDGFPage page, String outFilename,