Context Navigation

← Previous Changeset
Next Changeset →

Changeset 266

Timestamp:

01/03/08 22:33:04 (5 years ago)

Author:

Message:

Drop doxygen support, add more API documentation, API changes.

Location:

libyaml/trunk

Files:

: 1 deleted
: 3 edited

README (modified) (3 diffs)
doc (deleted)
include/Makefile.am (modified) (1 diff)
include/yaml.h (modified) (60 diffs)

Legend:

: Unmodified
: Added
: Removed

libyaml/trunk/README

-                      r220
+                      r266
 LibYAML - A C library for parsing and emitting YAML.
-The project is in an early stage of development.
 To build and install the library, run:
 …
 # make install
+For more information, check the LibYAML homepage:
+For the API reference, check the file 'include/yaml.h'.  Examples on how to use
+LibYAML could be found in the 'tests' directory.
+Check the LibYAML homepage for more information:
 'http://pyyaml.org/wiki/LibYAML'.
 …
 under the MIT license.  See the file LICENSE for more details.
+This project is developed for Python Software Foundation as a part of
+Google Summer of Code under the mentorship of Clark Evans.
+The initial version of this project was developed for Python Software
+Foundation under the mentorshipf of Clark Evans as a part of Google Summer of
+Code 2006.

libyaml/trunk/include/Makefile.am

-                      r200
+                      r266
 INCLUDES = yaml.h
-DOXYGEN_CFG = $(top_srcdir)/doc/doxygen.cfg
 nobase_include_HEADERS = $(INCLUDES)
-if DOXYGEN
-html: $(INCLUDES) $(DOXYGEN_CFG)
-        PACKAGE=$(PACKAGE) VERSION=$(VERSION) top_srcdir=$(top_srcdir) top_builddir=$(top_builddir) doxygen $(DOXYGEN_CFG)
-endif
-distclean-local:
-        -rm -rf $(top_builddir)/doc/html
-dist-hook: html
-        cp -a $(top_builddir)/doc/html $(top_distdir)/doc

libyaml/trunk/include/yaml.h

-                      r265
+                      r266
+/**
+ * @file yaml.h
+ * @brief Public interface for libyaml.
+ *
+ * Include the header file with the code:
+ * @code
+ * #include <yaml.h>
+ * @endcode
+ */
+/*****************************************************************************
+ * Public Interface for LibYAML
+ *
+ * Copyright (c) 2006 Kirill Simonov
+ *
+ * LibYAML is free software; you can use, modify and/or redistribute it under
+ * the terms of the MIT license; see the file LICENCE for more details.
+ *****************************************************************************/
+/*
+ * General guidelines.
+ *
+ * Naming conventions: all functions exported by LibYAML starts with the `yaml_` prefix;
+ * types starts with `yaml_` and ends with `_t`; macros and enumerations starts
+ * with `YAML_`.
+ *
+ * FIXME: Calling conventions.
+ * FIXME: Memory allocation.
+ * FIXME: Errors and exceptions.
+ * FIXME: And so on, and so forth.
+ */
 #ifndef YAML_H
 …
 #include <string.h>
+/**
+ * @defgroup export Export Definitions
+ * @{
+ */
+/** The public API declaration. */
+/*****************************************************************************
+ * Export Definitions
+ *****************************************************************************/
+/*
+ * Public API declarations.
+ *
+ * The following definitions are relevant only for the Win32 platform.  If you
+ * are building LibYAML as a static library or linking your application against
+ * LibYAML compiled as a static library, define the macro
+ * `YAML_DECLARE_STATIC`.  If you are building LibYAML as a dynamic library
+ * (DLL), you need to define `YAML_DECLARE_EXPORT`.  You don't need to define
+ * any macros in case you are linking your application against LibYAML compiled
+ * as DLL.
+ *
+ * There is no need to define any macros if you use LibYAML on non-Win32
+ * platform.
+ */
 #ifdef WIN32
 …
 #endif
 /** @} */
+/**
+ * @defgroup version Version Information
+ * @{
  */
+/** The major version number. */
+/*****************************************************************************
+ * Version Information
+ *****************************************************************************/
+/*
+ * The major, minor and patch version numbers of LibYAML.
+ */
 #define YAML_VERSION_MAJOR  0
-/** The minor version number. */
 #define YAML_VERSION_MINOR  2
-/** The patch version number. */
 #define YAML_VERSION_PATCH  0
