Add javadoc to a few interfaces

Author: carlosame

svgom-api/src/main/java/org/w3c/dom/svg/SVGPoint.java

@@ -14,14 +14,58 @@
 
 import org.w3c.dom.DOMException;
 
+/**
+ * An <code>(x, y)</code> coordinate pair.
+ * <p>
+ * When used in matrix operations, an SVGPoint is treated as a vector of the
+ * form:
+ * </p>
+ * 
+ * <pre>
+ * [x]
+ * [y]
+ * [1]
+ * </pre>
+ */
 public interface SVGPoint {
+
+	/**
+	 * Get the x coordinate.
+	 * 
+	 * @return the x coordinate.
+	 */
 	float getX();
 
+	/**
+	 * Sets the x coordinate.
+	 * 
+	 * @param x the x coordinate.
+	 * @throws DOMException NO_MODIFICATION_ALLOWED_ERR if this value is read only.
+	 */
 	void setX(float x) throws DOMException;
 
+	/**
+	 * Get the y coordinate.
+	 * 
+	 * @return the y coordinate.
+	 */
 	float getY();
 
+	/**
+	 * Sets the y coordinate.
+	 * 
+	 * @param y the y coordinate.
+	 * @throws DOMException NO_MODIFICATION_ALLOWED_ERR if this value is read only.
+	 */
 	void setY(float y) throws DOMException;
 
+	/**
+	 * Applies a 2x3 matrix transformation on this SVGPoint object and returns a
+	 * new, transformed SVGPoint object.
+	 * 
+	 * @param matrix the matrix.
+	 * @return a new SVGPoint object.
+	 */
 	SVGPoint matrixTransform(SVGMatrix matrix);
+
 }

svgom-api/src/main/java/org/w3c/dom/svg/SVGPointList.java

@@ -14,20 +14,110 @@
 
 import org.w3c.dom.DOMException;
 
+/**
+ * A list of {@link SVGPoint} objects.
+ */
 public interface SVGPointList {
+
+	/**
+	 * The number of items in the list.
+	 * 
+	 * @return The number of items.
+	 */
 	int getNumberOfItems();
 
+	/**
+	 * Clears all existing current items from the list, with the result being an
+	 * empty list.
+	 * 
+	 * @throws DOMException NO_MODIFICATION_ALLOWED_ERR if this list is read only.
+	 */
 	void clear() throws DOMException;
 
+	/**
+	 * Clear this list and add the given value to it.
+	 * 
+	 * @param newItem the value.
+	 * @return the value.
+	 * @throws DOMException NO_MODIFICATION_ALLOWED_ERR if this list is read only.
+	 */
 	SVGPoint initialize(SVGPoint newItem) throws DOMException, SVGException;
 
+	/**
+	 * Get the specified item from the list.
+	 * 
+	 * @param index The index of the item from the list which is to be returned. The
+	 *              first item is number 0.
+	 * @return the specified item from the list.
+	 * @throws DOMException INDEX_SIZE_ERR if the index number is greater than or
+	 *                      equal to numberOfItems.
+	 */
 	SVGPoint getItem(int index) throws DOMException;
 
+	/**
+	 * Inserts a new item into the list at the specified position.
+	 * <p>
+	 * The first item is number 0. If newItem is already in a list, it is removed
+	 * from its previous list before it is inserted into this list. The inserted
+	 * item is the item itself and not a copy. If the item is already in this list,
+	 * note that the index of the item to insert before is before the removal of the
+	 * item.
+	 * </p>
+	 * 
+	 * @param newItem The item which is to be inserted into the list.
+	 * @param index   The index of the item before which the new item is to be
+	 *                inserted. The first item is number 0. If the index is equal to
+	 *                0, then the new item is inserted at the front of the list. If
+	 *                the index is greater than or equal to numberOfItems, then the
+	 *                new item is appended to the end of the list.
+	 * @return The inserted item.
+	 * @throws DOMException NO_MODIFICATION_ALLOWED_ERR if this list is read only.
+	 */
 	SVGPoint insertItemBefore(SVGPoint newItem, int index) throws DOMException, SVGException;
 
+	/**
+	 * Replaces an existing item in the list with a new item.
+	 * <p>
+	 * If newItem is already in a list, it is removed from its previous list before
+	 * it is inserted into this list. The inserted item is the item itself and not a
+	 * copy. If the item is already in this list, note that the index of the item to
+	 * replace is before the removal of the item.
+	 * </p>
+	 * 
+	 * @param newItem The item which is to be inserted into the list.
+	 * @param index   The index of the item which is to be replaced. The first item
+	 *                is number 0.
+	 * @return The inserted item.
+	 * @throws DOMException NO_MODIFICATION_ALLOWED_ERR if this list is read only,
+	 *                      INDEX_SIZE_ERR if the index number is greater than or
+	 *                      equal to numberOfItems.
+	 */
 	SVGPoint replaceItem(SVGPoint newItem, int index) throws DOMException, SVGException;
 
+	/**
+	 * Removes an existing item from the list.
+	 * 
+	 * @param index The index of the item which is to be removed. The first item is
+	 *              number 0.
+	 * @return The removed item.
+	 * @throws DOMException NO_MODIFICATION_ALLOWED_ERR if this list is read only,
+	 *                      INDEX_SIZE_ERR if the index number is greater than or
+	 *                      equal to numberOfItems.
+	 */
 	SVGPoint removeItem(int index) throws DOMException;
 
+	/**
+	 * Inserts a new item at the end of the list.
+	 * <p>
+	 * If newItem is already in a list, it is removed from its previous list before
+	 * it is inserted into this list. The inserted item is the item itself and not a
+	 * copy.
+	 * </p>
+	 * 
+	 * @param newItem The item which is to be appended.
+	 * @return the new item.
+	 * @throws DOMException NO_MODIFICATION_ALLOWED_ERR if this list is read only.
+	 */
 	SVGPoint appendItem(SVGPoint newItem) throws DOMException, SVGException;
+
 }

