Update documentation for Scanner and AnchorDict, and fix formatting.

include/yaml-cpp/contrib/anchordict.h

@@ -12,11 +12,13 @@
 #include "../anchor.h"
 
 namespace YAML {
-/// AnchorDict
-/// . An object that stores and retrieves values correlating to anchor_t
-///   values.
-/// . Efficient implementation that can make assumptions about how anchor_t
-///   values are assigned by the Parser class.
+/**
+ * An object that stores and retrieves values correlating to {@link anchor_t}
+ * values.
+ *
+ * <p>Efficient implementation that can make assumptions about how
+ * {@code anchor_t} values are assigned by the {@link Parser} class.
+ */
 template <class T>
 class AnchorDict {
  public:

src/scanner.h

@@ -24,15 +24,24 @@ namespace YAML {
 class Node;
 class RegEx;
 
+/**
+ * A scanner transforms a stream of characters into a stream of tokens.
+ */
 class Scanner {
  public:
-  Scanner(std::istream &in);
+  explicit Scanner(std::istream &in);
   ~Scanner();
 
-  // token queue management (hopefully this looks kinda stl-ish)
+  /** Returns true if there are no more tokens to be read. */
   bool empty();
+
+  /** Removes the next token in the queue. */
   void pop();
+
+  /** Returns, but does not remove, the next token in the queue. */
   Token &peek();
+
+  /** Returns the current mark in the input stream. */
   Mark mark() const;
 
  private:
@@ -52,11 +61,29 @@ class Scanner {
 
  private:
   // scanning
+
+  /**
+   * Scans until there's a valid token at the front of the queue, or the queue
+   * is empty. The state can be checked by {@link #empty}, and the next token
+   * retrieved by {@link #peek}.
+   */
   void EnsureTokensInQueue();
+
+  /**
+   * The main scanning function; this method branches out to scan whatever the
+   * next token should be.
+   */
   void ScanNextToken();
+
+  /** Eats the input stream until it reaches the next token-like thing. */
   void ScanToNextToken();
+
+  /** Sets the initial conditions for starting a stream. */
   void StartStream();
+
+  /** Closes out the stream, finish up, etc. */
   void EndStream();
+
   Token *PushToken(Token::TYPE type);
 
   bool InFlowContext() const { return !m_flows.empty(); }
@@ -64,9 +91,29 @@ class Scanner {
   std::size_t GetFlowLevel() const { return m_flows.size(); }
 
   Token::TYPE GetStartTokenFor(IndentMarker::INDENT_TYPE type) const;
+
+  /**
+   * Pushes an indentation onto the stack, and enqueues the proper token
+   * (sequence start or mapping start).
+   *
+   * @return the indent marker it generates (if any).
+   */
   IndentMarker *PushIndentTo(int column, IndentMarker::INDENT_TYPE type);
+
+  /**
+   * Pops indentations off the stack until it reaches the current indentation
+   * level, and enqueues the proper token each time. Then pops all invalid
+   * indentations off.
+   */
   void PopIndentToHere();
+
+  /**
+   * Pops all indentations (except for the base empty one) off the stack, and
+   * enqueues the proper token each time.
+   */
   void PopAllIndents();
+
+  /** Pops a single indent, pushing the proper token. */
   void PopIndent();
   int GetTopIndent() const;
 
@@ -78,9 +125,17 @@ class Scanner {
   bool VerifySimpleKey();
   void PopAllSimpleKeys();
 
+  /**
+   * Throws a ParserException with the current token location (if available),
+   * and does not parse any more tokens.
+   */
   void ThrowParserException(const std::string &msg) const;
 
   bool IsWhitespaceToBeEaten(char ch);
+
+  /**
+   * Returns the appropriate regex to check if the next token is a value token.
+   */
   const RegEx &GetValueRegex() const;
 
   struct SimpleKey {