+/** The version string generator macro. */
+#define YAML_VERSION_STRING_GENERATOR(major,minor,patch)                        \
+    (#major "." #minor "." #patch)
+/** The version string. */
+#define YAML_VERSION_STRING                                                     \
+    YAML_VERSION_STRING_GENERATOR(YAML_VERSION_MAJOR,YAML_VERSION_MINOR,YAML_VERSION_PATCH)
+/**
+/*
+ * The version of LibYAML as a string.
+ */
+#define YAML_VERSION_STRING "0.2.0"
+/*
  * Get the library version numbers at runtime.
+ *
+ * @param[out]      major   Major version number.
+ * @param[out]      minor   Minor version number.
+ * @param[out]      patch   Patch version number.
+ * Arguments:
+ *
+ * - `major`: a pointer to store the major version number.
+ *
+ * - `minor`: a pointer to store the minor version number.
+ *
+ * - `patch`: a pointer to store the patch version number.
  */
 …
 yaml_get_version(int *major, int *minor, int *patch);
 /**
+/*
  * Get the library version as a string at runtime.
+ *
+ * @returns The function returns the pointer to a static string of the form
+ * @c "X.Y.Z", where @c X is the major version number, @c Y is the minor version
+ * number, and @c Z is the patch version number.
+ * Returns: the version of LibYAML as a static string.
  */
 …
 yaml_get_version_string(void);
+/** @} */
+/**
+ * @defgroup styles Error Handling
+ * @{
+ */
+/** Many bad things could happen with the parser and the emitter. */
+/*****************************************************************************
+ * Error Handling
+ *****************************************************************************/
+/*
+ * The type of the error.
+ *
+ * The YAML parser and emitter reports any error details using the
+ * `yaml_error_t` structure.  The error type shows what subsystem generated the
+ * error and what additional information about the error is available.
+ */
 typedef enum yaml_error_type_e {
     /** No error is produced. */
+    /* No error was produced. */
     YAML_NO_ERROR,
     /** Cannot allocate or reallocate a block of memory. */
+    /* Cannot allocate or reallocate a block of memory. */
     YAML_MEMORY_ERROR,
     /** Cannot read from the input stream. */
+    /* Cannot read from the input stream. */
     YAML_READER_ERROR,
     /** Cannot decode the input stream. */
+    /* Cannot decode a character in the input stream. */
     YAML_DECODER_ERROR,
     /** Cannot scan a YAML token. */
+    /* Cannot scan a YAML token. */
     YAML_SCANNER_ERROR,
     /** Cannot parse a YAML production. */
+    /* Cannot parse a YAML event. */
     YAML_PARSER_ERROR,
     /** Cannot compose a YAML document. */
+    /* Cannot compose a YAML document. */
     YAML_COMPOSER_ERROR,
     /** Cannot write into the output stream. */
+    /* Cannot write into the output stream. */
     YAML_WRITER_ERROR,
     /** Cannot emit a YAML event. */
+    /* Cannot emit a YAML event. */
     YAML_EMITTER_ERROR,
     /** Cannot serialize a YAML document. */
+    /* Cannot serialize a YAML document. */
     YAML_SERIALIZER_ERROR,
     /** Cannot resolve an implicit tag. */
+    /* Cannot resolve an implicit YAML node tag. */
     YAML_RESOLVER_ERROR
 } yaml_error_type_t;
+/** The pointer position. */
+/*
+ * Position in the input stream.
+ *
+ * Marks are used to indicate the position of YAML tokens, events and documents
+ * in the input stream as well as to point to the place where a parser error has
+ * occured.
+ */
 typedef struct yaml_mark_s {
     /** The character number (starting from zero). */
+    /* The number of the character in the input stream (starting from zero). */
     size_t index;
+    /** The mark line (starting from zero). */
+    /* The line in the input stream (starting from zero). */
     size_t line;
+    /** The mark column (starting from zero). */
+    /* The column in the input stream (starting from zero). */
     size_t column;
 } yaml_mark_t;
+/** The error details. */
+/*
+ * Error details.
+ *
+ * The structure gives detailed information on any problem that occured during
+ * parsing or emitting.
+ */
 typedef struct yaml_error_s {
     /** The error type. */
+    /* The error type. */
     yaml_error_type_t type;
     /** The detailed error information. */
+    /* The specific information for each error type. */
     union {
         /**
          * A problem while reading the stream (@c YAML_READER_ERROR or
          * @c YAML_DECODER_ERROR).
+        /*
+         * A problem occured while reading the input stream (relevant for
+         * `YAML_READER_ERROR` and `YAML_DECODER_ERROR`).
          */
         struct {
             /** The problem description. */
+            /* The problem description. */
             const char *problem;
             /** The stream offset. */
+            /* The position in the input stream, in bytes. */
             size_t offset;
             /** The problematic octet or character (@c -1 if not applicable). */
+            /* The problematic octet or character (`-1` if not applicable). */
             int value;
         } reading;
+        /**
+         * A problem while loading the stream (@c YAML_SCANNER_ERROR,
+         * @c YAML_PARSER_ERROR, or @c YAML_COMPOSER_ERROR).
+        /*
+         * A problem occured while loading YAML data from the input stream
+         * (relevant for `YAML_SCANNER_ERROR`, `YAML_PARSER_ERROR`, and
+         * `YAML_COMPOSER_ERROR`).
          */
         struct {
+            /** The context in which the problem occured
+             * (@c NULL if not applicable).
+             */
+            /* The description of the context in which the problem occured
+               (`NULL` if not applicable). */
             const char *context;
             /** The context mark (if @c problem_mark is not @c NULL). **/
+            /* The context mark (if `context` is not `NULL`). */
             yaml_mark_t context_mark;
             /** The problem description. */
+            /* The problem description. */
             const char *problem;
             /** The problem mark. */
+            /* The problem mark. */
             yaml_mark_t problem_mark;
         } loading;
+        /** A problem while writing into the stream (@c YAML_WRITER_ERROR). */
+        /*
+         * A problem occured while writing into the output stream (relevant for
+         * `YAML_WRITER_ERROR`).
+         */
         struct {
             /** The problem description. */
+            /* The problem description. */
             const char *problem;
             /** The stream offset. */
+            /* The position in the output stream, in bytes. */
             size_t offset;
         } writing;
+        /** A problem while dumping into the stream (@c YAML_EMITTER_ERROR and
+         * @c YAML_SERIALIZER_ERROR).
+        /*
+         * A problem while dumping YAML data into the output stream (relevant
+         * for `YAML_EMITTER_ERROR` and `YAML_SERIALIZER_ERROR`).
          */
         struct {
             /** The problem description. */
+            /* The problem description. */
             const char *problem;
         } dumping;
+        /** A problem while resolving an implicit tag (@c YAML_RESOLVER_ERROR). */
+        /*
+         * A problem occured while resolving an implicit YAML node tag
+         * (relevant for `YAML_RESOLVER_ERROR`).
+         */
         struct {
             /** The problem description. */
+            /* The problem description. */
             const char *problem;
         } resolving;
 …
 } yaml_error_t;
+/**
+ * Create an error message.
+ *
+ * @param[in]   error   An error object.
+ * @param[out]  buffer         model   A token to copy.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.  The function may
+ * fail if the buffer is not large enough to contain the whole message.
+/*
+ * Generate an error message.
+ *
+ * Given an instance of the `yaml_error_t` structure and a buffer, the function
+ * fills the buffer with a message describing the error.  The generated message
+ * follows the pattern: `"Error type: error details"`.  If the buffer is not
+ * large enough to hold the whole message, the function fails.
+ *
+ * Arguments:
+ *
+ * - `error`: an error object obtained using `yaml_parser_get_error()` or
+ *   `yaml_emitter_get_error()`.
+ *
+ * - `buffer`: a pointer to a character buffer to be filled with a generated
+ *   error message.
+ *
+ * - `capacity`: the size of the buffer.
+ *
+ * Returns: `1` if the function succeeded, `0` on error.  The function may fail
+ * if the provided buffer is not large enough to hold the whole buffer, in
+ * which case an application may increase the size of the buffer and call the
+ * function again.  If the function fails, the content of the buffer is
+ * undefined.
  */
 …
 yaml_error_message(yaml_error_t *error, char *buffer, size_t capacity);
+/** @} */
+/**
+ * @defgroup basic Basic Types
+ * @{
+ */
+/** The character type (UTF-8 octet). */
+/******************************************************************************
+ * Basic Types
+ ******************************************************************************/
+/*
+ * The character type (UTF-8 octet).
+ *
+ * Usage of the string type `(yaml_char_t *)` in the LibYAML API indicates that
+ * the string is encoded in UTF-8.
+ */
 typedef unsigned char yaml_char_t;
+/** The version directive data. */
+/*
+ * The version directive information.
+ *
+ * Note that LibYAML only supports YAML 1.1.
+ */
 typedef struct yaml_version_directive_s {
     /** The major version number. */
+    /* The major version number. */
     int major;
     /** The minor version number. */
+    /* The minor version number. */
     int minor;
 } yaml_version_directive_t;
+/** The tag directive data. */
+/*
+ * The tag directive information.
+ */
 typedef struct yaml_tag_directive_s {
     /** The tag handle. */
+    /* The tag handle. */
     yaml_char_t *handle;
     /** The tag prefix. */
+    /* The tag prefix. */
     yaml_char_t *prefix;
 } yaml_tag_directive_t;
+/** The stream encoding. */
+/*
+ * The stream encoding.
+ *
+ * An application may explicitly specify the encoding in the input stream or
+ * let the parser to detect the input stream encoding from a BOM mark.  If the
+ * stream does not start with a BOM mark, UTF-8 is assumed.
+ *
+ * An application may specify the encoding of the output stream or let the
+ * emitter to choose a suitable encoding, in which case, UTF-8 is used.
+ */
 typedef enum yaml_encoding_e {
     /** Let the parser choose the encoding. */
+    /* The default/autodetected encoding. */
     YAML_ANY_ENCODING,
     /** The default UTF-8 encoding. */
+    /* The UTF-8 encoding. */
     YAML_UTF8_ENCODING,
     /** The UTF-16-LE encoding with BOM. */
+    /* The UTF-16-LE encoding. */
     YAML_UTF16LE_ENCODING,
     /** The UTF-16-BE encoding with BOM. */
+    /* The UTF-16-BE encoding. */
     YAML_UTF16BE_ENCODING
 } yaml_encoding_t;
+/** Line break types. */
+/*
+ * Line break types.
+ *
+ * An application may specify the line break type the emitter should use or
+ * leave it to the emitter discretion.  In the latter case, LN (Unix style) is
+ * used.
+ */
 typedef enum yaml_break_e {
     /** Let the parser choose the break type. */
+    /* Let the parser choose the break type. */
     YAML_ANY_BREAK,
     /** Use CR for line breaks (Mac style). */
+    /* Use CR for line breaks (Mac style). */
     YAML_CR_BREAK,
     /** Use LN for line breaks (Unix style). */
+    /* Use LN for line breaks (Unix style). */
     YAML_LN_BREAK,
     /** Use CR LN for line breaks (DOS style). */
+    /* Use CR LN for line breaks (DOS style). */
     YAML_CRLN_BREAK
 } yaml_break_t;
+/** @} */
+/**
+ * @defgroup styles Node Styles
+ * @{
+ */
+/** Scalar styles. */
+/******************************************************************************
+ * Node Styles
+ ******************************************************************************/
+/*
+ * Scalar styles.
+ *
+ * There are two groups of scalar types in YAML: flow and block.  Flow scalars
+ * are divided into three styles: plain, single-quoted, and double-quoted;
+ * block scalars are divided into two styles: literal and folded.
+ *
+ * The parser reports the style in which a scalar node is represented, however
+ * it is a purely presentation details that must not be used in interpreting
+ * the node content.
+ *
+ * An application may suggest a preferred node style or leave it completely
+ * to the emitter discretion.  Note that the emitter may ignore any stylistic
+ * suggestions.
+ */
 typedef enum yaml_scalar_style_e {
     /** Let the emitter choose the style. */
+    /* Let the emitter choose the style. */
     YAML_ANY_SCALAR_STYLE,
     /** The plain scalar style. */
+    /* The plain flow scalar style. */
     YAML_PLAIN_SCALAR_STYLE,
     /** The single-quoted scalar style. */
+    /* The single-quoted flow scalar style. */
     YAML_SINGLE_QUOTED_SCALAR_STYLE,
     /** The double-quoted scalar style. */
+    /* The double-quoted flow scalar style. */
     YAML_DOUBLE_QUOTED_SCALAR_STYLE,
     /** The literal scalar style. */
+    /* The literal block scalar style. */
     YAML_LITERAL_SCALAR_STYLE,
     /** The folded scalar style. */
+    /* The folded block scalar style. */
     YAML_FOLDED_SCALAR_STYLE
 } yaml_scalar_style_t;
+/** Sequence styles. */
+/*
+ * Sequence styles.
+ *
+ * YAML supports two sequence styles: flow and block.
+ *
+ * The parser reports the style of a sequence node, but this information should
+ * not be used in interpreting the sequence content.
+ *
+ * An application may suggest a preferred sequence style or leave it completely
+ * to the emitter discretion.  Note that the emitter may ignore any stylistic
+ * hints.
+ */
 typedef enum yaml_sequence_style_e {
     /** Let the emitter choose the style. */
+    /* Let the emitter choose the style. */
     YAML_ANY_SEQUENCE_STYLE,
+    /** The block sequence style. */
+    /* The flow sequence style. */
+    YAML_FLOW_SEQUENCE_STYLE
+    /* The block sequence style. */
     YAML_BLOCK_SEQUENCE_STYLE,
-    /** The flow sequence style. */
-    YAML_FLOW_SEQUENCE_STYLE
 } yaml_sequence_style_t;
+/** Mapping styles. */
+/*
+ * Mapping styles.
+ *
+ * YAML supports two mapping styles: flow and block.
+ *
+ * The parser reports the style of a mapping node, but this information should
+ * not be used in interpreting the mapping content.
+ *
+ * An application may suggest a preferred mapping style or leave it completely
+ * to the emitter discretion.  Note that the emitter may ignore any stylistic
+ * hints.
+ */
 typedef enum yaml_mapping_style_e {
     /** Let the emitter choose the style. */
+    /* Let the emitter choose the style. */
     YAML_ANY_MAPPING_STYLE,
     /** The block mapping style. */
+    /* The block mapping style. */
     YAML_BLOCK_MAPPING_STYLE,
     /** The flow mapping style. */
+    /* The flow mapping style. */
     YAML_FLOW_MAPPING_STYLE
-/*    YAML_FLOW_SET_MAPPING_STYLE   */
 } yaml_mapping_style_t;
+/** @} */
+/**
+ * @defgroup tokens Tokens
+ * @{
+ */
+/** Token types. */
+/******************************************************************************
+ * Tokens
+ ******************************************************************************/
+/*
+ * Token types.
+ *
+ * The LibYAML scanner generates the following types of tokens:
+ *
+ * - STREAM-START: indicates the beginning of the stream.
+ *
+ * - STREAM-END: indicates the end of the stream.
+ *
+ * - VERSION-DIRECTIVE: describes the `%YAML` directive.
+ *
+ * - TAG-DIRECTIVE: describes the `%TAG` directive.
+ *
+ * - DOCUMENT-START: the indicator `---`.
+ *
+ * - DOCUMENT-END: the indicator `...`.
+ *
+ * - BLOCK-SEQUENCE-START: indentation increase indicating the beginning of a
+ *   block sequence node.
+ *
+ * - BLOCK-MAPPING-START: indentation increase indicating the beginning of a
+ *   block mapping node.
+ *
+ * - BLOCK-END: indentation decrease indicating the end of a block collection
+ *   node.
+ *
+ * - FLOW-SEQUENCE-START: the indicator `[`.
+ *
+ * - FLOW-SEQUENCE-END: the indicator `]`.
+ *
+ * - FLOW-MAPPING-START: the indicator `{`.
+ *
+ * - FLOW-MAPPING-END: the indicator `}`.
+ *
+ * - BLOCK-ENTRY: the beginning of an item of a block sequence.
+ *
+ * - FLOW-ENTRY: the beginning of an item of a flow sequence.
+ *
+ * - KEY: the beginning of a simple key, or the indicator `?`.
+ *
+ * - VALUE: the indicator `:`.
+ *
+ * - ALIAS: an alias of a node.
+ *
+ * - ANCHOR: a node anchor.
+ *
+ * - TAG: a node tag.
+ *
+ * - SCALAR: the content of a scalar node.
+ */
 typedef enum yaml_token_type_e {
     /** An empty token. */
+    /* An empty unitialized token. */
     YAML_NO_TOKEN,
     /** A STREAM-START token. */
+    /* A STREAM-START token. */
     YAML_STREAM_START_TOKEN,
     /** A STREAM-END token. */
+    /* A STREAM-END token. */
     YAML_STREAM_END_TOKEN,
     /** A VERSION-DIRECTIVE token. */
+    /* A VERSION-DIRECTIVE token. */
     YAML_VERSION_DIRECTIVE_TOKEN,
     /** A TAG-DIRECTIVE token. */
+    /* A TAG-DIRECTIVE token. */
     YAML_TAG_DIRECTIVE_TOKEN,
     /** A DOCUMENT-START token. */
+    /* A DOCUMENT-START token. */
     YAML_DOCUMENT_START_TOKEN,
     /** A DOCUMENT-END token. */
+    /* A DOCUMENT-END token. */
     YAML_DOCUMENT_END_TOKEN,
     /** A BLOCK-SEQUENCE-START token. */
+    /* A BLOCK-SEQUENCE-START token. */
     YAML_BLOCK_SEQUENCE_START_TOKEN,
     /** A BLOCK-SEQUENCE-END token. */
+    /* A BLOCK-SEQUENCE-END token. */
     YAML_BLOCK_MAPPING_START_TOKEN,
     /** A BLOCK-END token. */
+    /* A BLOCK-END token. */
     YAML_BLOCK_END_TOKEN,
     /** A FLOW-SEQUENCE-START token. */
+    /* A FLOW-SEQUENCE-START token. */
     YAML_FLOW_SEQUENCE_START_TOKEN,
     /** A FLOW-SEQUENCE-END token. */
+    /* A FLOW-SEQUENCE-END token. */
     YAML_FLOW_SEQUENCE_END_TOKEN,
     /** A FLOW-MAPPING-START token. */
+    /* A FLOW-MAPPING-START token. */
     YAML_FLOW_MAPPING_START_TOKEN,
     /** A FLOW-MAPPING-END token. */
+    /* A FLOW-MAPPING-END token. */
     YAML_FLOW_MAPPING_END_TOKEN,
     /** A BLOCK-ENTRY token. */
+    /* A BLOCK-ENTRY token. */
     YAML_BLOCK_ENTRY_TOKEN,
     /** A FLOW-ENTRY token. */
+    /* A FLOW-ENTRY token. */
     YAML_FLOW_ENTRY_TOKEN,
     /** A KEY token. */
+    /* A KEY token. */
     YAML_KEY_TOKEN,
     /** A VALUE token. */
+    /* A VALUE token. */
     YAML_VALUE_TOKEN,
     /** An ALIAS token. */
+    /* An ALIAS token. */
     YAML_ALIAS_TOKEN,
     /** An ANCHOR token. */
+    /* An ANCHOR token. */
     YAML_ANCHOR_TOKEN,
     /** A TAG token. */
+    /* A TAG token. */
     YAML_TAG_TOKEN,
     /** A SCALAR token. */
+    /* A SCALAR token. */
     YAML_SCALAR_TOKEN
 } yaml_token_type_t;
+/** The token structure. */
+/*
+ * The token object.
+ *
+ * Typically the token API is too low-level to be used directly by
+ * applications.  A possible user of the token API is a syntax highlighting
+ * application.
+ */
 typedef struct yaml_token_s {
     /** The token type. */
+    /* The token type. */
     yaml_token_type_t type;
     /** The token data. */
+    /* The token data. */
     union {
         /** The stream start (for @c YAML_STREAM_START_TOKEN). */
+        /* Extra data associated with a STREAM-START token. */
         struct {
             /** The stream encoding. */
+            /* The stream encoding. */
             yaml_encoding_t encoding;
         } stream_start;
         /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
+        /* Extra data associated with a VERSION-DIRECTIVE token. */
         struct {
             /** The major version number. */
+            /* The major version number. */
             int major;
             /** The minor version number. */
+            /* The minor version number. */
             int minor;
         } version_directive;
         /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
+        /* Extra data associated with a TAG-DIRECTIVE token. */
         struct {
             /** The tag handle. */
+            /* The tag handle. */
             yaml_char_t *handle;
             /** The tag prefix. */
+            /* The tag prefix. */
             yaml_char_t *prefix;
         } tag_directive;
         /** The alias (for @c YAML_ALIAS_TOKEN). */
+        /* Extra data associated with an ALIAS token. */
         struct {
             /** The alias value. */
+            /* The alias value. */
             yaml_char_t *value;
         } alias;
         /** The anchor (for @c YAML_ANCHOR_TOKEN). */
+        /* Extra data associated with an ANCHOR token. */
         struct {
             /** The anchor value. */
+            /* The anchor value. */
             yaml_char_t *value;
         } anchor;
         /** The tag (for @c YAML_TAG_TOKEN). */
+        /* Extra data associated with a TAG token. */
         struct {
             /** The tag handle. */
+            /* The tag handle. */
             yaml_char_t *handle;
             /** The tag suffix. */
+            /* The tag suffix. */
             yaml_char_t *suffix;
         } tag;
         /** The scalar value (for @c YAML_SCALAR_TOKEN). */
+        /* Extra data associated with a SCALAR token. */
         struct {
             /** The scalar value. */
+            /* The scalar value. */
             yaml_char_t *value;
             /** The length of the scalar value. */
+            /* The length of the scalar value. */
             size_t length;
             /** The scalar style. */
+            /* The scalar style. */
             yaml_scalar_style_t style;
         } scalar;
 …
     } data;
     /** The beginning of the token. */
+    /* The beginning of the token. */
     yaml_mark_t start_mark;
     /** The end of the token. */
+    /* The end of the token. */
     yaml_mark_t end_mark;
 } yaml_token_t;
 /**
+/*
  * Allocate a new empty token object.
+ *
+ * @returns a new token object or @c NULL on error.
+ * A token object allocated using this function must be deleted with
+ * `yaml_token_delete()`.
+ *
+ * Returns: a new empty token object or `NULL` on error.  The function may fail
+ * if it cannot allocate memory for a new token object.
  */
 …
 yaml_token_new(void);
+/**
+ * Delete and deallocate a token object.
+ *
+ * @param[in,out]   token   A token object.
+/*
+ * Deallocate a token object and free the associated data.
+ *
+ * A token object must be previously allocated with `yaml_token_new()`.
+ *
+ * Arguments:
+ *
+ * - `token`: a token object to be deallocated.
  */
 …
 yaml_token_delete(yaml_token_t *token);
 /**
+/*
  * Duplicate a token object.
+ *
+ * @param[in,out]   token   An empty token object.
+ * @param[in]       model   A token to copy.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * This function creates a deep copy of an existing token object.  It accepts
+ * two token objects: an empty token and a model token.  The latter is supposed
+ * to be initialized with `yaml_parser_parse_token()`.  The function assigns
+ * the type of the model to the empty token as well as duplicates and copies
+ * the internal state associated with the model token.
+ *
+ * Arguments:
+ *
+ * - `token`: an empty token object.
+ *
+ * - `model`: a token to be copied.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for duplicating the state of the model token.  In that case,
+ * the token remains empty.
  */
 …
 yaml_token_duplicate(yaml_token_t *token, const yaml_token_t *model);
+/**
+ * Free any memory allocated for a token object.
+ *
+ * @param[in,out]   token   A token object.
+/*
+ * Clear the token state.
+ *
+ * This function clears the type and the internal state of a token object
+ * freeing any associated data.  After applying this function to a token, it
+ * becomes empty.  It is supposed that the token was previously initialized
+ * using `yaml_parser_parse_token()` or `yaml_token_duplicate()`.
+ *
+ * Arguments:
+ *
+ * - `token`: a token object.
  */
 YAML_DECLARE(void)
+yaml_token_destroy(yaml_token_t *token);
+/** @} */
+/**
+ * @defgroup events Events
+ * @{
+ */
+/** Event types. */
+yaml_token_clear(yaml_token_t *token);
+/******************************************************************************
+ * Events
+ ******************************************************************************/
+/*
+ * Event types.
+ *
+ * The LibYAML parser generates, while the LibYAML emitter accepts, YAML events
+ * of the following types:
+ *
+ * - STREAM-START: indicates the beginning of the stream.
+ *
+ * - STREAM-END: indicates the end of the stream.
+ *
+ * - DOCUMENT-START: indicates the beginning of the document.
+ *
+ * - DOCUMENT-END: indicates the end of the document.
+ *
+ * - ALIAS: an alias to an already produced node.
+ *
+ * - SCALAR: a scalar node.
+ *
+ * - SEQUENCE-START: indicates the beginning of a sequence node.
+ *
+ * - SEQUENCE-END: indicates the end of a sequence node.
+ *
+ * - MAPPING-START: indicates the beginning of a mapping node.
+ *
+ * - MAPPING-END: indicates the end of a mapping node.
+ *
+ * A valid sequence of events obeys the grammar:
+ *
+ *      stream ::= STREAM-START document* STREAM-END
+ *      document ::= DOCUMENT-START node DOCUMENT-END
+ *      node ::= ALIAS | SCALAR | sequence | mapping
+ *      sequence ::= SEQUENCE-START node* SEQUENCE-END
+ *      mapping ::= MAPPING-START (node node)* MAPPING-END
+ */
 typedef enum yaml_event_type_e {
     /** An empty event. */
+    /* An empty unitialized event. */
     YAML_NO_EVENT,
     /** A STREAM-START event. */
+    /* A STREAM-START event. */
     YAML_STREAM_START_EVENT,
     /** A STREAM-END event. */
+    /* A STREAM-END event. */
     YAML_STREAM_END_EVENT,
     /** A DOCUMENT-START event. */
+    /* A DOCUMENT-START event. */
     YAML_DOCUMENT_START_EVENT,
     /** A DOCUMENT-END event. */
+    /* A DOCUMENT-END event. */
     YAML_DOCUMENT_END_EVENT,
     /** An ALIAS event. */
+    /* An ALIAS event. */
     YAML_ALIAS_EVENT,
     /** A SCALAR event. */
+    /* A SCALAR event. */
     YAML_SCALAR_EVENT,
     /** A SEQUENCE-START event. */
+    /* A SEQUENCE-START event. */
     YAML_SEQUENCE_START_EVENT,
     /** A SEQUENCE-END event. */
+    /* A SEQUENCE-END event. */
     YAML_SEQUENCE_END_EVENT,
     /** A MAPPING-START event. */
+    /* A MAPPING-START event. */
     YAML_MAPPING_START_EVENT,
     /** A MAPPING-END event. */
+    /* A MAPPING-END event. */
     YAML_MAPPING_END_EVENT
 } yaml_event_type_t;
+/** The event structure. */
+/*
+ * The event object.
+ *
+ * The event-level API of LibYAML should be used for streaming applications.
+ */
 typedef struct yaml_event_s {
     /** The event type. */
+    /* The event type. */
     yaml_event_type_t type;
     /** The event data. */
+    /* The event data. */
     union {
         /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
+        /* The stream parameters (for `YAML_STREAM_START_EVENT`). */
         struct {
             /** The document encoding. */
+            /* The document encoding. */
             yaml_encoding_t encoding;
         } stream_start;
         /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
+        /* The document parameters (for `YAML_DOCUMENT_START_EVENT`). */
         struct {
             /** The version directive. */
+            /* The version directive or `NULL` if not present. */
             yaml_version_directive_t *version_directive;
             /** The list of tag directives. */
+            /* The list of tag directives. */
             struct {
                 /** The beginning of the list. */
+                /* The beginning of the list or `NULL`. */
                 yaml_tag_directive_t *list;
                 /** The length of the list. */
+                /* The length of the list. */
                 size_t length;
                 /** The capacity of the list. */
+                /* The capacity of the list (used internally). */
                 size_t capacity;
             } tag_directives;
             /** Is the document indicator implicit? */
+            /* Set if the document indicator is omitted. */
             int is_implicit;
         } document_start;
         /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
+        /* The document end parameters (for `YAML_DOCUMENT_END_EVENT`). */
         struct {
             /** Is the document end indicator implicit? */
+            /* Set if the document end indicator is omitted. */
             int is_implicit;
         } document_end;
         /** The alias parameters (for @c YAML_ALIAS_EVENT). */
+        /* The alias parameters (for `YAML_ALIAS_EVENT`). */
         struct {
             /** The anchor. */
+            /* The anchor. */
             yaml_char_t *anchor;
         } alias;
         /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
+        /* The scalar parameters (for `YAML_SCALAR_EVENT`). */
         struct {
             /** The anchor. */
+            /* The node anchor or `NULL`. */
             yaml_char_t *anchor;
             /** The tag. */
+            /* The node tag or `NULL`. */
             yaml_char_t *tag;
             /** The scalar value. */
+            /* The scalar value. */
             yaml_char_t *value;
             /** The length of the scalar value. */
+            /* The length of the scalar value (in bytes). */
             size_t length;
             /** Is the tag optional for the plain style? */
             int is_plain_implicit;
             /** Is the tag optional for any non-plain style? */
             int is_quoted_implicit;
             /** The scalar style. */
+            /* Set if the tag is optional for the plain style. */
+            int is_plain_nonspecific;
+            /* Set if the tag is optional for any non-plain style. */
+            int is_quoted_nonspecific;
+            /* The scalar style. */
             yaml_scalar_style_t style;
         } scalar;
         /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
+        /* The sequence parameters (for `YAML_SEQUENCE_START_EVENT`). */
         struct {
             /** The anchor. */
+            /* The node anchor or `NULL`. */
             yaml_char_t *anchor;
             /** The tag. */
+            /* The node tag or `NULL`. */
             yaml_char_t *tag;
             /** Is the tag optional? */
             int is_implicit;
             /** The sequence style. */
+            /* Set if the tag is optional. */
+            int is_nonspecific;
+            /* The sequence style. */
             yaml_sequence_style_t style;
         } sequence_start;
         /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
+        /* The mapping parameters (for `YAML_MAPPING_START_EVENT`). */
         struct {
             /** The anchor. */
+            /* The node anchor or `NULL`. */
             yaml_char_t *anchor;
             /** The tag. */
+            /* The node tag or `NULL`. */
             yaml_char_t *tag;
             /** Is the tag optional? */
             int is_implicit;
             /** The mapping style. */
+            /* Set if the tag is optional. */
+            int is_nonspecific;
+            /* The mapping style. */
             yaml_mapping_style_t style;
         } mapping_start;
 …
     } data;
     /** The beginning of the event. */
+    /* The beginning of the event. */
     yaml_mark_t start_mark;
     /** The end of the event. */
+    /* The end of the event. */
     yaml_mark_t end_mark;
 } yaml_event_t;
 /**
+/*
  * Allocate a new empty event object.
+ *
+ * @returns a new event object or @c NULL on error.
+ * An event object allocated using this function must be deleted with
+ * `yaml_event_delete()`.
+ *
+ * Returns: a new empty event object or `NULL` on error.  The function may fail
+ * if it cannot allocate memory for a new event object.
  */
 …
 yaml_event_new(void);
+/**
+ * Delete and deallocate an event object.
+ *
+ * @param[in,out]   event   An event object.
+/*
+ * Deallocate an event object and free the associated data.
+ *
+ * An event object must be previously allocated with `yaml_event_new()`.
+ *
+ * Arguments:
+ *
+ * - `event`: an event object to be deallocated.
  */
 …
 yaml_event_delete(yaml_event_t *event);
+/**
+ * Duplicate a event object.
+ *
+ * @param[in,out]   event   An empty event object.
+ * @param[in]       model   An event to copy.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+/*
+ * Duplicate an event object.
+ *
+ * This function creates a deep copy of an existing event object.  It accepts
+ * two objects: an empty event and a model event.  The model event is supposed
+ * to be initialized either with `yaml_parser_parse_event()` or using one of
+ * the functions `yaml_event_create_*()`.  The function assigns the type of the
+ * model to the empty event and copies the internal state associated with the
+ * model event.
+ *
+ * Arguments:
+ *
+ * - `event`: an empty event object.
+ *
+ * - `model`: an event to be copied.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for duplicating the state of the model event.  In that case,
+ * the event remains empty.
  */
 …
 yaml_event_duplicate(yaml_event_t *event, const yaml_event_t *model);
+/**
+/*
+ * Clear the event state.
+ *
+ * This function clears the type and the internal state of an event object
+ * freeing any associated data.  After applying this function to an event, it
+ * becomes empty.  It is supposed that the event was previously initialized
+ * using `yaml_parser_parse_event()` or `yaml_event_duplicate()`.  Note that
+ * the function `yaml_emitter_emit_event()` also clears the given event.
+ *
+ * Arguments:
+ *
+ * - `event`: an event object.
+ */
+YAML_DECLARE(void)
+yaml_event_clear(yaml_event_t *event);
+/*
  * Create a STREAM-START event.
+ *
+ * This function never fails.
+ *
+ * @param[out]      event       An empty event object.
+ * @param[in]       encoding    The stream encoding.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * This function initializes an empty event object allocated with
+ * `yaml_event_new()`.  The initialized event could be fed to
+ * `yaml_emitter_emit_event()`.
+ *
+ * Arguments:
+ *
+ * - `event`: an empty event object.
+ *
+ * - `encoding`: the stream encoding.
+ *
+ * Returns: `1`.  The function never fails.
  */
 …
         yaml_encoding_t encoding);
 /**
+/*
  * Create a STREAM-END event.
+ *
+ * This function never fails.
+ *
+ * @param[out]      event       An empty event object.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * This function initializes an empty event object allocated with
+ * `yaml_event_new()`.  The initialized event could be fed to
+ * `yaml_emitter_emit_event()`.
+ *
+ * Arguments:
+ *
+ * - `event`: an empty event object.
+ *
+ * Returns: `1`.  The function never fails.
  */
 …
 yaml_event_create_stream_end(yaml_event_t *event);
+/**
+ * Create the DOCUMENT-START event.
+ *
+ * @param[out]      event                   An empty event object.
+ * @param[in]       version_directive       The %YAML directive value or
+ *                                          @c NULL.
+ * @param[in]       tag_directives_list     The beginning of the %TAG
+ *                                          directives list or @c NULL.  The
+ *                                          list ends with @c (NULL,NULL).
+ * @param[in]       is_implicit             Set if the document start
+ *                                          indicator is optional.  This
+ *                                          parameter is stylistic and may be
+ *                                          ignored by the parser.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+/*
+ * Create a DOCUMENT-START event.
+ *
+ * This function initializes an empty event object allocated with
+ * `yaml_event_new()`.  The initialized event could be fed to
+ * `yaml_emitter_emit_event()`.
+ *
+ * Arguments:
+ *
+ * - `event`: an empty event object.
+ *
+ * - `version_directive`: a structure specifying the content of the `%YAML`
+ *   directive or `NULL` if the directive could be omitted.  Note that LibYAML
+ *   supports YAML 1.1 only.  The function does not check if the supplied
+ *   version equals to 1.1, but the emitter will fail to emit the event if it
+ *   is not so.
+ *
+ * - `tag_directives_list`: a pointer to a list specifying the content of the
+ *   `%TAG` directives associated with the document or `NULL` if the document
+ *   does not contain `%TAG` directives.  The content of a tag directive is a
+ *   pair (handle, prefix) of non-empty NUL-terminated UTF-8 strings.  The tag
+ *   handle is one of `!`, `!!` or a sequence of alphanumeric characters, `_`
+ *   and `-` surrounded by `!`.  The tag prefix is a prefix of any valid tag,
+ *   that is, it is a non-empty prefix of either a global tag (a valid URI) or
+ *   a local tag (an arbitrary string starting with `!`).  The function does
+ *   not check if the given directive values satisfy these requirements, but
+ *   the emitter will fail to emit the event if they are not met.
+ *
+ * - `tag_directives_length`: the length of `tag_directives_list`; `0` if
+ *   `tag_directives_list` is `NULL`.
+ *
+ * - `is_implicit`: `1` if the document indicator `---` is omitted, `0`
+ *   otherwise.  Note that this attribute is only a stylistic hint and could be
+ *   ignored by the emitter.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for duplicating the event parameters.  In this case, the
+ * event remains empty.
  */
 …
 yaml_event_create_document_start(yaml_event_t *event,
         const yaml_version_directive_t *version_directive,
+        const yaml_tag_directive_t *tag_directives,
+        const yaml_tag_directive_t *tag_directives_list,
+        size_t tag_directives_length,
         int is_implicit);
+/**
+ * Create the DOCUMENT-END event.
+ *
+ * @param[out]      event       An empty event object.
+ * @param[in]       is_implicit Set if the document end indicator is optional.
+ *                              This parameter is stylistic and may be ignored
+ *                              by the parser.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+/*
+ * Create a DOCUMENT-END event.
+ *
+ * This function initializes an empty event object allocated with
+ * `yaml_event_new()`.  The initialized event could be fed to
+ * `yaml_emitter_emit_event()`.
+ *
+ * Arguments:
+ *
+ * - `event`: an empty event object.
+ *
+ * - `is_implicit`: `1` if the document end indicator `...` is omitted, `0`
+ *   otherwise.  Note that this attribute is only a stylistic hint and could be
+ *   ignored by the emitter.
+ *
+ * Returns: `1`.  The function never fails.
  */
 …
 yaml_event_create_document_end(yaml_event_t *event, int is_implicit);
+/**
+ * Create an ALIAS event.
+ *
+ * @param[out]      event       An empty event object.
+ * @param[in]       anchor      The anchor value.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+/*
+ * Create an ANCHOR event.
+ *
+ * This function initializes an empty event object allocated with
+ * `yaml_event_new()`.  The initialized event could be fed to
+ * `yaml_emitter_emit_event()`.
+ *
+ * Arguments:
+ *
+ * - `event`: an empty event object.
+ *
+ * - `anchor`: the anchor value.  The anchor should be a non-empty
+ *   NUL-terminated string containing only alphanumerical characters, `_`, and
+ *   `-`.  The function does not check if this requirement is satisfied, but if
+ *   it is not so, the emitter will fail to emit the generated event.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for duplicating `anchor`.  In this case, the event remains
+ * empty.
  */
 …
 yaml_event_create_alias(yaml_event_t *event, const yaml_char_t *anchor);
 /**
+/*
  * Create a SCALAR event.
+ *
+ * @param[out]      event                   An empty event object.
+ * @param[in]       anchor                  The scalar anchor or @c NULL.
+ * @param[in]       tag                     The scalar tag or @c NULL.  If
+ *                                          latter, one of the
+ *                                          @a is_plain_implicit and
+ *                                          @a is_quoted_implicit flags must
+ *                                          be set.
+ * @param[in]       value                   The scalar value.
+ * @param[in]       length                  The length of the scalar value.
+ * @param[in]       is_plain_implicit       Set if the tag may be omitted for
+ *                                          the plain style.
+ * @param[in]       is_quoted_implicit      Set if the tag may be omitted for
+ *                                          any non-plain style.
+ * @param[in]       style                   The scalar style.  This attribute
+ *                                          may be ignored by the emitter.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * This function initializes an empty event object allocated with
+ * `yaml_event_new()`.  The initialized event could be fed to
+ * `yaml_emitter_emit_event()`.
+ *
+ * Arguments:
+ *
+ * - `event`: an empty event object.
+ *
+ * - `anchor`: the anchor value or `NULL`.  The anchor should be a non-empty
+ *   NUL-terminated string containing only alphanumerical characters, `_`, and
+ *   `-`.
+ *
+ * - `tag`: the tag value or `NULL`.  The tag should be a non-empty UTF-8
+ *   NUL-terminated string.  The tag could be global (a valid URI) or local (an
+ *   arbitrary string starting with `!`).  If `NULL` is provided, at least one
+ *   of the flags `is_plain_nonspecific` and `is_quoted_nonspecific` must be
+ *   set.  The function does not check whether these requirements are
+ *   satisfied, but the emitter will fail to emit the event if it is not so.
+ *
+ * - `value`: the value of the scalar node.  The value should be a UTF-8
+ *   string.  It could contain any valid UTF-8 character including NUL.  The
+ *   function does not check if `value` is a valid UTF-8 string, but the
+ *   emitter will fail to emit the event if it is not so.
+ *
+ * - `length`: the length of the scalar value (in bytes) or `-1`.  If `length`
+ *   is set to `-1`, the `value` is assumed to be NUL-terminated.
+ *
+ * - `is_plain_nonspecific`: `1` if the node tag could be omitted while
+ *   emitting the node provided that the the plain style is used for
+ *   representing the node value; `0` otherwise.  That this flag is set assumes
+ *   that the tag could be correctly determined by the parser using the node
+ *   position and content.
+ *
+ * - `is_quoted_nonspecific`: `1` if the node tag could be omitted while
+ *   emitting the node provided that the node value is represented using any
+ *   non-plain style; `0` otherwise.  That this flag is set assumes that the
+ *   tag could be correctly determined by the parser using the node position
+ *   and content.
+ *
+ * - `style`: the node style.  Note that this attribute only serves as a hint
+ *   and may be ignored by the emitter.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for duplicating the given string buffers.  In this case, the
+ * event remains empty.
  */
 …
 yaml_event_create_scalar(yaml_event_t *event,
         const yaml_char_t *anchor, const yaml_char_t *tag,
         const yaml_char_t *value, size_t length,
         int is_plain_implicit, int is_quoted_implicit,
+        const yaml_char_t *value, int length,
+        int is_plain_nonspecific, int is_quoted_nonspecific,
         yaml_scalar_style_t style);
 /**
+/*
  * Create a SEQUENCE-START event.
+ *
+ * @param[out]      event       An empty event object.
+ * @param[in]       anchor      The sequence anchor or @c NULL.
+ * @param[in]       tag         The sequence tag or @c NULL.  If latter, the
+ *                              @a is_implicit flag must be set.
+ * @param[in]       is_implicit Set if the tag may be omitted.
+ * @param[in]       style       The sequence style.  This attribute may be
+ *                              ignored by the parser.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * This function initializes an empty event object allocated with
+ * `yaml_event_new()`.  The initialized event could be fed to
+ * `yaml_emitter_emit_event()`.
+ *
+ * Arguments:
+ *
+ * - `event`: an empty event object.
+ *
+ * - `anchor`: the anchor value or `NULL`.  The anchor should be a non-empty
+ *   NUL-terminated string containing only alphanumerical characters, `_`, and
+ *   `-`.  The function does not check if this requirement is satisfied, but if
+ *   it is not so, the emitter will fail to emit the generated event.
+ *
+ * - `tag`: the tag value or `NULL`.  The tag should be a non-empty UTF-8
+ *   NUL-terminated string.  The tag could be global (a valid URI) or local (an
+ *   arbitrary string starting with `!`).  If `NULL` is provided, the flag
+ *   `is_nonspecific` must be set.  The function does not check whether these
+ *   requirements are satisfied, but if it is not so, the emitter will fail to
+ *   emit the generated event.
+ *
+ * - `is_nonspecific`: `1` if the node tag could be omitted while
+ *   emitting the node; `0` otherwise.  This flag should only be set if the
+ *   node tag could be correctly determined by the parser using the node
+ *   position in the document graph.
+ *
+ * - `style`: the node style.  Note that this attribute only serves as a hint
+ *   and may be ignored by the emitter.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for duplicating the given string buffers.  In this case, the
+ * event remains empty.
  */
 …
 yaml_event_create_sequence_start(yaml_event_t *event,
         const yaml_char_t *anchor, const yaml_char_t *tag,
         int is_implicit, yaml_sequence_style_t style);
 /**
+        int is_nonspecific, yaml_sequence_style_t style);
+/*
  * Create a SEQUENCE-END event.
+ *
+ * @param[out]      event       An empty event object.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * This function initializes an empty event object allocated with
+ * `yaml_event_new()`.  The initialized event could be fed to
+ * `yaml_emitter_emit_event()`.
+ *
+ * Arguments:
+ *
+ * - `event`: an empty event object.
+ *
+ * Returns: `1`.  This function never fails.
  */
 …
 yaml_event_create_sequence_end(yaml_event_t *event);
 /**
+/*
  * Create a MAPPING-START event.
+ *
+ * @param[out]      event       An empty event object.
+ * @param[in]       anchor      The mapping anchor or @c NULL.
+ * @param[in]       tag         The mapping tag or @c NULL.  If latter, the
+ *                              @a is_implicit flag must be set.
+ * @param[in]       is_implicit Set if the tag may be omitted.
+ * @param[in]       style       The mapping style.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * This function initializes an empty event object allocated with
+ * `yaml_event_new()`.  The initialized event could be fed to
+ * `yaml_emitter_emit_event()`.
+ *
+ * Arguments:
+ *
+ * - `event`: an empty event object.
+ *
+ * - `anchor`: the anchor value or `NULL`.  The anchor should be a non-empty
+ *   NUL-terminated string containing only alphanumerical characters, `_`, and
+ *   `-`.  The function does not check if this requirement is satisfied, but if
+ *   it is not so, the emitter will fail to emit the generated event.
+ *
+ * - `tag`: the tag value or `NULL`.  The tag should be a non-empty UTF-8
+ *   NUL-terminated string.  The tag could be global (a valid URI) or local (an
+ *   arbitrary string starting with `!`).  If `NULL` is provided, the flag
+ *   `is_nonspecific` must be set.  The function does not check whether these
+ *   requirements are satisfied, but if it is not so, the emitter will fail to
+ *   emit the generated event.
+ *
+ * - `is_nonspecific`: `1` if the node tag could be omitted while
+ *   emitting the node; `0` otherwise.  This flag should only be set if the
+ *   node tag could be correctly determined by the parser using the node
+ *   position in the document graph.
+ *
+ * - `style`: the node style.  Note that this attribute only serves as a hint
+ *   and may be ignored by the emitter.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for duplicating the given string buffers.  In this case, the
+ * event remains empty.
  */
 …
 yaml_event_create_mapping_start(yaml_event_t *event,
         const yaml_char_t *anchor, const yaml_char_t *tag,
         int is_implicit, yaml_mapping_style_t style);
 /**
+        int is_nonspecific, yaml_mapping_style_t style);
+/*
  * Create a MAPPING-END event.
+ *
+ * @param[out]      event       An empty event object.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * This function initializes an empty event object allocated with
+ * `yaml_event_new()`.  The initialized event could be fed to
+ * `yaml_emitter_emit_event()`.
+ *
+ * Arguments:
+ *
+ * - `event`: an empty event object.
+ *
+ * Returns: `1`.  This function never fails.
  */
 …
 yaml_event_create_mapping_end(yaml_event_t *event);
+/**
+ * Free any memory allocated for an event object.
+ *
+ * @param[in,out]   event   An event object.
+ */
+YAML_DECLARE(void)
+yaml_event_destroy(yaml_event_t *event);
+/** @} */
+/**
+ * @defgroup nodes Nodes
+ * @{
+ */
+/** The tag @c !!null with the only possible value: @c null. */
+/******************************************************************************
+ * Documents and Nodes
+ ******************************************************************************/
+/*
+ * Well-known scalar tags.
+ */
 #define YAML_NULL_TAG       ((const yaml_char_t *) "tag:yaml.org,2002:null")
-/** The tag @c !!bool with the values: @c true and @c falce. */
 #define YAML_BOOL_TAG       ((const yaml_char_t *) "tag:yaml.org,2002:bool")
-/** The tag @c !!str for string values. */
 #define YAML_STR_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:str")
-/** The tag @c !!int for integer values. */
 #define YAML_INT_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:int")
-/** The tag @c !!float for float values. */
 #define YAML_FLOAT_TAG      ((const yaml_char_t *) "tag:yaml.org,2002:float")
+/** The tag @c !!seq is used to denote sequences. */
+/*
+ * Basic collection tags.
+ */
 #define YAML_SEQ_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:seq")
-/** The tag @c !!map is used to denote mapping. */
 #define YAML_MAP_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:map")
+/** The default scalar tag is @c !!str. */
+/*
+ * The default tags for nodes lacking an explicit tag.
+ */
 #define YAML_DEFAULT_SCALAR_TAG     YAML_STR_TAG
-/** The default sequence tag is @c !!seq. */
 #define YAML_DEFAULT_SEQUENCE_TAG   YAML_SEQ_TAG
-/** The default mapping tag is @c !!map. */
 #define YAML_DEFAULT_MAPPING_TAG    YAML_MAP_TAG
+/** Node types. */
+/*
+ * Document types.
+ *
+ * There are no different document types in LibYAML: the document type field is
+ * only used to distinguish between newly allocated documents and those that
+ * are initialized with `yaml_parser_parse_document()` or
+ * `yaml_document_create()`.
+ */
+typedef enum yaml_document_type_e {
+    /* An empty uninitialized document. */
+    YAML_NO_DOCUMENT.
+    /* A YAML document. */
+    YAML_DOCUMENT
+} yaml_document_type_t;
+/*
+ * Node types.
+ *
+ * YAML recognizes three kinds of nodes: scalar, sequence and mapping.
+ */
 typedef enum yaml_node_type_e {
     /** An empty node. */
+    /* An empty node. */
     YAML_NO_NODE,
     /** A scalar node. */
+    /* A scalar node. */
     YAML_SCALAR_NODE,
     /** A sequence node. */
+    /* A sequence node. */
     YAML_SEQUENCE_NODE,
     /** A mapping node. */
+    /* A mapping node. */
     YAML_MAPPING_NODE
 } yaml_node_type_t;
+/** Arc types. */
+/*
+ * Arc types.
+ *
+ * Arcs are used to specify the path from the root node to a given node in the
+ * document graph.  There are three kinds of arcs: an item in a sequence node,
+ * a key in a mapping node, and a value in a mapping node.
+ */
 typedef enum yaml_arc_type_e {
     /** An empty arc. */
+    /* An empty arc. */
     YAML_NO_ARC,
     /** An item of a sequence. */
+    /* An item of a sequence. */
     YAML_SEQUENCE_ITEM_ARC,
     /** A key of a mapping. */
+    /* A key of a mapping. */
     YAML_MAPPING_KEY_ARC,
     /** A value of a mapping. */
+    /* A value of a mapping. */
     YAML_MAPPING_VALUE_ARC
 } yaml_arc_type_t;
 /** The forward definition of a document node structure. */
+typedef struct yaml_node_s yaml_node_t;
+/** An element of a sequence node. */
+/*
+ * An element of a sequence node.
+ */
 typedef int yaml_node_item_t;
+/** An element of a mapping node. */
+/*
+ * An element of a mapping node.
+ */
 typedef struct yaml_node_pair_s {
     /** The key of the element. */
+    /* A key in a mapping. */
     int key;
     /** The value of the element. */
+    /* A value in a mapping. */
     int value;
 } yaml_node_pair_t;
+/** An element of a path in a YAML document. */
+/*
+ * A path element.
+ *
+ * An arc is an element of a path from the root node to some other node in a
+ * YAML document.  An arc consists of a collection node and information on how
+ * it is connected to the next node in the path.  If the arc type is a sequence
+ * item, then the collection node is a sequence and the arc refers to the index
+ * in this sequence.  If the arc type is a mapping key, then the collection
+ * node is a mapping.  If the arc type is a mapping value, then the collection
+ * node is a mapping and the arc refers to the key associated to the value.
+ */
 typedef struct yaml_arc_s {
+    /** The arc type. */
+    /* The arc type. */
     yaml_arc_type_t type;
+    /** The collection node. */
+    int node;
+    /** A pointer in the collection node. */
+    int item;
+    /* The tag of the collection node. */
+    yaml_char_t *tag;
+    /* The connection information. */
+    union {
+        /* The sequence item data (for `YAML_SEQUENCE_ITEM_ARC`). */
+        struct {
+            /* The index of the item in the sequence (starting from `0`). */
+            int index;
+        } item;
+        /* The mapping value data (for `YAML_MAPPING_VALUE_ARC`). */
+        struct {
+            /* The key associated with the value. */
+            struct {
+                /* The key node type. */
+                yaml_node_type_t type;
+                /* The key node tag. */
+                yaml_char_t *tag;
+                /* The key node details. */
+                union {
+                    /* The scalar data (for a scalar key). */
+                    struct {
+                        /* The scalar value. */
+                        yaml_char_t *value;
+                        /* The scalar length. */
+                        size_t length;
+                    } scalar;
+                } data;
+            } key;
+        } value;
+    } data;
 } yaml_arc_t;
+/** The node structure. */
+/*
+ * The node object.
+ *
+ * A node object represents a node in a YAML document graph.  Node objects are
+ * created using the family of functions `yaml_document_add_*()`.  Links
+ * between nodes are created using the functions `yaml_document_append_*()`. A
+ * node object is destroyed when the document containing it is destroyed.
+ */
 struct yaml_node_s {
     /** The node type. */
+    /* The node type. */
     yaml_node_type_t type;
     /** The node anchor. */
+    /* The node anchor or `NULL`. */
     yaml_char_t *anchor;
     /** The node tag. */
+    /* The node tag. */
     yaml_char_t *tag;
     /** The node data. */
+    /* The node data. */
     union {
         /** The scalar parameters (for @c YAML_SCALAR_NODE). */
+        /* The scalar parameters (for `YAML_SCALAR_NODE`). */
         struct {
             /** The scalar value. */
+            /* The scalar value. */
             yaml_char_t *value;
             /** The length of the scalar value. */
+            /* The length of the scalar value. */
             size_t length;
             /** The scalar style. */
+            /* The scalar style. */
             yaml_scalar_style_t style;
         } scalar;
         /** The sequence parameters (for @c YAML_SEQUENCE_NODE). */
+        /* The sequence parameters (for `YAML_SEQUENCE_NODE`). */
         struct {
             /** The list of sequence items. */
+            /* The list of sequence items. */
             struct {
                 /** The beginning of the list. */
+                /* The pointer to the beginning of the list. */
                 yaml_node_item_t *list;
                 /** The length of the list. */
+                /* The length of the list. */
                 size_t length;
                 /** The capacity of the list. */
+                /* The capacity of the list (used internally). */
                 size_t capacity;
             } items;
             /** The sequence style. */
+            /* The sequence style. */
             yaml_sequence_style_t style;
         } sequence;
         /** The mapping parameters (for @c YAML_MAPPING_NODE). */
+        /* The mapping parameters (for `YAML_MAPPING_NODE`). */
         struct {
             /** The list of mapping pairs (key, value). */
+            /* The list of mapping pairs (key, value). */
             struct {
                 /** The beginning of the list. */
+                /** The pointer to the beginning of the list. */
                 yaml_node_pair_t *list;
                 /** The length of the list. */
+                /* The length of the list. */
                 size_t length;
                 /** The capacity of the list. */
+                /* The capacity of the list (used internally). */
                 size_t capacity;
             } pairs;
             /** The mapping style. */
+            /* The mapping style. */
             yaml_mapping_style_t style;
         } mapping;
 …
     } data;
     /** The beginning of the node. */
+    /* The beginning of the node. */
     yaml_mark_t start_mark;
     /** The end of the node. */
+    /* The end of the node. */
     yaml_mark_t end_mark;
 };
+/** The incomplete node structure. */
+/*
+ * The incomplete node object.
+ *
+ * This structure provides the information about a node that a tag resolver
+ * could use to determine the specific node tag.  This information includes
+ * the path from the root node and the node content for scalar nodes.
+ */
 typedef struct yaml_incomplete_node_s {
     /** The node type. */
+    /* The node type. */
     yaml_node_type_t type;
     /** The path to the new node. */
+    /* The path to the new node. */
     struct {
         /** The beginning of the list. */
+        /* The pointer to the beginning of the list. */
         yaml_arc_t *list;
+        /* The length of the list. */
+        size_t length;
+        /* The capacity of the list (used internally). */
+        size_t capacity;
+    } path;
+    /* The node data. */
+    union {
+        /* The scalar parameters (for `YAML_SCALAR_NODE`). */
+        struct {
+            /* The scalar value. */
+            yaml_char_t *value;
+            /* The length of the scalar value. */
+            size_t length;
+            /* Set if the scalar is plain. */
+            int is_plain;
+        } scalar;
+    } data;
+    /* The position of the node. */
+    yaml_mark_t mark;
+} yaml_incomplete_node_t;
+/*
+ * The document object.
+ *
+ * A document object represents the main structure of the YAML object model:
+ * the document graph consisting of nodes of three kinds: scalars, sequences,
+ * and mappings with the selected root node.
+ *
+ * An empty document object is allocated using the function
+ * `yaml_document_new()`.  Then the function `yaml_parser_parse_document()`
+ * could be used to load a YAML document from the input stream.  Alternatively,
+ * a document could be created with `yaml_document_create()` and its content
+ * could be specified using the families of functions `yaml_document_add_*()`
+ * and `yaml_document_append_*()`.  A document with all associated nodes could
+ * be destroyed using the function `yaml_document_delete()`.
+ */
+typedef struct yaml_document_s {
+    /* The document type. */
+    yaml_document_type_t type;
+    /* The document nodes (for internal use only). */
+    struct {
+        /* The pointer to the beginning of the list. */
+        yaml_node_t *list;
+        /* The length of the list. */
+        size_t length;
+        /* The capacity of the list. */
+        size_t capacity;
+    } nodes;
+    /* The version directive or `NULL`. */
+    yaml_version_directive_t *version_directive;
+    /* The list of tag directives. */
+    struct {
+        /* The pointer to the beginning of the list or `NULL`. */
+        yaml_tag_directive_t *list;
         /** The length of the list. */
         size_t length;
+        /** The capacity of the list. */
+        size_t capacity;
+    } path;
+    /** The node data. */
+    union {
+        /** The scalar parameters (for @c YAML_SCALAR_NODE). */
+        struct {
+            /** The scalar value. */
+            yaml_char_t *value;
+            /** The length of the scalar value. */
+            size_t length;
+            /** Set if the scalar is plain. */
+            int is_plain;
+        } scalar;
+    } data;
+    /** The position of the node. */
+    yaml_mark_t mark;
+} yaml_incomplete_node_t;
+/** The document structure. */
+typedef struct yaml_document_s {
+    /** The document nodes. */
+    struct {
+        /** The beginning of the list. */
+        yaml_node_t *list;
+        /** The length of the list. */
+        size_t length;
+        /** The capacity of the list. */
+        size_t capacity;
+    } nodes;
+    /** The version directive. */
+    yaml_version_directive_t *version_directive;
+    /** The list of tag directives. */
+    struct {
+        /** The beginning of the tag directive list. */
+        yaml_tag_directive_t *list;
+        /** The length of the tag directive list. */
+        size_t length;
+        /** The capacity of the tag directive list. */
+        /** The capacity of the list (used internally). */
         size_t capacity;
     } tag_directives;
     /** Is the document start indicator implicit? */
+    /** Set if the document start indicator is implicit. */
     int is_start_implicit;
     /** Is the document end indicator implicit? */
+    /** Set if the document end indicator is implicit. */
     int is_end_implicit;
 …
 } yaml_document_t;
+#if 0
+/**
+/*
  * Allocate a new empty document object.
+ *
+ * @returns a new document object or @c NULL on error.
+ * A document object allocated using this function must be deleted with
+ * `yaml_document_delete()`.
+ *
+ * Returns: a new empty document object or `NULL` on error.  The function may
+ * fail if it cannot allocate memory for a new object.
  */
 …
 yaml_document_new(void);
+/**
+ * Delete and deallocatge a document object.
+ *
+ * @param[in,out]   document    A document object.
+/*
+ * Deallocate a document object and free the associated data.
+ *
+ * A document object must be previously allocated with `yaml_document_new()`.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object to be deallocated.
  */
 …
 yaml_document_delete(yaml_document_t *document);
 /**
+/*
  * Duplicate a document object.
+ *
+ * @param[in,out]   document   An empty document object.
+ * @param[in]       model       A document to copy.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * This function creates a complete copy of an existing document and all the
+ * nodes it contains.  The function accepts two objects: an empty document and
+ * a model document.  The model is supposed to be initialized either with
+ * `yaml_parser_parse_document()` or constructed manually.  The functions
+ * duplicate the content of the document and its nodes and assigns it to the
+ * empty document.
+ *
+ * Arguments:
+ *
+ * - `document`: an empty document object.
+ *
+ * - `model`: a document to be copied.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for duplicating the state of the model.  In that case, the
+ * document remains empty.
  */
 …
 yaml_document_duplicate(yaml_document_t *document, yaml_document_t *model);
+/**
+/*
+ * Clear the document.
+ *
+ * This function clears the type of the document and destroys all the document
+ * nodes.  After applying this function to a document, it becomes empty.  It is
+ * supposed that the document was previously initialized using
+ * `yaml_parser_parse_document()` or created manually.  Note that the function
+ * `yaml_emitter_emit_document()` also clears the given document.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ */
+YAML_DECLARE(void)
+yaml_document_clear(yaml_document_t *document);
+/*
  * Create a YAML document.
+ *
+ * @param[out]      document                An empty document object.
+ * @param[in]       version_directive       The %YAML directive value or
+ *                                          @c NULL.
+ * @param[in]       tag_directives          The list of the %TAG directives or
+ *                                          @c NULL.  The list must end with
+ *                                          the pair @c (NULL,NULL).
+ * @param[in]       is_start_implicit       If the document start indicator is
+ *                                          implicit.
+ * @param[in]       is_end_implicit         If the document end indicator is
+ *                                          implicit.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * This function initializes an empty document object allocated with
+ * `yaml_document_new()`.  Further, nodes could be added to the document using
+ * the functions `yaml_document_add_*()` and `yaml_document_append_*()`.  The
+ * initialized document could be fed to `yaml_emitter_emit_document()`.
+ *
+ * Arguments:
+ *
+ * - `document`: an empty document object.
+ *
+ * - `version_directive`: a structure specifying the content of the `%YAML`
+ *   directive or `NULL` if the directive could be omitted.  Note that LibYAML
+ *   supports YAML 1.1 only.  The constructor does not check if the supplied
+ *   version equals to 1.1, but the emitter will fail to emit the document if
+ *   it is not so.
+ *
+ * - `tag_directives_list`: a pointer to a list specifying the content of the
+ *   `%TAG` directives associated with the document or `NULL` if the document
+ *   does not contain `%TAG` directives.  The content of a tag directive is a
+ *   pair (handle, prefix) of non-empty NUL-terminated UTF-8 strings.  The tag
+ *   handle is one of `!`, `!!` or a sequence of alphanumeric characters, `_`
+ *   and `-` surrounded by `!`.  The tag prefix is a prefix of any valid tag,
+ *   that is, it is a non-empty prefix of either a global tag (a valid URI) or
+ *   a local tag (an arbitrary string starting with `!`).  The constructor does
+ *   not check if the given directive values satisfy these requirements, but
+ *   the emitter will fail to emit the document if they are not met.
+ *
+ * - `tag_directives_length`: the length of `tag_directives_list`; `0` if
+ *   `tag_directives_list` is `NULL`.
+ *
+ * - `is_start_implicit`: `1` if the document start indicator `---` is omitted;
+ *   `0` otherwise.  Note that this attribute is only a stylistic hint and
+ *   could be ignored by the emitter.
+ *
+ * - `is_end_implicit`: `1` if the document end indicator `...` is omitted; `0`
+ *   otherwise.  Note that this attribute is only a stylistic hint and could be
+ *   ignored by the emitter.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for duplicating the document parameters.  In this case, the
+ * document remains empty.
  */
 YAML_DECLARE(int)
 yaml_document_create(yaml_document_t *document,
+        yaml_version_directive_t *version_directive,
+        yaml_tag_directive_t *tag_directives,
+        const yaml_version_directive_t *version_directive,
+        const yaml_tag_directive_t *tag_directives_list,
+        size_t tag_directives_length,
         int is_start_implicit, int is_end_implicit);
-/**
- * Delete a YAML document and all its nodes.
+ *
- * @param[in,out]   document        A document object.
- */
-YAML_DECLARE(void)
-yaml_document_destroy(yaml_document_t *document);
 /**
  * Get a node of a YAML document.
+ *
+ * The root node of the document has the id `0`.
+ *
  * The pointer returned by this function is valid until any of the functions
+ * modifying the documents is called.
+ *
+ * @param[in]       document        A document object.
+ * @param[in]       index           The node id.
+ *
+ * @returns the node objct or @c NULL if @c node_id is out of range.
+ * modifying the document is called.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: the node id.  The node id starts from `0` and increases by `1`
+ *   for each newly added node.  Specifying a negative `node_id` is possible,
+ *   which is interpeted as the number (<total number of nodes> - `node_id`).
+ *
+ * Returns: a pointer to the node object or `NULL` if `node_id` is out of
+ * range.
  */
 YAML_DECLARE(yaml_node_t *)
+yaml_document_get_node(yaml_document_t *document, int index);
+/**
+ * Get the root of a YAML document node.
+ *
+ * The root object is the first object added to the document.
+ *
+ * The pointer returned by this function is valid until any of the functions
+ * modifying the documents is called.
+ *
+ * An empty document produced by the parser signifies the end of a YAML
+ * stream.
+ *
+ * @param[in]       document        A document object.
+ *
+ * @returns the node object or @c NULL if the document is empty.
+ */
+YAML_DECLARE(yaml_node_t *)
+yaml_document_get_root_node(yaml_document_t *document);
+/**
+yaml_document_get_node(yaml_document_t *document, int node_id);
+/*
  * Create a SCALAR node and attach it to the document.
+ *
+ * The @a style argument may be ignored by the emitter.
+ *
+ * @param[in,out]   document        A document object.
+ * @param[in]       anchor          A preferred anchor for the node or @c NULL.
+ * @param[in]       tag             The scalar tag.
+ * @param[in]       value           The scalar value.
+ * @param[in]       length          The length of the scalar value.
+ * @param[in]       style           The scalar style.
+ *
+ * @returns the node id or @c 0 on error.
+ */
+YAML_DECLARE(int)
+yaml_document_add_scalar(yaml_document_t *document,
+        yaml_char_t *anchor, yaml_char_t *tag, yaml_char_t *value,
+        size_t length, yaml_scalar_style_t style);
+/**
+ * Note that the first node attached to a document becomes the root node.
+ * There must exist a path from the root node to any node added to the
+ * document, otherwise the function `yaml_emitter_emit_document()` will fail.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: a pointer to save the id of the generated node or `NULL`.
+ *
+ * - `anchor`: the node anchor or `NULL`.  The anchor should be a non-empty
+ *   NUL-terminated string containing only alphanumerical characters, `_`, and
+ *   `-`.  The function does not check whether this requirement is satisfied,
+ *   but the emitter may fail to emit the node if it is not so.  This parameter
+ *   is considered as a stylistic hint and could be ignored by the emitter.
+ *   The emitter may automatically generate an anchor for a node that does not
+ *   specify it or specifies a duplicate anchor.
+ *
+ * - `tag`: the node tag.  The tag should be a non-empty UTF-8 NUL-terminated
+ *   string.  The tag could be global (a valid URI) or local (an arbitrary
+ *   string starting with `!`).  The function does not check whether these
+ *   requirements are satisfied, but the emitter will fail to emit the node if
+ *   it is not so.
+ *
+ * - `value`: the scalar value.  The value should be a string containing any
+ *   valid UTF-8 character including NUL.  The function does not check if
+ *   `value` is a valid UTF-8 string, but the emitter will fail to emit the
+ *   node if it is not so.
+ *
+ * - `length`: the length of the scalar value (in bytes) or `-1`.  If `length`
+ *   is set to `-1`, the `value` is assumed to be NUL-terminated.
+ *
+ * - `style`: the node style.  Note that this attribute only serves as a hint
+ *   and may be ignored by the emitter.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for duplicating the given string buffers.  If the function
+ * succeeds, the id of the added node is returned via the pointer `node_id`
+ * if it is not set to `NULL`.
+ */
+YAML_DECLARE(int)
+yaml_document_add_scalar(yaml_document_t *document, int *node_id,
+        const yaml_char_t *anchor, const yaml_char_t *tag,
+        const yaml_char_t *value, int length,
+        yaml_scalar_style_t style);
+/*
  * Create a SEQUENCE node and attach it to the document.
+ *
+ * The @a style argument may be ignored by the emitter.
+ *
+ * @param[in,out]   document    A document object.
+ * @param[in]       anchor      A preferred anchor for the node or @c NULL.
+ * @param[in]       tag         The sequence tag.
+ * @param[in]       style       The sequence style.
+ *
+ * @returns the node id or @c 0 on error.
+ */
+YAML_DECLARE(int)
+yaml_document_add_sequence(yaml_document_t *document,
+        yaml_char_t *anchor, yaml_char_t *tag, yaml_sequence_style_t style);
+/**
+ * Note that the first node attached to a document becomes the root node.
+ * There must exist a path from the root node to any node added to the
+ * document, otherwise the function `yaml_emitter_emit_document()` will fail.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: a pointer to save the id of the generated node or `NULL`.
+ *
+ * - `anchor`: the node anchor or `NULL`.  The anchor should be a non-empty
+ *   NUL-terminated string containing only alphanumerical characters, `_`, and
+ *   `-`.  The function does not check whether this requirement is satisfied,
+ *   but the emitter may fail to emit the node if it is not so.  This parameter
+ *   is considered as a stylistic hint and could be ignored by the emitter.
+ *   The emitter may automatically generate an anchor for a node that does not
+ *   specify it or specifies a duplicate anchor.
+ *
+ * - `tag`: the node tag.  The tag should be a non-empty UTF-8 NUL-terminated
+ *   string.  The tag could be global (a valid URI) or local (an arbitrary
+ *   string starting with `!`).  The function does not check whether these
+ *   requirements are satisfied, but the emitter will fail to emit the node if
+ *   it is not so.
+ *
+ * - `style`: the node style.  Note that this attribute only serves as a hint
+ *   and may be ignored by the emitter.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for duplicating the given string buffers.  If the function
+ * succeeds, the id of the added node is returned via the pointer `node_id`
+ * if it is not set to `NULL`.
+ */
+YAML_DECLARE(int)
+yaml_document_add_sequence(yaml_document_t *document, int *node_id,
+        const yaml_char_t *anchor, const yaml_char_t *tag,
+        yaml_sequence_style_t style);
+/*
  * Create a MAPPING node and attach it to the document.
+ *
+ * The @a style argument may be ignored by the emitter.
+ *
+ * @param[in,out]   document    A document object.
+ * @param[in]       anchor      A preferred anchor for the node or @c NULL.
+ * @param[in]       tag         The sequence tag.
+ * @param[in]       style       The sequence style.
+ *
+ * @returns the node id or @c 0 on error.
+ */
+YAML_DECLARE(int)
+yaml_document_add_mapping(yaml_document_t *document,
+        yaml_char_t *anchor, yaml_char_t *tag, yaml_mapping_style_t style);
+/**
+ * Note that the first node attached to a document becomes the root node.
+ * There must exist a path from the root node to any node added to the
+ * document, otherwise the function `yaml_emitter_emit_document()` will fail.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: a pointer to save the id of the generated node or `NULL`.
+ *
+ * - `anchor`: the node anchor or `NULL`.  The anchor should be a non-empty
+ *   NUL-terminated string containing only alphanumerical characters, `_`, and
+ *   `-`.  The function does not check whether this requirement is satisfied,
+ *   but the emitter may fail to emit the node if it is not so.  This parameter
+ *   is considered as a stylistic hint and could be ignored by the emitter.
+ *   The emitter may automatically generate an anchor for a node that does not
+ *   specify it or specifies a duplicate anchor.
+ *
+ * - `tag`: the node tag.  The tag should be a non-empty UTF-8 NUL-terminated
+ *   string.  The tag could be global (a valid URI) or local (an arbitrary
+ *   string starting with `!`).  The function does not check whether these
+ *   requirements are satisfied, but the emitter will fail to emit the node if
+ *   it is not so.
+ *
+ * - `style`: the node style.  Note that this attribute only serves as a hint
+ *   and may be ignored by the emitter.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for duplicating the given string buffers.  If the function
+ * succeeds, the id of the added node is returned via the pointer `node_id`
+ * if it is not set to `NULL`.
+ */
+YAML_DECLARE(int)
+yaml_document_add_mapping(yaml_document_t *document, int *node_id,
+        const yaml_char_t *anchor, const yaml_char_t *tag,
+        yaml_mapping_style_t style);
+/*
+ * Get the value of a `!!null` SCALAR node.
+ *
+ * Use this function to ensure that the given node is a scalar, the node tag is
+ * equal to `tag:yaml.org,2002:null` and the node value is a valid null value.
+ * Given that the `!!null` tag admits only one valid value, the value is not
+ * returned.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: the node id; could be negative.
+ *
+ * Returns: `1` if the node is a valid `!!null` scalar, `0` otherwise.
+ */
+YAML_DECLARE(int)
+yaml_document_get_null_node(yaml_document_t *document, int node_id);
+/*
+ * Get the value of a `!!bool` SCALAR node.
+ *
+ * Use this function to ensure that the given node is a scalar, the node tag is
+ * `tag:yaml.org,2002:bool` and the node value is a valid boolean value.  The
+ * function returns the true value as `1` and the false value as `0`.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: the node id; could be negative.
+ *
+ * - `value`: a pointer to save the node value or `NULL`.
+ *
+ * Returns: `1` if the node is a valid `!!bool` scalar, `0` otherwise.  If the
+ * function succeeds and `value` is not `NULL`, the node value is saved to
+ * `value`.
+ */
+YAML_DECLARE(int)
+yaml_document_get_bool_node(yaml_document_t *document, int node_id,
+        int *value);
+/*
+ * Get the value of a `!!str` SCALAR node.
+ *
+ * Use this function to ensure that the given node is a scalar, the node tag is
+ * `tag:yaml.org,2002:str` and the node value is a string that does not contain
+ * the NUL character.  In this case, the function returns the node value.  The
+ * produced value is valid until the document object is cleared or deleted.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: the node id; could be negative.
+ *
+ * - `value`: a pointer to save the node value or `NULL`.
+ *
+ * Returns: `1` if the node is a valid `!!str` scalar, `0` otherwise.  If the
+ * function succeeds and `value` is not `NULL`, the node value is saved to
+ * `value`.
+ */
+YAML_DECLARE(int)
+yaml_document_get_str_node(yaml_document_t *document, int node_id,
+        char **value);
+/*
+ * Get the value of an `!!int` SCALAR node.
+ *
+ * Use this function to ensure that the given node is a scalar, the node tag is
+ * `tag:yaml.org,2002:int` and the node value is a valid integer.  In this
+ * case, the function parses the node value and returns an integer number.  The
+ * function recognizes decimal, hexdecimal and octal numbers including negative
+ * numbers.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: the node id; could be negative.
+ *
+ * - `value`: a pointer to save the node value or `NULL`.
+ *
+ * Returns: `1` if the node is a valid `!!int` scalar, `0` otherwise.  If the
+ * function succeeds and `value` is not `NULL`, the node value is saved to
+ * `value`.
+ */
+YAML_DECLARE(int)
+yaml_document_get_int_node(yaml_document_t *document, int node_id,
+        int *value);
+/*
+ * Get the value of a `!!float` SCALAR node.
+ *
+ * Use this function to ensure that the given node is a scalar, the node tag is
+ * `tag:yaml.org,2002:float` and the node value is a valid float value.  In
+ * this case, the function parses the node value and returns a float number.
+ * The function recognizes float values in exponential and fixed notation as
+ * well as special values `.nan`, `.inf` and `-.inf`.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: the node id; could be negative.
+ *
+ * - `value`: a pointer to save the node value or `NULL`.
+ *
+ * Returns: `1` if the node is a valid `!!float` scalar, `0` otherwise.  If the
+ * function succeeds and `value` is not `NULL`, the node value is saved to
+ * `value`.
+ */
+YAML_DECLARE(int)
+yaml_document_get_float_node(yaml_document_t *document, int node_id,
+        double *value);
+/*
+ * Get the value of a `!!seq` SEQUENCE node.
+ *
+ * Use this function to ensure that the given node is a sequence and the node
+ * tag is `tag:yaml.org,2002:seq`.  In this case, the function returns the list
+ * of nodes that belong to the sequence.  The produced list is valid until the
+ * document object is modified.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: the node id; could be negative.
+ *
+ * - `items`: a pointer to save the list of sequence items or `NULL`.
+ *
+ * - `length`: a pointer to save the length of the sequence or `NULL`.
+ *   `length` must be equal to `NULL` if and only if `items` is also `NULL`.
+ *
+ * Returns: `1` if the node is a valid `!!seq` sequence, `0` otherwise.  If the
+ * function succeeds and `items` is not `NULL`, the list of sequence items is
+ * saved to `items` and the sequence length is saved to `length`.
+ */
+YAML_DECLARE(int)
+yaml_document_get_seq_node(yaml_document_t *document, int node_id,
+        yaml_node_item_t **items, size_t *length);
+/*
+ * Get the value of a `!!map` MAPPING node.
+ *
+ * Use this function to ensure that the given node is a mapping and the node
+ * tag is `tag:yaml.org,2002:map`.  In this case, the function returns the list
+ * of node pairs (key, value) that belong to the sequence.  The produced list
+ * is valid until the document is modified.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: the node id; could be negative.
+ *
+ * - `pairs`: a pointer to save the list of mapping pairs or `NULL`.
+ *
+ * - `length`: a pointer to save the length of the mapping or `NULL`.
+ *   `length` must be equal to `NULL` if and only if `pairs` is also `NULL`.
+ *
+ * Returns: `1` if the node is a valid `!!map` mapping, `0` otherwise.  If the
+ * function succeeds and `pairs` is not `NULL`, the list of mapping pairs is
+ * saved to `pairs` and the mapping length is saved to `length`.
+ */
+YAML_DECLARE(int)
+yaml_document_get_map_node(yaml_document_t *document, int node_id,
+        yaml_node_pair_t **pairs, size_t *length);
+/*
+ * Add a `!!null` SCALAR node to the document.
+ *
+ * This function is a shorthand for the call:
+ *
+ *      yaml_document_add_scalar(document, node_id, NULL,
+ *              YAML_NULL_TAG, "null", -1, YAML_ANY_SCALAR_STYLE)
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: a pointer to save the id of the generated node or `NULL`.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for new buffers.  If the function succeeds, the id of the
+ * added node is returned via the pointer `node_id` if it is not set to `NULL`.
+ */
+YAML_DECLARE(int)
+yaml_document_add_null_node(yaml_document_t *document, int *node_id);
+/*
+ * Add a `!!bool` SCALAR node to the document.
+ *
+ * This function is a shorthand for the call:
+ *
+ *      yaml_document_add_scalar(document, node_id, NULL,
+ *              YAML_BOOL_TAG, (value ? "true" : "false"), -1,
+ *              YAML_ANY_SCALAR_STYLE)
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: a pointer to save the id of the generated node or `NULL`.
+ *
+ * - `value`: a boolean value; any non-zero value is true, `0` is false.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for new buffers.  If the function succeeds, the id of the
+ * added node is returned via the pointer `node_id` if it is not set to `NULL`.
+ */
+YAML_DECLARE(int)
+yaml_document_add_bool_node(yaml_document_t *document, int *node_id,
+        int value);
+/*
+ * Add a `!!str` SCALAR node to the document.
+ *
+ * This function is a shorthand for the call:
+ *
+ *      yaml_document_add_scalar(document, node_id, NULL,
+ *              YAML_STR_TAG, (const yaml_char_t *) value, -1,
+ *              YAML_ANY_SCALAR_STYLE)
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: a pointer to save the id of the generated node or `NULL`.
+ *
+ * - `value`: a NUL-terminated UTF-8 string.  The function does not check if
+ *   `value` is a valid UTF-8 string, but if it is not so, the emitter will
+ *   fail to emit the node.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for new buffers.  If the function succeeds, the id of the
+ * added node is returned via the pointer `node_id` if it is not set to `NULL`.
+ */
+YAML_DECLARE(int)
+yaml_document_add_str_node(yaml_document_t *document, int *node_id,
+        const char *value);
+/*
+ * Add an `!!int` SCALAR node to the document.
+ *
+ * This function is a shorthand for the call:
+ *
+ *      yaml_document_add_scalar(document, node_id, NULL,
+ *              YAML_INT_TAG, <string representation of the value>, -1,
+ *              YAML_ANY_SCALAR_STYLE)
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: a pointer to save the id of the generated node or `NULL`.
+ *
+ * - `value`: an integer value.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for new buffers.  If the function succeeds, the id of the
+ * added node is returned via the pointer `node_id` if it is not set to `NULL`.
+ */
+YAML_DECLARE(int)
+yaml_document_add_int_node(yaml_document_t *document, int *node_id,
+        int value);
+/*
+ * Add a `!!float` SCALAR node to the document.
+ *
+ * This function is a shorthand for the call:
+ *
+ *      yaml_document_add_scalar(document, node_id, NULL,
+ *              YAML_FLOAT_TAG, <string representation of the value>, -1,
+ *              YAML_ANY_SCALAR_STYLE)
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: a pointer to save the id of the generated node or `NULL`.
+ *
+ * - `value`: a float value.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for new buffers.  If the function succeeds, the id of the
+ * added node is returned via the pointer `node_id` if it is not set to `NULL`.
+ */
+YAML_DECLARE(int)
+yaml_document_add_float_node(yaml_document_t *document, int *node_id,
+        double value);
+/*
+ * Add a `!!seq` SEQUENCE node to the document.
+ *
+ * This function is a shorthand for the call:
+ *
+ *      yaml_document_add_sequence(document, node_id, NULL,
+ *              YAML_SEQ_TAG, YAML_ANY_SEQUENCE_STYLE)
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: a pointer to save the id of the generated node or `NULL`.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for new buffers.  If the function succeeds, the id of the
+ * added node is returned via the pointer `node_id` if it is not set to `NULL`.
+ */
+YAML_DECLARE(int)
+yaml_document_add_seq_node(yaml_document_t *document, int *node_id);
+/*
+ * Add a `!!map` MAPPING node to the document.
+ *
+ * This function is a shorthand for the call:
+ *
+ *      yaml_document_add_mapping(document, node_id, NULL,
+ *              YAML_MAP_TAG, YAML_ANY_MAPPING_STYLE)
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `node_id`: a pointer to save the id of the generated node or `NULL`.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for new buffers.  If the function succeeds, the id of the
+ * added node is returned via the pointer `node_id` if it is not set to `NULL`.
+ */
+YAML_DECLARE(int)
+yaml_document_add_map_node(yaml_document_t *document, int *node_id);
+/*
  * Add an item to a SEQUENCE node.
+ *
+ * @param[in,out]   document    A document object.
+ * @param[in]       sequence    The sequence node id.
+ * @param[in]       item        The item node id.
+*
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * The order in which items are added to a sequence coincides with the order
+ * they are emitted into the output stream.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `sequence_id`: the id of a sequence node; could be negative.  It is a
+ *   fatal error if `sequence_id` does not refer to an existing sequence node.
+ *
+ * - `item_id`: the id of an item node; could be negative.  It is a fatal error
+ *   if `item_id` does not refer to an existing node.  Note that it is possible
+ *   for `item_id` to coincide with `sequence_id`, which means that the
+ *   sequence recursively contains itself.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for internal buffers.
  */
 YAML_DECLARE(int)
 yaml_document_append_sequence_item(yaml_document_t *document,
         int sequence, int item);
 /**
+        int sequence_id, int item_id);
+/*
  * Add a pair of a key and a value to a MAPPING node.
+ *
+ * @param[in,out]   document    A document object.
+ * @param[in]       mapping     The mapping node id.
+ * @param[in]       key         The key node id.
+ * @param[in]       value       The value node id.
+*
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * The order in which (key, value) pairs are added to a mapping coincides with
+ * the order in which they are presented in the output stream.  Note that the
+ * mapping key order is a presentation detail and should not used to convey any
+ * information.  An ordered mapping could be represented as a sequence of
+ * single-paired mappings.
+ *
+ * Arguments:
+ *
+ * - `document`: a document object.
+ *
+ * - `mapping_id`: the id of a mapping node; could be negative.  It is a
+ *   fatal error if `mapping_id` does not refer to an existing mapping node.
+ *
+ * - `key_id`: the id of a key node; could be negative.  It is a fatal error
+ *   if `key_id` does not refer to an existing node.
+ *
+ * - `value_id`: the id of a value node; could be negative.  It is a fatal
+ *   error if `value_id` does not refer to an existing node.
+ *
+ * Returns: `1` on success, `0` on error.  The function may fail if it cannot
+ * allocate memory for internal buffers.
  */
 YAML_DECLARE(int)
 yaml_document_append_mapping_pair(yaml_document_t *document,
+        int mapping, int key, int value);
+#endif
+/**
+ * @defgroup callbacks Callback Definitions
+ * @{
+ */
+/**
+        int mapping_id, int key_id, int value_id);
+/******************************************************************************
+ * Callback Definitions
+ ******************************************************************************/
+/*
  * The prototype of a read handler.
+ *
+ * The read handler is called when the parser needs to read more bytes from the
+ * source.  The handler should read no more than @a size bytes and write them
+ * to the @a buffer.  The number of the read bytes should be returned using the
+ * @a size_read variable.  If the handler reaches the stream end, @a size_read
+ * must be set to @c 0.
+ *
+ * @param[in,out]   data        A pointer to an application data specified by
+ *                              @c yaml_parser_set_reader().
+ * @param[out]      buffer      The buffer to write the data from the source.
+ * @param[in]       capacity    The maximum number of bytes the buffer can hold.
+ * @param[out]      length      The actual number of bytes read from the source.
+ *
+ * @returns On success, the handler should return @c 1.  If the handler failed,
+ * the returned value should be @c 0.  On EOF, the handler should set the
+ * @a size_read to @c 0 and return @c 1.
+ * The reader is called when the parser needs to read more bytes from the input
+ * stream.  The reader is given a buffer to fill and should returns the number
+ * of bytes read.  The reader should block if no data from the input stream is
+ * available, but it should return immediately if it could produce least one
+ * byte of the input stream.  If the reader reaches the stream end, it should
+ * return immediately setting the number of bytes read to `0`.
+ *
+ * Arguments:
+ *
+ * - `data`: a pointer to an application data specified with
+ *   `yaml_parser_set_reader()`.
+ *
+ * - `buffer`: a pointer to a buffer which should be filled with the bytes
+ *   from the input stream.
+ *
+ * - `capacity`: the maximum capacity of the buffer.
+ *
+ * - `length`: a pointer to save the actual number of bytes read from the input
+ *   stream; `length` equals `0` signifies that the reader reached the end of
+ *   the stream.
+ *
+ * Return: on success, the reader should return `1`.  If the reader fails for
+ * any reason, it should return `0`.  On the end of the input stream, the
+ * reader should set `length` to `0` and return `1`.
  */
 …
         size_t *length);
 /**
+/*
  * The prototype of a write handler.
+ *
+ * The write handler is called when the emitter needs to flush the accumulated
+ * characters to the output.  The handler should write @a size bytes of the
+ * @a buffer to the output.
+ *
+ * @param[in,out]   data        A pointer to an application data specified by
+ *                              @c yaml_emitter_set_writer().
+ * @param[in]       buffer      The buffer with bytes to be written.
+ * @param[in]       length      The number of bytes to be written.
+ *
+ * @returns On success, the handler should return @c 1.  If the handler failed,
+ * it should return @c 0.
+ * The writer is called when the emitter needs to flush the accumulated bytes
+ * into the output stream.
+ *
+ * Arguments:
+ *
+ * - `data`: a pointer to an application data specified with
+ *   `yaml_emitter_set_writer()`.
+ *
+ * - `buffer`: a pointer to a buffer with bytes to be written to the output
+ *   stream.
+ *
+ * - `length`: the number of bytes to be written.
+ *
+ * Returns: on success, the writer should return `1`.  If the writer fails for
+ * any reason, it should return `0`.
  */
 …
 /**
+ * The prototype of a tag resolver.
+ *
+ * The resolve handler is called when the parser encounters a new node without
+ * an explicit tag.  The handler should determine the correct tag of the node
+ * basing on the node kind, the path to the node from the document root and,
+ * in the case of the scalar node, the node value.  The handler is also called
+ * by the emitter to determine whether the node tag could be omitted.
+ *
+ * @param[in,out]   data        A pointer to an application data specified by
+ *                              @c yaml_parser_set_writter() or
+ *                              @c yaml_emitter_set_writer().
+ * @param[in]       node        Information about the new node.
+ * @param[out]      tag         The guessed node tag.
+ *
+ * @returns On success, the handler should return @c 1.  If the handler failed,
+ * it should return @c 0.
+ * The prototype of a nonspecific tag resolver.
+ *
+ * The resolver is called when the parser encounters a node without an explicit
+ * tag.  The resolver should determine the correct tag of the node from the
+ * path to the node from the root node and, in case of the scalar node, the
+ * node value.  The resolver is also called by the emitter to determine whether
+ * the node tag could be omitted.
+ *
+ * Arguments:
+ *
+ * - `data`: a pointer to an application data specified with
+ *   `yaml_parser_set_resolver()` or `yaml_emitter_set_resolver()`.
+ *
+ * - `node`: information about the new node.
+ *
+ * - `tag`: A pointer to save the guessed node tag.  The value returned by the
+ *   resolved is immediately copied.
+ *
+ * Returns: on success, the resolver should return `1`.  If the resolver fails
+ * for any reason, it should return `0`.
  */
 …
         yaml_char_t **tag);
