Skip to content

Commit 2a8d5f7

Browse files
rbrirbri
committed
improved javadoc
1 parent 36600ce commit 2a8d5f7

2 files changed

Lines changed: 60 additions & 43 deletions

File tree

‎src/main/java/org/htmlunit/cyberneko/HTMLTagBalancer.java‎

Lines changed: 33 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -220,13 +220,13 @@ public class HTMLTagBalancer
220220
*/
221221
protected boolean fSeenRootElementEnd;
222222

223-
/** True if seen {@code head} element. */
223+
/** True if an explicit (non-synthesized) {@code <html>} element has been seen. */
224224
protected boolean fSeenRealHtmlElement;
225225

226-
/** True if seen {@code head} element. */
226+
/** True if seen {@code <head>} element. */
227227
protected boolean fSeenHeadElement;
228228

229-
/** True if seen {@code body} element. */
229+
/** True if seen {@code <body>} element. */
230230
protected boolean fSeenBodyElement;
231231
private boolean fSeenBodyElementEnd;
232232

@@ -551,8 +551,20 @@ public void endDocument(final Augmentations augs) throws XNIException {
551551
}
552552

553553
/**
554-
* Consume elements that have been buffered, like &lt;/body&gt;&lt;/html&gt; that are first consumed
555-
* at the end of document
554+
* Consumes end-element events that have been buffered (e.g.
555+
* {@code </head>}, {@code </body>}, {@code </html>}) so they can be
556+
* replayed at the correct point in the document — typically at the
557+
* very end, after all outside content has been processed.
558+
* <p>
559+
* The size-1 and size-2 fast paths avoid allocating a copy of the
560+
* buffer list. These cover the overwhelmingly common cases:
561+
* <ul>
562+
* <li><b>size 1</b> — only {@code </head>} was buffered.</li>
563+
* <li><b>size 2</b> — {@code </body>} and {@code </html>} were
564+
* buffered (or {@code </head>} followed by {@code </body>}).</li>
565+
* </ul>
566+
* The general path (size &gt; 2) makes a defensive copy because
567+
* {@link #endElement} may re-enter this method or modify the buffer.
556568
*/
557569
private void consumeBufferedEndElements() {
558570
final int s = endElementsBuffer_.size();
@@ -1453,24 +1465,27 @@ public static class Info {
14531465
* <strong>Note:</strong>
14541466
* This constructor makes a copy of the element information.
14551467
*
1456-
* @param element The element qualified name.
1457-
* @param qname qname
1468+
* @param element The HTML element definition.
1469+
* @param qname The element's qualified name (will be deep-copied).
14581470
*/
14591471
public Info(final HTMLElements.Element element, final QName qname) {
14601472
this(element, qname, null);
14611473
}
14621474

1463-
/**
1464-
* Creates an element information object.
1465-
* <p>
1466-
* <strong>Note:</strong>
1467-
* This constructor makes a copy of the element information.
1468-
*
1469-
* @param element The element qualified name.
1470-
* @param attributes The element attributes.
1471-
* @param qname qname
1472-
*/
1473-
public Info(final HTMLElements.Element element, final QName qname,
1475+
/**
1476+
* Creates an element information object.
1477+
* <p>
1478+
* <strong>Note:</strong>
1479+
* This constructor makes a deep copy of the qualified name and,
1480+
* for inline elements, of the attributes so that formatting
1481+
* elements can be re-opened with their original attributes.
1482+
*
1483+
* @param element The HTML element definition.
1484+
* @param qname The element's qualified name (will be deep-copied).
1485+
* @param attributes The element attributes to copy, or {@code null} if
1486+
* no attribute snapshot is needed.
1487+
*/
1488+
public Info(final HTMLElements.Element element, final QName qname,
14741489
final XMLAttributes attributes) {
14751490
this.element = element;
14761491
this.qname = new QName(qname);

‎src/main/java/org/htmlunit/cyberneko/xerces/util/XMLAttributesImpl.java‎

Lines changed: 27 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -67,8 +67,9 @@ public XMLAttributesImpl(final XMLAttributesImpl attributes) {
6767
* marked as specified in the XML instance document unless set otherwise using
6868
* the <code>setSpecified</code> method.
6969
* <p>
70-
* <strong>Note:</strong> If an attribute of the same name already exists, the
71-
* old values for the attribute are replaced by the new values.
70+
* <strong>Note:</strong> This implementation does <em>not</em> check whether an
71+
* attribute of the same name already exists. If duplicate prevention is required,
72+
* the caller must verify uniqueness before calling this method.
7273
*
7374
* @param name The attribute name.
7475
* @param type The attribute type. The type name is determined by the type
@@ -122,14 +123,21 @@ public void addAttribute(final QName name, final String type, final String value
122123
}
123124

124125
/**
125-
* Same as {@link #addAttribute(QName, String, String, String, boolean)} but with an additional
126-
* nonNormalizedValue parameter
127-
*
128-
* @param name the attribute name
129-
* @param type the attribute type
130-
* @param value the attribute value
131-
* @param nonNormalizedValue the non-normalized attribute value
132-
* @param specified the specified attribute value
126+
* Adds an attribute together with its non-normalized (plain) value.
127+
* <p>
128+
* This variant stores both the normalized {@code value} and the original
129+
* {@code nonNormalizedValue} so that downstream consumers can access the
130+
* raw attribute text via {@link #getNonNormalizedValue(int)}.
131+
* <p>
132+
* Like the other {@code addAttribute} overloads, this method does
133+
* <em>not</em> check for duplicate attribute names.
134+
*
135+
* @param name the attribute name
136+
* @param type the attribute type (e.g. "CDATA")
137+
* @param value the normalized attribute value
138+
* @param nonNormalizedValue the original, non-normalized attribute value
139+
* @param specified {@code true} if the attribute was specified in the
140+
* instance document
133141
*/
134142
public void addAttribute(final QName name, final String type, final String value,
135143
final String nonNormalizedValue, final boolean specified) {
@@ -328,22 +336,16 @@ public String getValue(final String qname) {
328336
}
329337

330338
/**
331-
* Return the name of an attribute in this list (by position).
332-
*
339+
* <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span>
333340
* <p>
334-
* The names must be unique: the SAX parser shall not include the same attribute
335-
* twice. Attributes without values (those declared #IMPLIED without a value
336-
* specified in the start tag) will be omitted from the list.
337-
* </p>
338-
*
339-
* <p>
340-
* If the attribute name has a namespace prefix, the prefix will still be
341-
* attached.
342-
* </p>
341+
* Returns the raw (prefixed) name of the attribute at the given index.
342+
* This is a convenience shortcut equivalent to
343+
* {@code getName(index).getRawname()} but with bounds checking.
343344
*
344345
* @param index The index of the attribute in the list (starting at 0).
345-
* @return The name of the indexed attribute, or null if the index is out of
346-
* range.
346+
* @return The raw name of the indexed attribute, or null if the index is
347+
* out of range.
348+
* @see #getQName(int)
347349
* @see #getLength
348350
*/
349351
public String getNameRawName(final int index) {
@@ -458,7 +460,7 @@ public String getType(final String uri, final String localName) {
458460
* Look up an attribute's Namespace URI by index.
459461
*
460462
* @param index The attribute index (zero-based).
461-
* @return The Namespace URI
463+
* @return The Namespace URI, or null if the index is out of range.
462464
* @see #getLength
463465
*/
464466
@Override
@@ -477,7 +479,7 @@ public String getURI(final int index) {
477479
* values.
478480
* </p>
479481
*
480-
* @param uri The Namespace URI, or null if the
482+
* @param uri The Namespace URI, or null if the name has no Namespace URI.
481483
* @param localName The local name of the attribute.
482484
* @return The attribute value as a string, or null if the attribute is not in
483485
* the list.

0 commit comments

Comments
 (0)