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;