+/** @} */
+/**
+ * @defgroup parser Parser Definitions
+ * @{
+ */
+/** The parser object. */
+/******************************************************************************
+ * Parser Definitions
+ ******************************************************************************/
+/*
+ * An opaque definition of the parser object.
+ *
+ * A parser object is used to parse an input YAML stream producing a sequence
+ * of YAML tokens, events or documents.
+ */
 typedef struct yaml_parser_s yaml_parser_t;
 /**
  * Create a new parser object.
+ *
  * This function creates a new parser object.  An application is responsible
  * for destroying the object using the @c yaml_parser_delete() function.
+ *
  * @returns a new parser object or @c NULL on error.
+/*
+ * Allocate a new parser object.
+ *
+ * An allocated parser object should be deleted with `yaml_parser_delete()`
+ *
+ * Returns: a new parser object or `NULL` on error.  The function may fail if
+ * it cannot allocate memory for internal buffers.
  */
 …
 yaml_parser_new(void);
+/**
+ * Destroy a parser.
+ *
+ * @param[in,out]   parser  A parser object.
+/*
+ * Deallocate a parser and free the internal parser data.
+ *
+ * A parser object must be previously allocated with `yaml_parser_new()`.
+ *
+ * Arguments:
+ *
+ * - `parser`: a parser object.
  */
 …
 yaml_parser_delete(yaml_parser_t *parser);
