Added some of the missing JavaDoc comments.
diff --git a/src/main/java/org/yaml/snakeyaml/composer/Composer.java b/src/main/java/org/yaml/snakeyaml/composer/Composer.java
index 528133e..b6db4b7 100644
--- a/src/main/java/org/yaml/snakeyaml/composer/Composer.java
+++ b/src/main/java/org/yaml/snakeyaml/composer/Composer.java
@@ -41,7 +41,11 @@
import org.yaml.snakeyaml.resolver.Resolver;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Creates a node graph from parser events.
+ * <p>
+ * Corresponds to the 'Compose' step as described in chapter 3.1 of the
+ * <a href="http://www.yaml.org/spec/1.2/spec.html">YAML Specification</a>.
+ * </p>
*/
public class Composer {
private final Parser parser;
@@ -56,6 +60,10 @@
this.recursiveNodes = new HashSet<Node>();
}
+ /**
+ * Checks if further documents are available.
+ * @return <code>true</code> if there is at least one more document.
+ */
public boolean checkNode() {
// Drop the STREAM-START event.
if (parser.checkEvent(StreamStartEvent.class)) {
@@ -65,6 +73,11 @@
return !parser.checkEvent(StreamEndEvent.class);
}
+ /**
+ * Reads and composes the next document.
+ * @return The root node of the document or <code>null</code> if no
+ * more documents are available.
+ */
public Node getNode() {
// Get the root node of the next document.
if (!parser.checkEvent(StreamEndEvent.class)) {
@@ -74,6 +87,15 @@
}
}
+ /**
+ * Reads a document from a source that contains only one
+ * document.
+ * <p>
+ * If the stream contains more than one document an exception is thrown.
+ * </p>
+ * @return The root node of the document or <code>null</code> if no
+ * document is available.
+ */
public Node getSingleNode() {
// Drop the STREAM-START event.
parser.getEvent();
diff --git a/src/main/java/org/yaml/snakeyaml/events/AliasEvent.java b/src/main/java/org/yaml/snakeyaml/events/AliasEvent.java
index 33458a1..6e43ef9 100644
--- a/src/main/java/org/yaml/snakeyaml/events/AliasEvent.java
+++ b/src/main/java/org/yaml/snakeyaml/events/AliasEvent.java
@@ -18,7 +18,7 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Marks the inclusion of a previously anchored node.
*/
public final class AliasEvent extends NodeEvent {
public AliasEvent(String anchor, Mark startMark, Mark endMark) {
diff --git a/src/main/java/org/yaml/snakeyaml/events/CollectionEndEvent.java b/src/main/java/org/yaml/snakeyaml/events/CollectionEndEvent.java
index 690c318..83f40d5 100644
--- a/src/main/java/org/yaml/snakeyaml/events/CollectionEndEvent.java
+++ b/src/main/java/org/yaml/snakeyaml/events/CollectionEndEvent.java
@@ -18,7 +18,7 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Base class for the end events of the collection nodes.
*/
public abstract class CollectionEndEvent extends Event {
diff --git a/src/main/java/org/yaml/snakeyaml/events/CollectionStartEvent.java b/src/main/java/org/yaml/snakeyaml/events/CollectionStartEvent.java
index 6e616d2..3ad1696 100644
--- a/src/main/java/org/yaml/snakeyaml/events/CollectionStartEvent.java
+++ b/src/main/java/org/yaml/snakeyaml/events/CollectionStartEvent.java
@@ -18,7 +18,7 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Base class for the start events of the collection nodes.
*/
public abstract class CollectionStartEvent extends NodeEvent {
private final String tag;
@@ -36,14 +36,27 @@
this.flowStyle = flowStyle;
}
+ /**
+ * Tag of this collection.
+ * @return The tag of this collection, or <code>null</code> if no explicit tag is available.
+ */
public String getTag() {
return this.tag;
}
+ /**
+ * <code>true</code> if the tag can be omitted while this collection is emitted.
+ * @return True if the tag can be omitted while this collection is emitted.
+ */
public boolean getImplicit() {
return this.implicit;
}
+ /**
+ * <code>true</code> if this collection is in flow style, <code>false</code>
+ * for block style.
+ * @return If this collection is in flow style.
+ */
public Boolean getFlowStyle() {
return this.flowStyle;
}
diff --git a/src/main/java/org/yaml/snakeyaml/events/DocumentEndEvent.java b/src/main/java/org/yaml/snakeyaml/events/DocumentEndEvent.java
index c02232f..8534eb6 100644
--- a/src/main/java/org/yaml/snakeyaml/events/DocumentEndEvent.java
+++ b/src/main/java/org/yaml/snakeyaml/events/DocumentEndEvent.java
@@ -18,7 +18,10 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Marks the end of a document.
+ * <p>
+ * This event follows the document's content.
+ * </p>
*/
public final class DocumentEndEvent extends Event {
private final boolean explicit;
diff --git a/src/main/java/org/yaml/snakeyaml/events/DocumentStartEvent.java b/src/main/java/org/yaml/snakeyaml/events/DocumentStartEvent.java
index 3bccfa0..b9488f6 100644
--- a/src/main/java/org/yaml/snakeyaml/events/DocumentStartEvent.java
+++ b/src/main/java/org/yaml/snakeyaml/events/DocumentStartEvent.java
@@ -20,7 +20,10 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Marks the beginning of a document.
+ * <p>
+ * This event followed by the document's content and a {@link DocumentEndEvent}.
+ * </p>
*/
public final class DocumentStartEvent extends Event {
private final boolean explicit;
@@ -39,10 +42,22 @@
return explicit;
}
+ /**
+ * YAML version the document conforms to.
+ * @return <code>null</code>if the document has no explicit
+ * <code>%YAML</code> directive.
+ * Otherwise an array with two components, the major and minor part of
+ * the version (in this order).
+ */
public Integer[] getVersion() {
return version;
}
+ /**
+ * Tag shorthands as defined by the <code>%TAG</code> directive.
+ * @return Mapping of 'handles' to 'prefixes' (the handles
+ * include the '!' characters).
+ */
public Map<String, String> getTags() {
return tags;
}
diff --git a/src/main/java/org/yaml/snakeyaml/events/Event.java b/src/main/java/org/yaml/snakeyaml/events/Event.java
index 055b796..4339308 100644
--- a/src/main/java/org/yaml/snakeyaml/events/Event.java
+++ b/src/main/java/org/yaml/snakeyaml/events/Event.java
@@ -18,7 +18,8 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Basic unit of output from a {@link org.yaml.snakeyaml.parser.Parser}
+ * or input of a {@link org.yaml.snakeyaml.emitter.Emitter}.
*/
public abstract class Event {
private final Mark startMark;
@@ -47,6 +48,7 @@
protected String getArguments() {
return "";
}
+
/*
* for tests only
diff --git a/src/main/java/org/yaml/snakeyaml/events/MappingEndEvent.java b/src/main/java/org/yaml/snakeyaml/events/MappingEndEvent.java
index a797089..134ce6f 100644
--- a/src/main/java/org/yaml/snakeyaml/events/MappingEndEvent.java
+++ b/src/main/java/org/yaml/snakeyaml/events/MappingEndEvent.java
@@ -18,7 +18,9 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Marks the end of a mapping node.
+ *
+ * @see MappingStartEvent
*/
public final class MappingEndEvent extends CollectionEndEvent {
diff --git a/src/main/java/org/yaml/snakeyaml/events/MappingStartEvent.java b/src/main/java/org/yaml/snakeyaml/events/MappingStartEvent.java
index 469ea52..68b02fa 100644
--- a/src/main/java/org/yaml/snakeyaml/events/MappingStartEvent.java
+++ b/src/main/java/org/yaml/snakeyaml/events/MappingStartEvent.java
@@ -18,7 +18,20 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Marks the beginning of a mapping node.
+ * <p>
+ * This event is followed by a number of key value pairs.
+ * <br>
+ * The pairs are not in any particular order. However, the value
+ * always directly follows the corresponding key.
+ * <br>
+ * After the key value pairs follows a {@link MappingEndEvent}.
+ * </p>
+ * <p>
+ * There must be an even number of node events between the start
+ * and end event.
+ * </p>
+ * @see MappingEndEvent
*/
public final class MappingStartEvent extends CollectionStartEvent {
public MappingStartEvent(String anchor, String tag, boolean implicit, Mark startMark,
diff --git a/src/main/java/org/yaml/snakeyaml/events/NodeEvent.java b/src/main/java/org/yaml/snakeyaml/events/NodeEvent.java
index 3cc1638..e7ec518 100644
--- a/src/main/java/org/yaml/snakeyaml/events/NodeEvent.java
+++ b/src/main/java/org/yaml/snakeyaml/events/NodeEvent.java
@@ -18,7 +18,8 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Base class for all events that mark the beginning
+ * of a node.
*/
public abstract class NodeEvent extends Event {
@@ -29,6 +30,14 @@
this.anchor = anchor;
}
+ /**
+ * Node anchor by which this node might later be referenced
+ * by a {@link AliasEvent}.
+ * <p>
+ * Note that {@link AliasEvent}s are by it self <code>NodeEvent</code>s
+ * and use this property to indicate the referenced anchor.
+ * @return Anchor of this node or <code>null</code> if no anchor is defined.
+ */
public String getAnchor() {
return this.anchor;
}
diff --git a/src/main/java/org/yaml/snakeyaml/events/ScalarEvent.java b/src/main/java/org/yaml/snakeyaml/events/ScalarEvent.java
index 9b45136..9311440 100644
--- a/src/main/java/org/yaml/snakeyaml/events/ScalarEvent.java
+++ b/src/main/java/org/yaml/snakeyaml/events/ScalarEvent.java
@@ -18,7 +18,7 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Marks a scalar value.
*/
public final class ScalarEvent extends NodeEvent {
private final String tag;
@@ -40,14 +40,36 @@
this.style = style;
}
+ /**
+ * Tag of this scalar.
+ * @return The tag of this scalar, or <code>null</code> if no explicit tag is available.
+ */
public String getTag() {
return this.tag;
}
+ /**
+ * Style of the scalar.
+ * <dl>
+ * <dt>''</dt><dd>Flow Style - Plain</dd>
+ * <dt>'\''</dt><dd>Flow Style - Single-Quoted</dd>
+ * <dt>'"'</dt><dd>Flow Style - Double-Quoted</dd>
+ * <dt>'|'</dt><dd>Block Style - Literal</dd>
+ * <dt>'>'</dt><dd>Block Style - Folded</dd>
+ * </dl>
+ * @return Style of the scalar.
+ */
public Character getStyle() {
return this.style;
}
+ /**
+ * String representation of the value.
+ * <p>
+ * Without quotes and escaping.
+ * </p>
+ * @return Value as Unicode string.
+ */
public String getValue() {
return this.value;
}
@@ -60,5 +82,4 @@
protected String getArguments() {
return super.getArguments() + ", tag=" + tag + ", " + implicit + ", value=" + value;
}
-
}
diff --git a/src/main/java/org/yaml/snakeyaml/events/SequenceEndEvent.java b/src/main/java/org/yaml/snakeyaml/events/SequenceEndEvent.java
index e474bf6..8e10809 100644
--- a/src/main/java/org/yaml/snakeyaml/events/SequenceEndEvent.java
+++ b/src/main/java/org/yaml/snakeyaml/events/SequenceEndEvent.java
@@ -18,7 +18,9 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Marks the end of a sequence.
+ *
+ * @see SequenceStartEvent
*/
public final class SequenceEndEvent extends CollectionEndEvent {
diff --git a/src/main/java/org/yaml/snakeyaml/events/SequenceStartEvent.java b/src/main/java/org/yaml/snakeyaml/events/SequenceStartEvent.java
index e4eee23..5521964 100644
--- a/src/main/java/org/yaml/snakeyaml/events/SequenceStartEvent.java
+++ b/src/main/java/org/yaml/snakeyaml/events/SequenceStartEvent.java
@@ -18,7 +18,12 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Marks the beginning of a sequence node.
+ * <p>
+ * This event is followed by the elements contained in the sequence, and
+ * a {@link SequenceEndEvent}.
+ * </p>
+ * @see SequenceEndEvent
*/
public final class SequenceStartEvent extends CollectionStartEvent {
public SequenceStartEvent(String anchor, String tag, boolean implicit, Mark startMark,
diff --git a/src/main/java/org/yaml/snakeyaml/events/StreamEndEvent.java b/src/main/java/org/yaml/snakeyaml/events/StreamEndEvent.java
index 7646f4b..eed1bf6 100644
--- a/src/main/java/org/yaml/snakeyaml/events/StreamEndEvent.java
+++ b/src/main/java/org/yaml/snakeyaml/events/StreamEndEvent.java
@@ -18,7 +18,15 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Marks the end of a stream that might have contained multiple documents.
+ * <p>
+ * This event is the last event that a parser emits. Together
+ * with {@link StreamStartEvent} (which is the first event a parser emits)
+ * they mark the beginning and the end of a stream of documents.
+ * </p>
+ * <p>
+ * See {@link Event} for an exemplary output.
+ * </p>
*/
public final class StreamEndEvent extends Event {
public StreamEndEvent(Mark startMark, Mark endMark) {
diff --git a/src/main/java/org/yaml/snakeyaml/events/StreamStartEvent.java b/src/main/java/org/yaml/snakeyaml/events/StreamStartEvent.java
index 6009920..5bdbd4f 100644
--- a/src/main/java/org/yaml/snakeyaml/events/StreamStartEvent.java
+++ b/src/main/java/org/yaml/snakeyaml/events/StreamStartEvent.java
@@ -18,7 +18,15 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Marks the start of a stream that might contain multiple documents.
+ * <p>
+ * This event is the first event that a parser emits. Together
+ * with {@link StreamEndEvent} (which is the last event a parser emits)
+ * they mark the beginning and the end of a stream of documents.
+ * </p>
+ * <p>
+ * See {@link Event} for an exemplary output.
+ * </p>
*/
public final class StreamStartEvent extends Event {
diff --git a/src/main/java/org/yaml/snakeyaml/nodes/CollectionNode.java b/src/main/java/org/yaml/snakeyaml/nodes/CollectionNode.java
index 18f4663..9df2161 100644
--- a/src/main/java/org/yaml/snakeyaml/nodes/CollectionNode.java
+++ b/src/main/java/org/yaml/snakeyaml/nodes/CollectionNode.java
@@ -18,7 +18,8 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Base class for the two collection types {@link MappingNode mapping}
+ * and {@link CollectionNode collection}.
*/
public abstract class CollectionNode extends Node {
private Boolean flowStyle;
@@ -28,6 +29,11 @@
this.flowStyle = flowStyle;
}
+
+ /**
+ * Serialization style of this collection.
+ * @return <code>true</code> for flow style, <code>false</code> for block style.
+ */
public Boolean getFlowStyle() {
return flowStyle;
}
diff --git a/src/main/java/org/yaml/snakeyaml/nodes/MappingNode.java b/src/main/java/org/yaml/snakeyaml/nodes/MappingNode.java
index d87e410..5fb533b 100644
--- a/src/main/java/org/yaml/snakeyaml/nodes/MappingNode.java
+++ b/src/main/java/org/yaml/snakeyaml/nodes/MappingNode.java
@@ -20,7 +20,10 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Represents a map.
+ * <p>
+ * A map is a collection of unsorted key-value pairs.
+ * </p>
*/
public class MappingNode extends CollectionNode {
private Class<? extends Object> keyType;
@@ -48,6 +51,10 @@
return NodeId.mapping;
}
+ /**
+ * Returns the entries of this map.
+ * @return List of entries.
+ */
public List<NodeTuple> getValue() {
for (NodeTuple nodes : value) {
nodes.getKeyNode().setType(keyType);
diff --git a/src/main/java/org/yaml/snakeyaml/nodes/Node.java b/src/main/java/org/yaml/snakeyaml/nodes/Node.java
index b6f0aca..5792540 100644
--- a/src/main/java/org/yaml/snakeyaml/nodes/Node.java
+++ b/src/main/java/org/yaml/snakeyaml/nodes/Node.java
@@ -18,7 +18,17 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Base class for all nodes.
+ * <p>
+ * The nodes form the node-graph described in the
+ * <a href="http://www.yaml.org/spec/1.2/spec.html">YAML Specification</a>.
+ * </p>
+ * <p>
+ * While loading, the node graph is usually created by the
+ * {@link org.yaml.snakeyaml.composer.Composer},
+ * and later transformed into application specific Java classes by the
+ * classes from the {@link org.yaml.snakeyaml.constructor} package.
+ * </p>
*/
public abstract class Node {
private String tag;
@@ -42,6 +52,13 @@
this.useClassConstructor = null;
}
+ /**
+ * Tag of this node.
+ * <p>
+ * Every node has a tag assigned. The tag
+ * is either local or global.
+ * @return Tag of this node.
+ */
public String getTag() {
return this.tag;
}
@@ -89,6 +106,22 @@
this.twoStepsConstruction = twoStepsConstruction;
}
+ /**
+ * Indicates if this node must be constructed in two steps.
+ * <p>
+ * Two-step construction is required whenever a node is
+ * a child (direct or indirect) of it self. That is,
+ * if a recursive structure is build using anchors and aliases.
+ * </p>
+ * <p>
+ * Set by {@link org.yaml.snakeyaml.composer.Composer},
+ * used during the construction process.
+ * </p>
+ * <p>
+ * Only relevant during loading.
+ * </p>
+ * @return <code>true</code> if the node is self referenced.
+ */
public boolean isTwoStepsConstruction() {
return twoStepsConstruction;
}
@@ -113,6 +146,10 @@
this.useClassConstructor = useClassConstructor;
}
+ /**
+ * Indicates if the tag was added by {@link org.yaml.snakeyaml.resolver.Resolver}.
+ * @return <code>true</code> if the tag of this node was resolved</code>
+ */
public boolean isResolved() {
return resolved;
}
diff --git a/src/main/java/org/yaml/snakeyaml/nodes/NodeId.java b/src/main/java/org/yaml/snakeyaml/nodes/NodeId.java
index cde1517..846605d 100644
--- a/src/main/java/org/yaml/snakeyaml/nodes/NodeId.java
+++ b/src/main/java/org/yaml/snakeyaml/nodes/NodeId.java
@@ -15,6 +15,9 @@
*/
package org.yaml.snakeyaml.nodes;
+/**
+ * Enum for the three basic YAML types: scalar, sequence and mapping.
+ */
public enum NodeId {
scalar, sequence, mapping;
}
diff --git a/src/main/java/org/yaml/snakeyaml/nodes/NodeTuple.java b/src/main/java/org/yaml/snakeyaml/nodes/NodeTuple.java
index f0cd54d..32be6cd 100644
--- a/src/main/java/org/yaml/snakeyaml/nodes/NodeTuple.java
+++ b/src/main/java/org/yaml/snakeyaml/nodes/NodeTuple.java
@@ -15,6 +15,9 @@
*/
package org.yaml.snakeyaml.nodes;
+/**
+ * Stores one key value pair used in a map.
+ */
public class NodeTuple {
private final Node keyNode;
@@ -28,10 +31,17 @@
this.valueNode = valueNode;
}
+ /**
+ * Key node.
+ */
public Node getKeyNode() {
return keyNode;
}
+ /**
+ * Value node.
+ * @return value
+ */
public Node getValueNode() {
return valueNode;
}
diff --git a/src/main/java/org/yaml/snakeyaml/nodes/ScalarNode.java b/src/main/java/org/yaml/snakeyaml/nodes/ScalarNode.java
index 71159eb..3ccc7dd 100644
--- a/src/main/java/org/yaml/snakeyaml/nodes/ScalarNode.java
+++ b/src/main/java/org/yaml/snakeyaml/nodes/ScalarNode.java
@@ -18,7 +18,10 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Represents a scalar node.
+ * <p>
+ * Scalar nodes form the leaves in the node graph.
+ * </p>
*/
public class ScalarNode extends Node {
private Character style;
@@ -39,6 +42,11 @@
this.resolved = resolved;
}
+ /**
+ * Serialized representation of this node.
+ * @see org.yaml.snakeyaml.events.ScalarEvent
+ * @return
+ */
public Character getStyle() {
return style;
}
@@ -48,6 +56,10 @@
return NodeId.scalar;
}
+ /**
+ * Value of this scalar.
+ * @return Scalar's value.
+ */
public String getValue() {
return value;
}
diff --git a/src/main/java/org/yaml/snakeyaml/nodes/SequenceNode.java b/src/main/java/org/yaml/snakeyaml/nodes/SequenceNode.java
index 3cec975..d78af98 100644
--- a/src/main/java/org/yaml/snakeyaml/nodes/SequenceNode.java
+++ b/src/main/java/org/yaml/snakeyaml/nodes/SequenceNode.java
@@ -20,7 +20,10 @@
import org.yaml.snakeyaml.error.Mark;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Represents a sequence.
+ * <p>
+ * A sequence is a ordered collection of nodes.
+ * </p>
*/
public class SequenceNode extends CollectionNode {
private Class<? extends Object> listType;
@@ -46,13 +49,17 @@
return NodeId.sequence;
}
+ /**
+ * Returns the elements in this sequence.
+ * @return Nodes (sorted).
+ */
public List<Node> getValue() {
for (Node node : value) {
node.setType(listType);
}
return value;
}
-
+
public void setListType(Class<? extends Object> listType) {
this.listType = listType;
}
diff --git a/src/main/java/org/yaml/snakeyaml/parser/Parser.java b/src/main/java/org/yaml/snakeyaml/parser/Parser.java
index 585cc2c..0c935e6 100644
--- a/src/main/java/org/yaml/snakeyaml/parser/Parser.java
+++ b/src/main/java/org/yaml/snakeyaml/parser/Parser.java
@@ -20,14 +20,53 @@
import org.yaml.snakeyaml.events.Event;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * This interface represents an input stream of {@link Event Events}.
+ * <p>
+ * The parser and the scanner form together the 'Parse' step in
+ * the loading process (see chapter 3.1 of the
+ * <a href="http://www.yaml.org/spec/1.2/spec.html">YAML Specification</a>).
+ * </p>
+ *
+ * @see org.yaml.snakeyaml.events.Event
*/
public interface Parser {
+
+ /**
+ * Check if the next event is one of the given types.
+ *
+ * @param choices List of event types.
+ * @return <code>true</code> if the next event can be assigned to a
+ * variable of at least one of the given types. Returns <code>false</code>
+ * if no more events are available.
+ * @throws ParserException Thrown in case of malformed input.
+ */
public boolean checkEvent(List<Class<? extends Event>> choices);
+ /**
+ * Check if the next event is assignable to the given type.
+ * <p>
+ * This is a convenience method to avoid <code>List</code> creation if
+ * calling {@link #checkEvent(List)} for
+ * a single type.
+ * </p>
+ * @param choice Event type.
+ * @return True if the next event is an instance of <code>type</code>.
+ * False if no more events are available.
+ * @throws ParserException Thrown in case of malformed input.
+ */
public boolean checkEvent(Class<? extends Event> choice);
+ /**
+ * Return the next event, but do not delete it from the stream.
+ * @return The event that will be returned on the next call to {@link #getEvent}
+ * @throws ParserException Thrown in case of malformed input.
+ */
public Event peekEvent();
+ /**
+ * Returns the next event.
+ * <p>The event will be removed from the stream.</p>
+ * @throws ParserException Thrown in case of malformed input.
+ */
public Event getEvent();
}
diff --git a/src/main/java/org/yaml/snakeyaml/parser/ParserException.java b/src/main/java/org/yaml/snakeyaml/parser/ParserException.java
index 816a747..24deba5 100644
--- a/src/main/java/org/yaml/snakeyaml/parser/ParserException.java
+++ b/src/main/java/org/yaml/snakeyaml/parser/ParserException.java
@@ -19,11 +19,22 @@
import org.yaml.snakeyaml.error.MarkedYAMLException;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Exception thrown by the {@link Parser} implementations in case of
+ * malformed input.
*/
public class ParserException extends MarkedYAMLException {
private static final long serialVersionUID = -2349253802798398038L;
+ /**
+ * Constructs an instance.
+ * @param context Part of the input document in which vicinity
+ * the problem occurred.
+ * @param contextMark Position of the <code>context</code>
+ * within the document.
+ * @param problem Part of the input document that caused the problem.
+ * @param problemMark Position of the <code>problem</code>.
+ * within the document.
+ */
public ParserException(String context, Mark contextMark, String problem, Mark problemMark) {
super(context, contextMark, problem, problemMark, null, null);
}
diff --git a/src/main/java/org/yaml/snakeyaml/parser/Production.java b/src/main/java/org/yaml/snakeyaml/parser/Production.java
index bf6a2fa..1fc0ada 100644
--- a/src/main/java/org/yaml/snakeyaml/parser/Production.java
+++ b/src/main/java/org/yaml/snakeyaml/parser/Production.java
@@ -17,6 +17,9 @@
import org.yaml.snakeyaml.events.Event;
+/**
+ * Helper for {@link ParserImpl}.
+ */
interface Production {
public Event produce();
}
diff --git a/src/main/java/org/yaml/snakeyaml/scanner/Scanner.java b/src/main/java/org/yaml/snakeyaml/scanner/Scanner.java
index 3e7b079..b8284ff 100644
--- a/src/main/java/org/yaml/snakeyaml/scanner/Scanner.java
+++ b/src/main/java/org/yaml/snakeyaml/scanner/Scanner.java
@@ -20,28 +20,53 @@
import org.yaml.snakeyaml.tokens.Token;
/**
- * Produce <code>Token<code>s.
- *
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * This interface represents an input stream of {@link Token Tokens}.
+ * <p>
+ * The parser and the scanner form together the 'Parse' step in
+ * the loading process (see chapter 3.1 of the
+ * <a href="http://www.yaml.org/spec/1.2/spec.html">YAML Specification</a>).
+ * </p>
+ *
+ * @see org.yaml.snakeyaml.tokens.Token
*/
public interface Scanner {
+
/**
* Check if the next token is one of the given types.
+ *
+ * @param choices List of token types.
+ * @return <code>true</code> if the next token can be assigned to a
+ * variable of at least one of the given types. Returns <code>false</code>
+ * if no more tokens are available.
+ * @throws ScannerException Thrown in case of malformed input.
*/
boolean checkToken(List<Class<? extends Token>> choices);
/**
- * Convenience method to avoid List creation
+ * Check if the next token is assignable to the given type.
+ * <p>
+ * This is a convenience method to avoid <code>List</code> creation if
+ * calling {@link #checkToken(List)} for
+ * a single type.
+ * </p>
+ * @param choice Token type.
+ * @return True if the next token is an instance of <code>type</code>.
+ * False if no more tokens are available.
+ * @throws ScannerException Thrown in case of malformed input.
*/
boolean checkToken(Class<? extends Token> choice);
/**
- * Return the next token, but do not delete it from the queue.
+ * Return the next token, but do not delete it from the stream.
+ * @return The token that will be returned on the next call to {@link #getToken}
+ * @throws ScannerException Thrown in case of malformed input.
*/
Token peekToken();
/**
- * Return the next token.
+ * Returns the next token.
+ * <p>The token will be removed from the stream.</p>
+ * @throws ScannerException Thrown in case of malformed input.
*/
Token getToken();
}
diff --git a/src/main/java/org/yaml/snakeyaml/scanner/ScannerException.java b/src/main/java/org/yaml/snakeyaml/scanner/ScannerException.java
index 6615d8c..2029a07 100644
--- a/src/main/java/org/yaml/snakeyaml/scanner/ScannerException.java
+++ b/src/main/java/org/yaml/snakeyaml/scanner/ScannerException.java
@@ -19,17 +19,39 @@
import org.yaml.snakeyaml.error.MarkedYAMLException;
/**
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * Exception thrown by the {@link Scanner} implementations in case of
+ * malformed input.
*/
public class ScannerException extends MarkedYAMLException {
-
+
private static final long serialVersionUID = 4782293188600445954L;
+ /**
+ * Constructs an instance.
+ * @param context Part of the input document in which vicinity
+ * the problem occurred.
+ * @param contextMark Position of the <code>context</code>
+ * within the document.
+ * @param problem Part of the input document that caused the problem.
+ * @param problemMark Position of the <code>problem</code>
+ * within the document.
+ * @param note Message for the user with further information about the problem.
+ */
public ScannerException(String context, Mark contextMark, String problem, Mark problemMark,
String note) {
super(context, contextMark, problem, problemMark, note);
}
+ /**
+ * Constructs an instance.
+ * @param context Part of the input document in which vicinity
+ * the problem occurred.
+ * @param contextMark Position of the <code>context</code>
+ * within the document.
+ * @param problem Part of the input document that caused the problem.
+ * @param problemMark Position of the <code>problem</code>
+ * within the document.
+ */
public ScannerException(String context, Mark contextMark, String problem, Mark problemMark) {
this(context, contextMark, problem, problemMark, null);
}
diff --git a/src/main/java/org/yaml/snakeyaml/scanner/SimpleKey.java b/src/main/java/org/yaml/snakeyaml/scanner/SimpleKey.java
index a6b416f..70cc017 100644
--- a/src/main/java/org/yaml/snakeyaml/scanner/SimpleKey.java
+++ b/src/main/java/org/yaml/snakeyaml/scanner/SimpleKey.java
@@ -19,8 +19,11 @@
/**
* Simple keys treatment.
+ * <p>
+ * Helper class for {@link ScannerImpl}.
+ * </p>
*
- * @see <a href="http://pyyaml.org/wiki/PyYAML">PyYAML</a> for more information
+ * @see ScannerImpl
*/
final class SimpleKey {
private int tokenNumber;
