improved jdoc

Author: rbri

src/main/java/org/htmlunit/html/DomElement.java

@@ -67,6 +67,8 @@
 import org.xml.sax.SAXException;
 
 /**
+ * A DOM element in an HTML or XML document.
+ *
  * @author Ahmed Ashour
  * @author Marc Guillemot
  * @author Tom Anderson

src/main/java/org/htmlunit/html/DomNode.java

@@ -1406,6 +1406,8 @@ public void moveBefore(final DomNode movedDomNode) {
     }
 
     /**
+     * Returns an iterable over the children of this node.
+     *
      * @return an {@link Iterable} over the children of this node
      */
     public final Iterable<DomNode> getChildren() {
@@ -1525,7 +1527,9 @@ public void remove() {
         }
 
         /**
-         * @return the next node, if there is one
+         * Returns the next node in the iteration.
+         *
+         * @return the next node, or {@code null} if there are no more nodes
          */
         public DomNode nextNode() {
             currentNode_ = nextNode_;
@@ -1601,7 +1605,9 @@ public void remove() {
         }
 
         /**
-         * @return the next node, if there is one
+         * Returns the next node in the iteration.
+         *
+         * @return the next node, or {@code null} if there are no more nodes
          */
         @SuppressWarnings("unchecked")
         public T nextNode() {
@@ -2140,8 +2146,12 @@ public DomElement getNextElementSibling() {
     }
 
     /**
-     * @param selectorString the selector to test
-     * @return the selected {@link DomElement} or null.
+     * Returns the closest ancestor element, or this element, that matches the
+     * specified CSS selector.
+     *
+     * @param selectorString the CSS selector to test
+     * @return the closest matching {@link DomElement}, or {@code null} if no
+     *         matching element is found
      */
     public DomElement closest(final String selectorString) {
         try {

src/main/java/org/htmlunit/html/HtmlForm.java

@@ -551,12 +551,13 @@ private <E extends HtmlElement> List<E> getFormElementsByAttribute(
     }
 
     /**
-     * @return A List containing all form controls in the form.
-     *         The form controls in the returned collection are in the same order
-     *         in which they appear in the form by following a preorder,
-     *         depth-first traversal of the tree. This is called tree order.
-     *         Only the following elements are returned:
-     *         button, fieldset, input, object, output, select, textarea.
+     * Returns the form controls contained in this form.
+     *
+     * @return a list containing all form controls in tree order (preorder,
+     *         depth-first traversal). Only the following elements are
+     *         included: {@code button}, {@code fieldset}, {@code input},
+     *         {@code object}, {@code output}, {@code select}, and
+     *         {@code textarea}
      */
     public List<HtmlElement> getFormElements() {
         return getElements(htmlElement -> {
@@ -601,8 +602,10 @@ public List<HtmlElement> getElementsJS() {
     }
 
     /**
-     * @param filter a predicate to filter the element
-     * @return all elements attached to this form and matching the filter predicate
+     * Returns the form elements that match the specified filter.
+     *
+     * @param filter the predicate used to select elements
+     * @return a list of form elements matching the specified filter
      */
     public List<HtmlElement> getElements(final Predicate<HtmlElement> filter) {
         final List<HtmlElement> elements = new ArrayList<>();
@@ -994,7 +997,9 @@ protected boolean isEmptyXmlTagExpanded() {
     }
 
     /**
-     * @return the value of the attribute {@code novalidate} or an empty string if that attribute isn't defined
+     * Returns whether form validation is disabled.
+     *
+     * @return {@code true} if the {@code novalidate} attribute is present
      */
     public final boolean isNoValidate() {
         return hasAttribute(ATTRIBUTE_NOVALIDATE);

src/main/java/org/htmlunit/html/HtmlImage.java

@@ -608,8 +608,10 @@ public int getWidthOrDefault() {
     }
 
     /**
-     * @return the {@link ImageData} of this image
-     * @throws IOException in case of error
+     * Returns the image data for this image.
+     *
+     * @return the {@link ImageData} for this image
+     * @throws IOException if an I/O error occurs while reading the image
      */
     public ImageData getImageData() throws IOException {
         readImageIfNeeded();
@@ -804,7 +806,10 @@ public DisplayStyle getDefaultStyleDisplay() {
     }
 
     /**
-     * @return true if the image was successfully downloaded
+     * Returns whether this image has finished loading.
+     *
+     * @return {@code true} if the image has finished loading or has no
+     *         {@code src} attribute
      */
     public boolean isComplete() {
         return isComplete_ || ATTRIBUTE_NOT_DEFINED == getSrcAttribute();

src/main/java/org/htmlunit/javascript/host/event/PointerEvent.java

@@ -151,71 +151,87 @@ public PointerEvent(final DomNode domNode, final String type, final boolean shif
     }
 
     /**
-     * @return the pointerId
+     * Returns the pointer identifier.
+     *
+     * @return the pointer identifier
      */
     @JsxGetter
     public long getPointerId() {
         return pointerId_;
     }
 
     /**
-     * @return the width
+     * Returns the pointer contact width.
+     *
+     * @return the pointer contact width
      */
     @JsxGetter
     public long getWidth() {
         return width_;
     }
 
     /**
-     * @return the height
+     * Returns the pointer contact height.
+     *
+     * @return the pointer contact height
      */
     @JsxGetter
     public long getHeight() {
         return height_;
     }
 
     /**
-     * @return the pressure
+     * Returns the normalized pointer pressure.
+     *
+     * @return the normalized pointer pressure
      */
     @JsxGetter
     public double getPressure() {
         return pressure_;
     }
 
     /**
-     * @return the tiltX
+     * Returns the pointer tilt along the X axis.
+     *
+     * @return the pointer tilt along the X axis
      */
     @JsxGetter
     public long getTiltX() {
         return tiltX_;
     }
 
     /**
-     * @return the tiltY
+     * Returns the pointer tilt along the Y axis.
+     *
+     * @return the pointer tilt along the Y axis
      */
     @JsxGetter
     public long getTiltY() {
         return tiltY_;
     }
 
     /**
-     * @return the pointerType
+     * Returns the pointer type.
+     *
+     * @return the pointer type
      */
     @JsxGetter
     public String getPointerType() {
         return pointerType_;
     }
 
     /**
-     * @return the isPrimary
+     * @return whether this is the primary pointer
      */
     @JsxGetter(propertyName = "isPrimary")
     public boolean isPrimary_js() {
         return isPrimary_;
     }
 
     /**
-     * @return the pointerType
+     * Returns the pointer altitude angle.
+     *
+     * @return the pointer altitude angle
      */
     @JsxGetter
     @SuppressWarnings("PMD.UseUnderscoresInNumericLiterals")
@@ -224,15 +240,19 @@ public double getAltitudeAngle() {
     }
 
     /**
-     * @return the pointerType
+     * Returns the pointer azimuth angle.
+     *
+     * @return the pointer azimuth angle
      */
     @JsxGetter
     public double getAzimuthAngle() {
         return azimuthAngle_;
     }
 
     /**
-     * @return the persistentDeviceId
+     * Returns the persistent device identifier.
+     *
+     * @return the persistent device identifier
      */
     @JsxGetter({CHROME, EDGE, FF})
     public double getPersistentDeviceId() {