+/**
+ * Get a parser error.
+ *
+ * @param[in]   parser  A parser object.
+ * @param[out]  error   An error object.
+/*
+ * Clear and reinitialize the internal state of the parser.
+ *
+ * This function could be used for cleaning up a parser object after an error
+ * condition or after the end of the input stream is reached.  A cleaned parser
+ * object may be reused to parse another YAML stream.  Note that all the parser
+ * parameters including the read handler must be reset.
+ *
+ * Arguments:
+ *
+ * - `parser`: a parser object.
  */
 YAML_DECLARE(void)
+yaml_parser_get_error(yaml_parser_t *parser, yaml_error_t *error);
+/**
+ * Set a string input.
+ *
+ * Note that the @a input pointer must be valid while the @a parser object
+ * exists.  The application is responsible for destroing @a input after
+ * destroying the @a parser.
+ *
+ * @param[in,out]   parser  A parser object.
+ * @param[in]       buffer  A source data.
+ * @param[in]       length  The length of the source data in bytes.
+yaml_parser_clear(yaml_parser_t *parser);
+/*
+ * Get the parser error.
+ *
+ * Use this function to get a detailed error information after failure of one
+ * of the following functions: `yaml_parser_parse_token()`,
+ * `yaml_parser_parse_event()`, `yaml_parser_parse_document()`,
+ * `yaml_parser_parse_single_document()`.
+ *
+ * The pointer returned by the function is only valid until the parser object
+ * is not modified.  However the error object could be safely copied.
+ *
+ * Arguments:
+ *
+ * - `parser`: a parser object.
+ *
+ * Returns: a pointer to an error object.  The returned pointer is only valid
+ * until the parser object is not modified or deleted.  However the error
+ * object could be safely copied.
+ */
+YAML_DECLARE(yaml_error_t *)
+yaml_parser_get_error(yaml_parser_t *parser);
+/*
+ * Set the parser to read the input stream from a character buffer.
+ *
+ * Arguments:
+ *
+ * - `parser`: a parser object.
+ *
+ * - `buffer`: a pointer to character buffer containing the input stream.  The
+ *   buffer must be valid until the parser object is cleared or deleted.
+ *
+ * - `length`: the length of the buffer in bytes.
  */
 …
         const unsigned char *buffer, size_t length);
