nu.xom

## Class Comment

- Object
- - nu.xom.Node
  - - nu.xom.Comment

-     public class Comment
      extends Node

  This class represents an XML comment such as `<-- This is a comment-->`. A comment node cannot have any child nodes. It can be a child of an `Element` or a `Document`. It has essentially no internal substructure.

  Version:
    1.3.0
  Author:
    Elliotte Rusty Harold

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Comment(Comment comment)` Creates a new comment that's a copy of its argument.
    `Comment(String data)` Creates a new `Comment` object from string data.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Comment` | `copy()` Returns a deep copy of this `Comment` object which contains the same text, but does not have any parent.
    `Node` | `getChild(int position)` Throws `IndexOutOfBoundsException` because comments do not have children.
    `int` | `getChildCount()` Returns 0 because comments do not have children.
    `String` | `getValue()` Returns the value of this comment as defined by XPath 1.0.
    `void` | `setValue(String data)` Sets the content of this `Comment` object to the specified string.
    `String` | `toString()` Returns a string form of the comment suitable for debugging and diagnosis.
    `String` | `toXML()` Returns a `String` containing the actual XML form of the comment; for example, `<--This is a comment-->`.

    - ### Methods inherited from class nu.xom.Node

      `detach, equals, getBaseURI, getDocument, getParent, hashCode, query, query`

    - ### Methods inherited from class Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Comment

          public Comment(String data)

      Creates a new `Comment` object from string data. The data is checked for legality according to XML 1.0 rules. Illegal characters such as the form feed and null are not allowed. Furthermore, the two hyphen string "--" is not allowed; and the last character of the comment must not be a hyphen.

      Parameters:
        `data` - the initial text of the comment

    - #### Comment

          public Comment(Comment comment)

      Creates a new comment that's a copy of its argument. The copy has the same data but no parent node.

      Parameters:
        `comment` - the comment to copy

  - ### Method Detail

    - #### getValue

          public final String getValue()

      Returns the value of this comment as defined by XPath 1.0. The XPath string-value of a comment node is the string content of the node, not including the initial `<--` and closing `-->`.

      Specified by:
        `getValue` in class `Node`
      Returns:
        the content of the comment

    - #### setValue

          public void setValue(String data)

      Sets the content of this `Comment` object to the specified string. This string is checked for legality according to XML 1.0 rules. Characters that can be serialized such as < and & are allowed. However, illegal characters such as the form feed and unmatched halves of surrogate pairs are not allowed. Furthermore, the string may not contain a double hyphen (`--`) and may not end with a hyphen.

      Parameters:
        `data` - the text to install in the comment

    - #### getChild

          public final Node getChild(int position)

      Throws `IndexOutOfBoundsException` because comments do not have children.

      Specified by:
        `getChild` in class `Node`
      Parameters:
        `position` - the index of the child node to return
      Returns:
        never returns because comments do not have children; Always throws an exception.
      Throws:
        `IndexOutOfBoundsException` - because comments do not have children

    - #### getChildCount

          public final int getChildCount()

      Returns 0 because comments do not have children.

      Specified by:
        `getChildCount` in class `Node`
      Returns:
        zero

    - #### copy

          public Comment copy()

      Returns a deep copy of this `Comment` object which contains the same text, but does not have any parent. Thus, it can be inserted into a different document.

      Specified by:
        `copy` in class `Node`
      Returns:
        a deep copy of this `Comment` that is not part of a document

    - #### toXML

          public final String toXML()

      Returns a `String` containing the actual XML form of the comment; for example, `<--This is a comment-->`.

      Specified by:
        `toXML` in class `Node`
      Returns:
        a `String` containing a well-formed XML comment

    - #### toString

          public final String toString()

      Returns a string form of the comment suitable for debugging and diagnosis. It deliberately does not return an actual XML comment.

      Overrides:
        `toString` in class `Object`
      Returns:
        a representation of the `Comment` as a `String`

Copyright 2002-2020 Elliotte Rusty Harold
elharo@ibiblio.org