Fx ready

src/main/java/org/openautonomousconnection/luascript/hosts/DomHost.java

@@ -4,79 +4,79 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Host capability that exposes a DOM-like API.
+ * Abstraction over DOM access for scripting.
  *
- * <p>Element identity is the (stable) element id.</p>
+ * <p>All element references are by stable element {@code id}.</p>
  */
 public interface DomHost {
 
     /**
-     * Returns all element ids known to the renderer (must be stable).
+     * Returns a list of all element ids in the document.
      *
-     * @return list of element ids
+     * @return list of ids (never null)
      */
     List<String> getAllElementIds();
 
     /**
-     * Returns all attributes for the given element id.
+     * Returns all attributes of the element.
      *
      * @param elementId element id
-     * @return attributes map (attributeName -> attributeValue)
+     * @return attributes map (never null)
      */
     Map<String, String> getAttributes(String elementId);
 
     /**
-     * Returns the tag name of the element (lowercase recommended), e.g. "script", "button".
+     * Returns the element tag name, lowercase if possible.
      *
      * @param elementId element id
-     * @return tag name
+     * @return tag name (never null)
      */
     String getTagName(String elementId);
 
     /**
-     * Returns the text content of an element
+     * Returns the element text content.
      *
      * @param elementId element id
-     * @return text content (never null)
+     * @return text (never null)
      */
     String getTextContent(String elementId);
 
     /**
-     * Sets the text content of an element.
+     * Sets the element text content.
      *
      * @param elementId element id
-     * @param text      text
+     * @param text new text
      */
     void setTextContent(String elementId, String text);
 
     /**
-     * Gets a single attribute or null if missing.
+     * Returns an attribute value or null if missing.
      *
      * @param elementId element id
-     * @param name      attribute name
-     * @return value or null
+     * @param name attribute name
+     * @return value or null if missing
      */
     String getAttribute(String elementId, String name);
 
     /**
-     * Sets an attribute (creates it if missing).
+     * Sets an attribute value (empty string allowed).
      *
      * @param elementId element id
-     * @param name      attribute name
-     * @param value     attribute value
+     * @param name attribute name
+     * @param value attribute value
      */
     void setAttribute(String elementId, String name, String value);
 
     /**
-     * Removes an attribute.
+     * Removes an attribute from the element.
      *
      * @param elementId element id
-     * @param name      attribute name
+     * @param name attribute name
      */
     void removeAttribute(String elementId, String name);
 
     /**
-     * Returns parent id or null.
+     * Returns the parent element id or null if none.
      *
      * @param elementId element id
      * @return parent id or null
@@ -84,48 +84,48 @@ public interface DomHost {
     String getParentId(String elementId);
 
     /**
-     * Returns direct children ids.
+     * Returns children element ids.
      *
      * @param elementId element id
-     * @return children ids
+     * @return list of children ids (never null)
      */
     List<String> getChildrenIds(String elementId);
 
     /**
-     * Creates a new element (detached) and returns its id.
+     * Creates an element and makes it addressable immediately.
      *
-     * @param tagName     tag name
-     * @param requestedId optional requested id, may be null/blank for auto id
+     * @param tagName tag name
+     * @param requestedId requested id or null
      * @return created element id
      */
     String createElement(String tagName, String requestedId);
 
     /**
-     * Removes an element from the DOM.
+     * Removes an element from the document.
      *
      * @param elementId element id
      */
     void removeElement(String elementId);
 
     /**
-     * Moves/appends child under parent.
+     * Appends a child element to a parent.
      *
      * @param parentId parent id
-     * @param childId  child id
+     * @param childId child id
      */
     void appendChild(String parentId, String childId);
 
     /**
-     * Inserts child before an existing direct child.
+     * Inserts {@code childId} before {@code beforeChildId} within {@code parentId}.
      *
-     * @param parentId      parent id
-     * @param childId       child id
+     * @param parentId parent id
+     * @param childId child id
      * @param beforeChildId existing child id
      */
     void insertBefore(String parentId, String childId, String beforeChildId);
 
     /**
-     * Checks if an element id exists.
+     * Checks if an element with the given id exists.
      *
      * @param id element id
      * @return true if exists
@@ -133,18 +133,18 @@ public interface DomHost {
     boolean exists(String id);
 
     /**
-     * Returns element ids by tag.
+     * Queries elements by tag name and returns their ids.
      *
-     * @param tagName tag
-     * @return ids
+     * @param tagName tag name
+     * @return list of ids (never null)
      */
     List<String> queryByTag(String tagName);
 
     /**
-     * Returns element ids by class.
+     * Queries elements by class token and returns their ids.
      *
-     * @param className class
-     * @return ids
+     * @param className class name token
+     * @return list of ids (never null)
      */
     List<String> queryByClass(String className);
 }