+/**
+ * Set a file input.
+ *
+ * @a file should be a file object open for reading.  The application is
+ * responsible for closing the @a file.
+ *
+ * @param[in,out]   parser  A parser object.
+ * @param[in]       file    An open file.
+/*
+ * Set the parser to read the input stream from a file.
+ *
+ * Arguments:
+ *
+ * - `parser`: a parser object.
+ *
+ * - `file`: a pointer to an open file object.  The pointer must be valid until
+ *   the parser object is cleared or deleted.
  */
 …
 yaml_parser_set_file_reader(yaml_parser_t *parser, FILE *file);
+/**
+ * Set a generic input handler.
+ *
+ * @param[in,out]   parser  A parser object.
+ * @param[in]       reader  A read handler.
+ * @param[in]       data    Any application data for passing to the read
+ *                          handler.
+/*
+ * Set an input stream reader for a parser.
+ *
+ * Arguments:
+ *
+ * - `parser`: a parser object.
+ *
+ * - `reader`: a read handler.
+ *
+ * - `data`: application data for passing to the reader.
  */
 …
         yaml_reader_t *reader, void *data);
+#if 0
 /**
  * Set the standard resolve handler.
+ *
  * The standard resolver recognize the following scalar kinds: !!null, !!bool,
  * !!str, !!int and !!float.
+ *
  * @param[in,out]   parser  A parser object.
+/*
+ * Set the standard nonspecific tag resolver for a parser.
+ *
+ * The standard resolver recognizes the following scalar tags: `!!null`,
+ * `!!bool`, `!!str`, `!!int`, and `!!float`.
+ *
+ * Arguments:
+ *
+ * - `parser`: a parser object.
  */
 …
 yaml_parser_set_standard_resolver(yaml_parser_t *parser);
 /**
  * Set the resolve handler.
+ *
  * The standard resolver recognize the following scalar kinds: !!null, !!bool,
  * !!str, !!int and !!float.
+ *
  * @param[in,out]   parser      A parser object.
  * @param[in]       resolver    A resolve handler.
  * @param[in]       data        Any application data for passing to the resolve
  *                              handler.
+/*
+ * Set a nonspecific tag resolver for a parser.
+ *
+ * Arguments:
+ *
+ * - `parser`: a parser object.
+ *
+ * - `resolver`: a resolve handler.
+ *
+ * - `data`: application data for passing to the resolver.
  */
 …
         yaml_resolver_t *resolver, void *data);