svgom-api/src/main/java/org/w3c/dom/svg/SVGPreserveAspectRatio.java

@@ -14,29 +14,100 @@
 
 import org.w3c.dom.DOMException;
 
+/**
+ * Represents the <code>preserveAspectRatio</code> attribute.
+ */
 public interface SVGPreserveAspectRatio {
 	// Alignment Types
+
+	/**
+	 * Some other value.
+	 */
 	short SVG_PRESERVEASPECTRATIO_UNKNOWN = 0;
+
+	/**
+	 * The none keyword.
+	 */
 	short SVG_PRESERVEASPECTRATIO_NONE = 1;
+
+	/**
+	 * The xMinYMin keyword.
+	 */
 	short SVG_PRESERVEASPECTRATIO_XMINYMIN = 2;
+
+	/**
+	 * The xMidYMin keyword.
+	 */
 	short SVG_PRESERVEASPECTRATIO_XMIDYMIN = 3;
+
+	/**
+	 * The xMaxYMin keyword.
+	 */
 	short SVG_PRESERVEASPECTRATIO_XMAXYMIN = 4;
+
+	/**
+	 * The xMinYMid keyword.
+	 */
 	short SVG_PRESERVEASPECTRATIO_XMINYMID = 5;
+
+	/**
+	 * The xMidYMid keyword.
+	 */
 	short SVG_PRESERVEASPECTRATIO_XMIDYMID = 6;
+
+	/**
+	 * The xMaxYMid keyword.
+	 */
 	short SVG_PRESERVEASPECTRATIO_XMAXYMID = 7;
+
+	/**
+	 * The xMinYMax keyword.
+	 */
 	short SVG_PRESERVEASPECTRATIO_XMINYMAX = 8;
+
+	/**
+	 * The xMidYMax keyword.
+	 */
 	short SVG_PRESERVEASPECTRATIO_XMIDYMAX = 9;
+
+	/**
+	 * The xMaxYMax keyword.
+	 */
 	short SVG_PRESERVEASPECTRATIO_XMAXYMAX = 10;
+
 	// Meet-or-slice Types
+
+	/**
+	 * Some other value.
+	 */
 	short SVG_MEETORSLICE_UNKNOWN = 0;
+
+	/**
+	 * The meet keyword.
+	 */
 	short SVG_MEETORSLICE_MEET = 1;
+
+	/**
+	 * The slice keyword.
+	 */
 	short SVG_MEETORSLICE_SLICE = 2;
 
+	/**
+	 * Get the alignment keyword part of the ‘preserveAspectRatio’ value.
+	 * 
+	 * @return the alignment keyword part of the ‘preserveAspectRatio’ value.
+	 */
 	short getAlign();
 
 	void setAlign(short align) throws DOMException;
 
+	/**
+	 * Get the meet-or-slice keyword part of the ‘preserveAspectRatio’ value.
+	 * 
+	 * @return the meet-or-slice keyword part of the ‘preserveAspectRatio’ value.
+	 */
 	short getMeetOrSlice();
 
 	void setMeetOrSlice(short meetOrSlice) throws DOMException;
+
 }

svgom-api/src/main/java/org/w3c/dom/svg/SVGURIReference.java

@@ -12,6 +12,20 @@
 
 package org.w3c.dom.svg;
 
+/**
+ * Represents the <code>href</code> attribute and the deprecated
+ * <code>xlink:href</code> attribute.
+ */
 public interface SVGURIReference {
+
+	/**
+	 * Gets the value of the <code>href</code> attribute and, on elements that are
+	 * defined to support it, the deprecated <code>xlink:href</code> attribute.
+	 * 
+	 * @return the <code>href</code> attribute if exists, or the deprecated
+	 *         <code>xlink:href</code> attribute if exists and the element is
+	 *         defined to support it, {@code null} otherwise.
+	 */
 	SVGAnimatedString getHref();
+
 }