Skip to content

Commit 130a5af

Browse files
rbrirbri
committed
improved jdoc
1 parent 36e019a commit 130a5af

4 files changed

Lines changed: 123 additions & 52 deletions

File tree

‎src/main/java/org/htmlunit/javascript/host/dom/AbstractList.java‎

Lines changed: 27 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -131,13 +131,17 @@ public boolean avoidObjectDetection() {
131131
}
132132

133133
/**
134+
* Sets whether this collection should avoid object detection.
135+
*
134136
* @param newValue the new value
135137
*/
136138
public void setAvoidObjectDetection(final boolean newValue) {
137139
avoidObjectDetection_ = newValue;
138140
}
139141

140142
/**
143+
* Sets the function that determines the effect of attribute changes on the cache.
144+
*
141145
* @param effectOnCacheFunction the new function
142146
*/
143147
public void setEffectOnCacheFunction(
@@ -149,7 +153,9 @@ public void setEffectOnCacheFunction(
149153
}
150154

151155
/**
152-
* @return elementSupplier
156+
* Returns the supplier used to retrieve the collection elements.
157+
*
158+
* @return the element supplier
153159
*/
154160
protected Supplier<List<DomNode>> getElementSupplier() {
155161
return elementsSupplier_;
@@ -167,7 +173,9 @@ public void setElementsSupplier(final Supplier<List<DomNode>> elementsSupplier)
167173
}
168174

169175
/**
170-
* @return isMatchingPredicate
176+
* Returns the predicate used to determine whether a node belongs to this collection.
177+
*
178+
* @return the matching predicate
171179
*/
172180
protected Predicate<DomNode> getIsMatchingPredicate() {
173181
return isMatchingPredicate_;
@@ -234,6 +242,9 @@ public List<DomNode> getElements() {
234242
return cachedElements;
235243
}
236244

245+
/**
246+
* Registers the DOM and attribute change listeners for this collection.
247+
*/
237248
private void registerListener() {
238249
if (!listenerRegistered_) {
239250
final DomNode domNode = getDomNodeOrNull();
@@ -297,8 +308,9 @@ else if (!matchingElements.isEmpty()) {
297308
}
298309

299310
/**
300-
* Constructs a new instance with an initial cache value.
301-
* @param parentScope the parent scope, on which we listen for changes
311+
* Creates a new collection backed by the specified initial elements.
312+
*
313+
* @param parentScope the parent scope on which to listen for changes
302314
* @param initialElements the initial content for the cache
303315
* @return the newly created instance
304316
*/
@@ -338,8 +350,9 @@ else if (matchingElements.size() == 1) {
338350
}
339351

340352
/**
341-
* Returns the length.
342-
* @return the length
353+
* Returns the number of elements in this collection.
354+
*
355+
* @return the number of elements
343356
*/
344357
public int getLength() {
345358
return getElements().size();
@@ -433,6 +446,11 @@ public void attributeReplaced(final HtmlAttributeChangeEvent event) {
433446
}
434447
}
435448

449+
/**
450+
* Clears the cached collection elements if required by the specified attribute change.
451+
*
452+
* @param event the attribute change event
453+
*/
436454
private void handleChangeOnCache(final HtmlAttributeChangeEvent event) {
437455
final AbstractList nodes = nodeList_.get();
438456
if (null == nodes) {
@@ -457,9 +475,10 @@ private void clearCache() {
457475
}
458476

459477
/**
460-
* Gets the scriptable for the provided element that may already be the right scriptable.
478+
* Returns the scriptable object for the specified element.
479+
*
461480
* @param object the object for which to get the scriptable
462-
* @return the scriptable
481+
* @return the scriptable object
463482
*/
464483
protected Scriptable getScriptableForElement(final Object object) {
465484
if (object instanceof Scriptable scriptable) {

‎src/main/java/org/htmlunit/javascript/host/dom/Node.java‎

Lines changed: 63 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -66,108 +66,144 @@
6666
public class Node extends EventTarget {
6767

6868
/**
69+
* The node is an element.
70+
*
6971
* @see org.w3c.dom.Node#ELEMENT_NODE
7072
*/
7173
@JsxConstant
7274
public static final int ELEMENT_NODE = org.w3c.dom.Node.ELEMENT_NODE;
7375

7476
/**
77+
* The node is an attribute.
78+
*
7579
* @see org.w3c.dom.Node#ATTRIBUTE_NODE
7680
*/
7781
@JsxConstant
7882
public static final int ATTRIBUTE_NODE = org.w3c.dom.Node.ATTRIBUTE_NODE;
7983

8084
/**
85+
* The node is a text node.
86+
*
8187
* @see org.w3c.dom.Node#TEXT_NODE
8288
*/
8389
@JsxConstant
8490
public static final int TEXT_NODE = org.w3c.dom.Node.TEXT_NODE;
8591

8692
/**
93+
* The node is a CDATA section.
94+
*
8795
* @see org.w3c.dom.Node#CDATA_SECTION_NODE
8896
*/
8997
@JsxConstant
9098
public static final int CDATA_SECTION_NODE = org.w3c.dom.Node.CDATA_SECTION_NODE;
9199

92100
/**
101+
* The node is an entity reference.
102+
*
93103
* @see org.w3c.dom.Node#ENTITY_REFERENCE_NODE
94104
*/
95105
@JsxConstant
96106
public static final int ENTITY_REFERENCE_NODE = org.w3c.dom.Node.ENTITY_REFERENCE_NODE;
97107

98108
/**
109+
* The node is an entity.
110+
*
99111
* @see org.w3c.dom.Node#ENTITY_NODE
100112
*/
101113
@JsxConstant
102114
public static final int ENTITY_NODE = org.w3c.dom.Node.ENTITY_NODE;
103115

104116
/**
117+
* The node is a processing instruction.
118+
*
105119
* @see org.w3c.dom.Node#PROCESSING_INSTRUCTION_NODE
106120
*/
107121
@JsxConstant
108122
public static final int PROCESSING_INSTRUCTION_NODE = org.w3c.dom.Node.PROCESSING_INSTRUCTION_NODE;
109123

110124
/**
125+
* The node is a comment.
126+
*
111127
* @see org.w3c.dom.Node#COMMENT_NODE
112128
*/
113129
@JsxConstant
114130
public static final int COMMENT_NODE = org.w3c.dom.Node.COMMENT_NODE;
115131

116132
/**
133+
* The node is a document.
134+
*
117135
* @see org.w3c.dom.Node#DOCUMENT_NODE
118136
*/
119137
@JsxConstant
120138
public static final int DOCUMENT_NODE = org.w3c.dom.Node.DOCUMENT_NODE;
121139

122140
/**
141+
* The node is a document type.
142+
*
123143
* @see org.w3c.dom.Node#DOCUMENT_TYPE_NODE
124144
*/
125145
@JsxConstant
126146
public static final int DOCUMENT_TYPE_NODE = org.w3c.dom.Node.DOCUMENT_TYPE_NODE;
127147

128148
/**
149+
* The node is a document fragment.
150+
*
129151
* @see org.w3c.dom.Node#DOCUMENT_FRAGMENT_NODE
130152
*/
131153
@JsxConstant
132154
public static final int DOCUMENT_FRAGMENT_NODE = org.w3c.dom.Node.DOCUMENT_FRAGMENT_NODE;
133155

134156
/**
157+
* The node is a notation.
158+
*
135159
* @see org.w3c.dom.Node#NOTATION_NODE
136160
*/
137161
@JsxConstant
138162
public static final int NOTATION_NODE = org.w3c.dom.Node.NOTATION_NODE;
139163

140164
/**
165+
* The nodes are disconnected.
166+
*
141167
* @see org.w3c.dom.Node#DOCUMENT_POSITION_DISCONNECTED
142168
*/
143169
@JsxConstant
144170
public static final int DOCUMENT_POSITION_DISCONNECTED = org.w3c.dom.Node.DOCUMENT_POSITION_DISCONNECTED;
145171

146172
/**
173+
* The reference node precedes the other node.
174+
*
147175
* @see org.w3c.dom.Node#DOCUMENT_POSITION_PRECEDING
148176
*/
149177
@JsxConstant
150178
public static final int DOCUMENT_POSITION_PRECEDING = org.w3c.dom.Node.DOCUMENT_POSITION_PRECEDING;
151179

152180
/**
181+
* The reference node follows the other node.
182+
*
153183
* @see org.w3c.dom.Node#DOCUMENT_POSITION_FOLLOWING
154184
*/
155185
@JsxConstant
156186
public static final int DOCUMENT_POSITION_FOLLOWING = org.w3c.dom.Node.DOCUMENT_POSITION_FOLLOWING;
157187

158188
/**
189+
* The reference node contains the other node.
190+
*
159191
* @see org.w3c.dom.Node#DOCUMENT_POSITION_CONTAINS
160192
*/
161193
@JsxConstant
162194
public static final int DOCUMENT_POSITION_CONTAINS = org.w3c.dom.Node.DOCUMENT_POSITION_CONTAINS;
163195

164196
/**
197+
* The reference node is contained by the other node.
198+
*
165199
* @see org.w3c.dom.Node#DOCUMENT_POSITION_CONTAINED_BY
166200
*/
167201
@JsxConstant
168202
public static final int DOCUMENT_POSITION_CONTAINED_BY = org.w3c.dom.Node.DOCUMENT_POSITION_CONTAINED_BY;
169203

170204
/**
205+
* The document position is implementation-specific.
206+
*
171207
* @see org.w3c.dom.Node#DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
172208
*/
173209
@JsxConstant
@@ -523,11 +559,11 @@ public Node cloneNode(final boolean deep) {
523559
}
524560

525561
/**
526-
* Check if 2 nodes are equals.
527-
* For detail specifications
528-
* @see <a href="https://dom.spec.whatwg.org/#concept-node-equals">concept-node-equals</a>
562+
* Determines whether this node is structurally equal to the specified node.
563+
*
529564
* @param other the node to compare with
530-
* @return true or false
565+
* @return {@code true} if the two nodes are structurally equal
566+
* @see <a href="https://dom.spec.whatwg.org/#concept-node-equals">WHATWG DOM: concept-node-equals</a>
531567
*/
532568
@JsxFunction
533569
public boolean isEqualNode(final Node other) {
@@ -642,35 +678,32 @@ else if (this instanceof Text || this instanceof Comment) {
642678
}
643679

644680
/**
645-
* This method provides a way to determine whether two Node references returned by
646-
* the implementation reference the same object.
647-
* When two Node references are references to the same object, even if through a proxy,
648-
* the references may be used completely interchangeably, such that all attributes
649-
* have the same values and calling the same DOM method on either reference always has exactly the same effect.
681+
* Determines whether this node and the specified node are the same object.
650682
*
651683
* @param other the node to test against
652-
*
653-
* @return whether this node is the same node as the given one
684+
* @return {@code true} if this node is the same node as the given one
654685
*/
655686
@JsxFunction
656687
public boolean isSameNode(final Object other) {
657688
return this == other;
658689
}
659690

660691
/**
661-
* Returns whether this node has any children.
662-
* @return boolean true if this node has any children, false otherwise
692+
* Returns whether this node has any child nodes.
693+
*
694+
* @return {@code true} if this node has any child nodes
663695
*/
664696
@JsxFunction
665697
public boolean hasChildNodes() {
666698
return getDomNodeOrDie().getChildren().iterator().hasNext();
667699
}
668700

669701
/**
670-
* @param namespace string containing the namespace to look the prefix up
671-
* @return a string containing the prefix for a given namespace URI,
672-
* if present, and null if not. When multiple prefixes are possible,
673-
* the first prefix is returned.
702+
* Returns the namespace prefix for the specified namespace URI.
703+
*
704+
* @param namespace the namespace URI
705+
* @return the corresponding namespace prefix, or {@code null} if none exists;
706+
* if multiple prefixes are possible, the first one is returned
674707
*/
675708
@JsxFunction
676709
public String lookupPrefix(final String namespace) {
@@ -788,8 +821,9 @@ public HtmlUnitScriptable getOwnerDocument() {
788821
}
789822

790823
/**
791-
* Returns the owner document.
792-
* @return the document
824+
* Returns the root node of this node's tree.
825+
*
826+
* @return the root node
793827
*/
794828
@JsxFunction
795829
public Node getRootNode() {
@@ -868,9 +902,10 @@ public NamedNodeMap getAttributes() {
868902
}
869903

870904
/**
871-
* Checks whether the given element is contained within this object.
872-
* @param element element object that specifies the element to check
873-
* @return true if the element is contained within this object
905+
* Returns whether the specified node is contained within this node.
906+
*
907+
* @param element the node to check
908+
* @return {@code true} if the specified node is contained within this node
874909
*/
875910
@JsxFunction
876911
public boolean contains(final Object element) {
@@ -900,8 +935,9 @@ public String getBaseURI() {
900935
}
901936

902937
/**
903-
* Returns true when the current element has any attributes or not.
904-
* @return true if an attribute is specified on this element
938+
* Returns whether this node has any attributes.
939+
*
940+
* @return {@code true} if this node has one or more attributes
905941
*/
906942
public boolean hasAttributes() {
907943
return getDomNodeOrDie().hasAttributes();
@@ -1003,9 +1039,10 @@ protected Element getLastElementChild() {
10031039
}
10041040

10051041
/**
1006-
* Gets the children of the current node.
1042+
* Returns the child elements of this node.
1043+
*
1044+
* @return a live collection of this node's child elements
10071045
* @see <a href="http://msdn.microsoft.com/en-us/library/ms537446.aspx">MSDN documentation</a>
1008-
* @return the child at the given position
10091046
*/
10101047
protected HTMLCollection getChildren() {
10111048
final DomNode node = getDomNodeOrDie();

‎src/main/java/org/htmlunit/javascript/host/dom/Selection.java‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,9 @@ public void jsConstructor() {
5353
}
5454

5555
/**
56-
* @return a string currently being represented by the selection object,
57-
* i.e. the currently selected text.
56+
* Returns the text represented by this selection.
57+
*
58+
* @return the currently selected text
5859
*/
5960
@JsxFunction(functionName = "toString")
6061
public String jsToString() {

0 commit comments

Comments
 (0)