+#endif
+/**
+ * Set the source encoding.
+ *
+ * @param[in,out]   parser      A parser object.
+ * @param[in]       encoding    The source encoding.
+/*
+ * Set the input stream encoding.
+ *
+ * Typically the parser guesses the input stream encoding by the BOM mark.  If
+ * the BOM mark is not present, the UTF-8 encoding is assumed.  An application
+ * could override the detection mechanism by specifying the the encoding
+ * explicitly.
+ *
+ * Arguments:
+ *
+ * - `parser`: a parser object.
+ *
+ * - `encoding`: the input stream encoding.
  */
 …
 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
+/**
+ * Scan the input stream and produce the next token.
+ *
+ * Call the function subsequently to produce a sequence of tokens corresponding
+ * to the input stream.  The initial token has the type
+ * @c YAML_STREAM_START_TOKEN while the ending token has the type
+ * @c YAML_STREAM_END_TOKEN.
+ *
+ * An application is responsible for freeing any buffers associated with the
+ * produced token object using the @c yaml_token_delete() function.
+ *
+ * An application must not alternate the calls of @c yaml_parser_scan() with
+ * the calls of @c yaml_parser_parse() or @c yaml_parser_load(). Doing this
+ * will break the parser.
+ *
+ * @param[in,out]   parser      A parser object.
+ * @param[out]      token       An empty token object.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+/*
+ * Parse the input stream and produce the next token.
+ *
+ * An application may call this function subsequently to produce a sequence of
+ * tokens corresponding to the input stream.  The first token in the sequence
+ * is STREAM-START and the last token is STREAM-END.  When the stream ends, the
+ * parser produces empty tokens.
+ *
+ * An application must not alternate calls of the functions
+ * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`,
+ * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on
+ * the same parser object.
+ *
+ * Arguments:
+ *
+ * - `parser`: a parser object.
+ *
+ * - `token`: an empty token object to save the token produced by the parser.
+ *   An application is responsible for clearing or deleting the produced token.
+ *   If the parser fails or the stream end is reached, the object is kept
+ *   empty.
+ *
+ * Returns: `1` on success, `0` on error.  If the function succeeds and the
+ * stream end is not reached, the token data is saved to the given token
+ * object.  If the function fails, the error details could be obtained with
+ * `yaml_parser_get_error()`.  In case of error, the parser is non-functional
+ * until it is cleared.
  */
 …
 yaml_parser_parse_token(yaml_parser_t *parser, yaml_token_t *token);
 /**
+/*
  * Parse the input stream and produce the next parsing event.
+ *
+ * Call the function subsequently to produce a sequence of events corresponding
+ * to the input stream.  The initial event has the type
+ * @c YAML_STREAM_START_EVENT while the ending event has the type
+ * @c YAML_STREAM_END_EVENT.
+ *
+ * An application is responsible for freeing any buffers associated with the
+ * produced event object using the @c yaml_event_delete() function.
+ *
+ * An application must not alternate the calls of @c yaml_parser_parse() with
+ * the calls of @c yaml_parser_scan() or @c yaml_parser_load(). Doing this will
+ * break the parser.
+ *
+ * @param[in,out]   parser      A parser object.
+ * @param[out]      event       An empty event object.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * An application may call this function subsequently to produce a sequence of
+ * events corresponding to the input stream.  The produced events satisfy
+ * the grammar:
+ *
+ *      stream ::= STREAM-START document* STREAM-END
+ *      document ::= DOCUMENT-START node DOCUMENT-END
+ *      node ::= ALIAS | SCALAR | sequence | mapping
+ *      sequence ::= SEQUENCE-START node* SEQUENCE-END
+ *      mapping ::= MAPPING-START (node node)* MAPPING-END
+ *
+ * When the stream ends, the parser produces empty tokens.
+ *
+ * An application must not alternate calls of the functions
+ * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`,
+ * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on
+ * the same parser object.
+ *
+ * Arguments:
+ *
+ * - `parser`: a parser object.
+ *
+ * - `event`: an empty event object to save the event produced by the parser.
+ *   An application is responsible for clearing or deleting the produced event.
+ *   Alternatively the produced event could be fed to the emitter.  If the
+ *   parser fails or the stream end is reached, the object is kept empty.
+ *
+ * Returns: `1` on success, `0` on error.  If the function succeeds and the
+ * stream end is not reached, the event data is saved to the given event
+ * object.  If the function fails, the error details could be obtained with
+ * `yaml_parser_get_error()`.  In case of error, the parser is non-functional
+ * until it is cleared.
  */
 …
 yaml_parser_parse_event(yaml_parser_t *parser, yaml_event_t *event);
+#if 0
+/**
+/*
  * Parse the input stream and produce the next YAML document.
+ *
+ * Call this function subsequently to produce a sequence of documents
+ * constituting the input stream.
+ *
+ * If the produced document has no root node, it means that the document
+ * end has been reached.
+ *
+ * An application is responsible for freeing any data associated with the
+ * produced document object using the @c yaml_document_delete() function.
+ *
+ * An application must not alternate the calls of @c yaml_parser_load() with
+ * the calls of @c yaml_parser_scan() or @c yaml_parser_parse(). Doing this
+ * will break the parser.
+ *
+ * @param[in,out]   parser      A parser object.
+ * @param[out]      document    An empty document object.
+ *
+ * @return @c 1 if the function succeeded, @c 0 on error.
+ * An application may call this function subsequently to produce a sequence of
+ * documents constituting the input stream.  When the stream ends, the parser
+ * produces empty documents.
+ *
+ * An application must not alternate calls of the functions
+ * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`,
+ * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on
+ * the same parser object.
+ *
+ * Arguments:
+ *
+ * - `parser`: a parser object.
+ *
+ * - `document`: an empty document object to save the document produced by the
+ *   parser.  An application is responsible for clearing or deleting the
+ *   produced document.  Alternatively the produced document could be fed to
+ *   the emitter.  If the parser fails or the stream end is reached, the object
+ *   is kept empty.
+ *
+ * Returns: `1` on success, `0` on error.  If the function succeeds and the
+ * stream end is not reached, the document data is saved to the given document
+ * object.  If the function fails, the error details could be obtained with
+ * `yaml_parser_get_error()`.  In case of error, the parser is non-functional
+ * until it is cleared.
  */
 …
 yaml_parser_parse_document(yaml_parser_t *parser, yaml_document_t *document);
+#endif
+/** @} */
+/**
+ * @defgroup emitter Emitter Definitions
+ * @{
+ */
+/** The emitter object. */
+/*
+ * Parse the input stream containing a single YAML document.
+ *
+ * An application may call this function to ensure that the input stream contain
+ * no more that one document.  If the stream is empty, the parser produces an
+ * empty document.  If the stream contains a single document, the parser returns
+ * it.  If the stream contains more than one document, the parser produces an
+ * error.
+ *
+ * An application must not alternate calls of the functions
+ * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`,
+ * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on
+ * the same parser object.
+ *
+ * Arguments:
+ *
+ * - `parser`: a parser object.
+ *
+ * - `document`: an empty document object to save the document produced by the
+ *   parser.  An application is responsible for clearing or deleting the
+ *   produced document.  Alternatively the produced document could be fed to
+ *   the emitter.  If the parser fails or the stream is empty, the object is
+ *   kept empty.
+ *
+ * Returns: `1` on success, `0` on error.  If the function succeeds and the
+ * stream is not empty, the document data is saved to the given document
+ * object.  If the function fails, the error details could be obtained with
+ * `yaml_parser_get_error()`.  In case of error, the parser is non-functional
+ * until it is cleared.
+ */
+YAML_DECLARE(int)
+yaml_parser_parse_single_document(yaml_parser_t *parser,
+        yaml_document_t *document);
+/******************************************************************************
+ * Emitter Definitions
+ ******************************************************************************/
+/*
+ * An opaque definition of the emitter object.
+ *
+ * An emitter object is used to emit YAML events or documents into an output
+ * YAML stream.
+ */
 typedef struct yaml_emitter_s yaml_emitter_t;
 /**
  * Create a new emitter object.
+ *
  * This function creates a new emitter object.  An application is responsible
  * for destroying the object using the @c yaml_emitter_delete() function.
+ *
  * @returns a new emitter object or @c NULL on error.
+/*
+ * Allocate a new emitter object.
+ *
+ * An allocated emitter object should be deleted with `yaml_emitter_delete()`.
+ *
+ * Returns: a new emitter or `NULL` on error.  The function mail fail if it
+ * cannot allocate memory for internal buffers.
  */
 …
 yaml_emitter_new(void);
+/**
+ * Destroy an emitter.
+ *
+ * @param[in,out]   emitter     An emitter object.
+/*
+ * Deallocate an emitter and free the internal emitter data.
+ *
+ * An emitter object must be previously allocated with `yaml_emitter_new()`.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
  */
 …
 yaml_emitter_delete(yaml_emitter_t *emitter);
+/**
+ * Get an emitter error.
+ *
+ * @param[in]   emitter An emitter object.
+ * @param[out]  error   An error object.
+/*
+ * Clear and reinitialize the internal state of the emitter.
+ *
+ * This function could be used for cleaning up an emitter object after an error
+ * condition or after a complete YAML stream was produced.  A cleaned emitter
+ * object may be reused to produce another YAML stream.  Note that all the
+ * emitter parameters including the write handler must be reset.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
  */
 YAML_DECLARE(void)
+yaml_emitter_get_error(yaml_emitter_t *emitter, yaml_error_t *error);
+/**
+ * Set a string output.
+ *
+ * The emitter will write the output characters to the @a output buffer of the
+ * size @a size.  The emitter will set @a size_written to the number of written
+ * bytes.  If the buffer is smaller than required, the emitter produces the
+ * @c YAML_WRITE_ERROR error.
+ *
+ * @param[in,out]   emitter         An emitter object.
+ * @param[in]       buffer          An output buffer.
+ * @param[in]       capacity        The buffer size.
+ * @param[in]       length          The pointer to save the number of written
+ *                                  bytes.
+yaml_emitter_clear(yaml_emitter_t *emitter);
+/*
+ * Get the emitter error.
+ *
+ * Use this function to get a detailed error information after failure of one
+ * of the following functions: `yaml_emitter_emit_event()`,
+ * `yaml_emitter_open()`, `yaml_emitter_close()`,
+ * `yaml_emitter_emit_document()`, `yaml_emitter_emit_single_document()`.
+ *
+ * The pointer returned by the function is only valid until the emitter object
+ * is not modified.  However the error object could be safely copied.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * Returns: a pointer to an error object.  The returned pointer is only valid
+ * until the emitter object is not modified or deleted.  However the error
+ * object could be safely copied.
+ */
+YAML_DECLARE(yaml_error_t *)
+yaml_emitter_get_error(yaml_emitter_t *emitter);
+/*
+ * Set the emitter to dump the generated YAML stream into a string buffer.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * - `buffer`: a pointer to a buffer to store the generated YAML stream.  The
+ *   pointer must be valid until the emitter object is cleared or deleted.
+ *
+ * - `capacity`: the size of the buffer.  The emitter will fail if the buffer
+ *   is smaller than required to hold the whole stream.
+ *
+ * - `length`: a pointer to save the length of the produced stream (in bytes).
  */
 …
         unsigned char *buffer, size_t capacity, size_t *length);
+/**
+ * Set a file output.
+ *
+ * @a file should be a file object open for writing.  The application is
+ * responsible for closing the @a file.
+ *
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       file        An open file.
+/*
+ * Set the emitter to dump the generated YAML stream into a file.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * - `file`: a pointer to a file open for writing.  The pointer must be valid
+ *   until the emitter object is cleared or deleted.
  */
 …
 yaml_emitter_set_file_writer(yaml_emitter_t *emitter, FILE *file);
+/**
+ * Set a generic output handler.
+ *
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       writer      A write handler.
+ * @param[in]       data        Any application data for passing to the write
+ *                              handler.
+/*
+ * Set the output stream writer for an emitter.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * - `writer`: a write handler.
+ *
+ * - `data`: application data for passing to the writer.
  */
 …
         yaml_writer_t *writer, void *data);
+#if 0
 /**
  * Set the standard resolve handler.
+ *
  * The standard resolver recognize the following scalar kinds: !!null, !!bool,
  * !!str, !!int and !!float.
+ *
  * @param[in,out]   emitter An emitter object.
+/*
+ * Set the standard nonspecific tag resolver for an emitter.
+ *
+ * The standard resolver recognizes the following scalar tags: `!!null`,
+ * `!!bool`, `!!str`, `!!int`, and `!!float`.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
  */
 …
 yaml_emitter_set_standard_resolver(yaml_emitter_t *emitter);
 /**
  * Set the resolve handler.
+ *
  * The standard resolver recognize the following scalar kinds: !!null, !!bool,
  * !!str, !!int and !!float.
+ *
  * @param[in,out]   emitter     An emitter object.
  * @param[in]       resolver    A resolve handler.
  * @param[in]       data        Any application data for passing to the resolve
  *                              handler.
+/*
+ * Set a nonspecific tag resolver for an emitter.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * - `resolver`: a resolve handler.
+ *
+ * - `data`: application data for passing to the resolver.
  */
 …
         yaml_resolver_t *resolver, void *data);
+#endif
+/**
+ * Set the output encoding.
+ *
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       encoding    The output encoding.
+/*
+ * Set the output stream encoding.
+ *
+ * The emitter uses the UTF-8 encoding for the output stream unless another
+ * encoding is specified explicitly.  The encoding could be specified using
+ * this function or via the `encoding` parameter of the STREAM-START event.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * - `encoding`: the output stream encoding.
  */
 …
 yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
+/**
+ * Set if the output should be in the "canonical" format as in the YAML
+ * specification.
+ *
+ * @param[in,out]   emitter         An emitter object.
+ * @param[in]       is_canonical    If the output is canonical.
+/*
+ * Specify if the emitter should use the "canonical" output format.
+ *
+ * The "canonical" format uses the flow style for collections and the
+ * double-quoted style for scalars.  Node tags are always dumped explicitly.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * - `is_canonical`: `1` to set the "canonical" format, `0` otherwise.
  */
 …
 yaml_emitter_set_canonical(yaml_emitter_t *emitter, int is_canonical);
 /**
+/*
  * Set the intendation increment.
+ *
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       indent      The indentation increment (1 < . < 10).
+ * The default intendation increment is `2`.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * - `indent`: the indentation increment; a number between `2` and `9`.
  */
 …
 yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
+/**
+ * Set the preferred line width. @c -1 means unlimited.
+ *
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       width       The preferred line width.
+/*
+ * Set the preferred line width.
+ *
+ * The default preferred line width is `80`.  The given line width is only a
+ * stylistic hint and could be violated by the emitter.  When the line width is
+ * exceeded, the emitter seeks for a way to move to the next line.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * - `width`: the preferred line width; `-1` means unlimited.
  */
 …
 yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
+/**
+ * Set if unescaped non-ASCII characters are allowed.
+ *
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       is_unicode  If unescaped Unicode characters are allowed.
+/*
+ * Specify if non-ASCII characters could be emitted unescaped.
+ *
+ * By default, the emitter always escapes non-ASCII characters using the `\u`
+ * or `\U` format.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * - `is_unicode`: `1` if unescaped non-ASCII characters are allowed; `0`
+ *   otherwise.
  */
 …
 yaml_emitter_set_unicode(yaml_emitter_t *emitter, int is_unicode);
 /**
+/*
  * Set the preferred line break.
+ *
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       line_break  The preferred line break.
+ * By default, the emitter uses the LN character for line breaks.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * - `line_break`: the preferred line break.
  */
 …
 yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
+/**
+ * Emit an event.
+ *
+ * The event object may be generated using the yaml_parser_parse() function.
+ * The emitter takes the responsibility for the event object and destroys its
+ * content after it is emitted. The event object is destroyed even if the
+ * function fails.
+ *
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in,out]   event       An event object.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+/*
+ * Emit an event to the output YAML stream.
+ *
+ * An application needs to call this function subsequently to produce a whole
+ * YAML stream.  The event sequence must satisfy the following grammar:
+ *
+ *      stream ::= STREAM-START document* STREAM-END
+ *      document ::= DOCUMENT-START node DOCUMENT-END
+ *      node ::= ALIAS | SCALAR | sequence | mapping
+ *      sequence ::= SEQUENCE-START node* SEQUENCE-END
+ *      mapping ::= MAPPING-START (node node)* MAPPING-END
+ *
+ * An application must not alternate the calls of the functions
+ * `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and
+ * `yaml_emitter_emit_single_document()` on the same emitter object.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * - `event`: an event to emit.  The event must be previously initialized using
+ *   either one of the functions `yaml_event_create_*()` or with
+ *   `yaml_parser_parse_event()`.  The emitter takes the responsibility for the
+ *   event data and clears the event, so that it becomes empty.  The event is
+ *   cleared even if the function fails.
+ *
+ * Returns: `1` on success, `0` on error.  Note that the emitter may not
+ * immediately dump the given event, so that the function could indicate
+ * success on an errorneous event.  In this case, some of the next calls of the
+ * function will generate an error.  If the function fails, the error details
+ * could be obtained with `yaml_emitter_get_error()`.  In case of error, the
+ * emitter is non-functional until it is cleared.
  */
 …
 yaml_emitter_emit_event(yaml_emitter_t *emitter, yaml_event_t *event);
+#if 0
+/**
+/*
  * Start a YAML stream.
+ *
+ * This function should be used before the first @c yaml_emitter_dump() is
+ * called.
+ *
+ * @param[in,out]   emitter     An emitter object.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ */
+YAML_DECLARE(int)
+yaml_emitter_open(yaml_emitter_t *emitter);
+/**
+ * This function should be used in conjunction with
+ * `yaml_emitter_emit_document()` and `yaml_emitter_end()`.  This function must
+ * be called once before any documents are emitted.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * Returns: `1` on success, `0` on error.  If the function fails, the error
+ * details could be obtained with `yaml_emitter_get_error()`.  In case of
+ * error, the emitter is non-functional until it is cleared.
+ */
+YAML_DECLARE(int)
+yaml_emitter_start(yaml_emitter_t *emitter);
+/*
  * Finish a YAML stream.
+ *
+ * This function should be used after the last @c yaml_emitter_dump() is
+ * called.
+ *
+ * @param[in,out]   emitter     An emitter object.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ */
+YAML_DECLARE(int)
+yaml_emitter_close(yaml_emitter_t *emitter);
+/**
+ * This function should be used in conjunction with `yaml_emitter_start()` and
+ * `yaml_emitter_emit_document()`.  This function must be called once after all
+ * documents are emitted.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * Returns: `1` on success, `0` on error.  If the function fails, the error
+ * details could be obtained with `yaml_emitter_get_error()`.  In case of
+ * error, the emitter is non-functional until it is cleared.
+ */
+YAML_DECLARE(int)
+yaml_emitter_end(yaml_emitter_t *emitter);
+/*
  * Emit a YAML document.
+ *
+ * The document object may be generated using the @c yaml_parser_load()
+ * function or the @c yaml_document_initialize() function.  The emitter takes
+ * the responsibility for the document object and destoys its content after
+ * it is emitted. The document object is destroyed even if the function fails.
+ *
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in,out]   document    A document object.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ * Before emitting any documents, the function `yaml_emitter_start()` must be
+ * called.  After all documents are emitted, the function `yaml_emitter_end()`
+ * must be called.
+ *
+ * An application must not alternate the calls of the functions
+ * `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and
+ * `yaml_emitter_emit_single_document()` on the same emitter object.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * - `document`: a document to emit.  The document must have a root node with
+ *   all the other nodes reachable from it.  The document may be prepared using
+ *   the functions `yaml_document_create()`, `yaml_document_add_*()` and
+ *   `yaml_document_append_*()` or obtained via `yaml_parser_parse_document()`.
+ *   The emitter takes the responsibility for the document content and clears
+ *   the document, so that it becomes empty.  The document is cleared even if
+ *   the function fails.
+ *
+ * Returns: `1` on success, `0` on error.  If the function fails, the error
+ * details could be obtained with `yaml_emitter_get_error()`.  In case of
+ * error, the emitter is non-functional until it is cleared.
  */
 …
 yaml_emitter_emit_document(yaml_emitter_t *emitter, yaml_document_t *document);
+#endif
+/**
+ * Flush the accumulated characters to the output stream.
+ *
+ * @param[in,out]   emitter     An emitter object.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+/*
+ * Emit a YAML stream consisting of a single document.
+ *
+ * This function is a shorthand of the calls:
+ *
+ *      yaml_emitter_start(emitter)
+ *      yaml_emitter_emit_document(emitter, document)
+ *      yaml_emitter_end(emitter)
+ *
+ * An application must not alternate the calls of the functions
+ * `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and
+ * `yaml_emitter_emit_single_document()` on the same emitter object.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * - `document`: a document to emit.  The document must have a root node with
+ *   all the other nodes reachable from it.  The document may be prepared using
+ *   the functions `yaml_document_create()`, `yaml_document_add_*()` and
+ *   `yaml_document_append_*()` or obtained via `yaml_parser_parse_document()`.
+ *   The emitter takes the responsibility for the document content and clears
+ *   the document, so that it becomes empty.  The document is cleared even if
+ *   the function fails.
+ *
+ * Returns: `1` on success, `0` on error.  If the function fails, the error
+ * details could be obtained with `yaml_emitter_get_error()`.  In case of
+ * error, the emitter is non-functional until it is cleared.
+ */
+YAML_DECLARE(int)
+yaml_emitter_emit_single_document(yaml_emitter_t *emitter,
+        yaml_document_t *document);
+/*
+ * Flush the accumulated characters.
+ *
+ * This function flushes the accumulated characters from the internal emitter
+ * buffer to the output stream.  Note that the buffer is flushed automatically
+ * when a complete document has emitted or a stream has ended.
+ *
+ * Arguments:
+ *
+ * - `emitter`: an emitter object.
+ *
+ * Returns: `1` on success, `0` on error.  If the function fails, the error
+ * details could be obtained with `yaml_emitter_get_error()`.  In case of
+ * error, the emitter is non-functional until it is cleared.
  */
 …
 yaml_emitter_flush(yaml_emitter_t *emitter);
-/** @} */
 #ifdef __cplusplus

Note: See TracChangeset for help on using the changeset viewer.