Kirill Simonov avatar Kirill Simonov committed b3f4201

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

Comments (0)

Files changed (4)

 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:
 $ ./configure
 $ make
 $ make
 # 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'.
 
 Post your questions and opinions to the YAML-Core mailing list:
 LibYAML is written by Kirill Simonov <xi@resolvent.net>.  It is released
 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.

doc/doxygen.cfg

-# Doxyfile 1.4.4
-
-#---------------------------------------------------------------------------
-# Project related configuration options
-#---------------------------------------------------------------------------
-PROJECT_NAME           = $(PACKAGE)
-PROJECT_NUMBER         = $(VERSION)
-OUTPUT_DIRECTORY       = $(top_builddir)/doc/
-CREATE_SUBDIRS         = NO
-OUTPUT_LANGUAGE        = English
-USE_WINDOWS_ENCODING   = NO
-BRIEF_MEMBER_DESC      = YES
-REPEAT_BRIEF           = YES
-ABBREVIATE_BRIEF       = 
-ALWAYS_DETAILED_SEC    = NO
-INLINE_INHERITED_MEMB  = NO
-FULL_PATH_NAMES        = YES
-STRIP_FROM_PATH        = 
-STRIP_FROM_INC_PATH    = 
-SHORT_NAMES            = NO
-JAVADOC_AUTOBRIEF      = YES
-MULTILINE_CPP_IS_BRIEF = NO
-DETAILS_AT_TOP         = NO
-INHERIT_DOCS           = YES
-DISTRIBUTE_GROUP_DOC   = NO
-SEPARATE_MEMBER_PAGES  = NO
-TAB_SIZE               = 8
-ALIASES                = 
-OPTIMIZE_OUTPUT_FOR_C  = YES
-OPTIMIZE_OUTPUT_JAVA   = NO
-SUBGROUPING            = YES
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-EXTRACT_ALL            = NO
-EXTRACT_PRIVATE        = NO
-EXTRACT_STATIC         = NO
-EXTRACT_LOCAL_CLASSES  = NO
-EXTRACT_LOCAL_METHODS  = NO
-HIDE_UNDOC_MEMBERS     = NO
-HIDE_UNDOC_CLASSES     = NO
-HIDE_FRIEND_COMPOUNDS  = NO
-HIDE_IN_BODY_DOCS      = NO
-INTERNAL_DOCS          = NO
-CASE_SENSE_NAMES       = YES
-HIDE_SCOPE_NAMES       = NO
-SHOW_INCLUDE_FILES     = YES
-INLINE_INFO            = YES
-SORT_MEMBER_DOCS       = NO
-SORT_BRIEF_DOCS        = NO
-SORT_BY_SCOPE_NAME     = NO
-GENERATE_TODOLIST      = YES
-GENERATE_TESTLIST      = YES
-GENERATE_BUGLIST       = YES
-GENERATE_DEPRECATEDLIST= YES
-ENABLED_SECTIONS       = 
-MAX_INITIALIZER_LINES  = 30
-SHOW_USED_FILES        = YES
-SHOW_DIRECTORIES       = YES
-FILE_VERSION_FILTER    = 
-#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-QUIET                  = NO
-WARNINGS               = YES
-WARN_IF_UNDOCUMENTED   = YES
-WARN_IF_DOC_ERROR      = YES
-WARN_NO_PARAMDOC       = NO
-WARN_FORMAT            = "$file:$line: $text"
-WARN_LOGFILE           = 
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-INPUT                  = $(top_srcdir)/include/
-FILE_PATTERNS          = *.h
-RECURSIVE              = YES
-EXCLUDE                = 
-EXCLUDE_SYMLINKS       = NO
-EXCLUDE_PATTERNS       = 
-EXAMPLE_PATH           = 
-EXAMPLE_PATTERNS       = 
-EXAMPLE_RECURSIVE      = NO
-IMAGE_PATH             = 
-INPUT_FILTER           = 
-FILTER_PATTERNS        = 
-FILTER_SOURCE_FILES    = NO
-#---------------------------------------------------------------------------
-# configuration options related to source browsing
-#---------------------------------------------------------------------------
-SOURCE_BROWSER         = NO
-INLINE_SOURCES         = NO
-STRIP_CODE_COMMENTS    = YES
-REFERENCED_BY_RELATION = NO
-REFERENCES_RELATION    = NO
-USE_HTAGS              = NO
-VERBATIM_HEADERS       = NO
-#---------------------------------------------------------------------------
-# configuration options related to the alphabetical class index
-#---------------------------------------------------------------------------
-ALPHABETICAL_INDEX     = NO
-COLS_IN_ALPHA_INDEX    = 5
-IGNORE_PREFIX          = 
-#---------------------------------------------------------------------------
-# configuration options related to the HTML output
-#---------------------------------------------------------------------------
-GENERATE_HTML          = YES
-HTML_OUTPUT            = html
-HTML_FILE_EXTENSION    = .html
-HTML_HEADER            = 
-HTML_FOOTER            = 
-HTML_STYLESHEET        = 
-HTML_ALIGN_MEMBERS     = YES
-GENERATE_HTMLHELP      = NO
-CHM_FILE               = 
-HHC_LOCATION           = 
-GENERATE_CHI           = NO
-BINARY_TOC             = NO
-TOC_EXPAND             = NO
-DISABLE_INDEX          = NO
-ENUM_VALUES_PER_LINE   = 1
-GENERATE_TREEVIEW      = NO
-TREEVIEW_WIDTH         = 250
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX         = NO
-LATEX_OUTPUT           = latex
-LATEX_CMD_NAME         = latex
-MAKEINDEX_CMD_NAME     = makeindex
-COMPACT_LATEX          = NO
-PAPER_TYPE             = a4wide
-EXTRA_PACKAGES         = 
-LATEX_HEADER           = 
-PDF_HYPERLINKS         = NO
-USE_PDFLATEX           = NO
-LATEX_BATCHMODE        = NO
-LATEX_HIDE_INDICES     = NO
-#---------------------------------------------------------------------------
-# configuration options related to the RTF output
-#---------------------------------------------------------------------------
-GENERATE_RTF           = NO
-RTF_OUTPUT             = rtf
-COMPACT_RTF            = NO
-RTF_HYPERLINKS         = NO
-RTF_STYLESHEET_FILE    = 
-RTF_EXTENSIONS_FILE    = 
-#---------------------------------------------------------------------------
-# configuration options related to the man page output
-#---------------------------------------------------------------------------
-GENERATE_MAN           = NO
-MAN_OUTPUT             = man
-MAN_EXTENSION          = .3
-MAN_LINKS              = NO
-#---------------------------------------------------------------------------
-# configuration options related to the XML output
-#---------------------------------------------------------------------------
-GENERATE_XML           = NO
-XML_OUTPUT             = xml
-XML_SCHEMA             = 
-XML_DTD                = 
-XML_PROGRAMLISTING     = YES
-#---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-GENERATE_AUTOGEN_DEF   = NO
-#---------------------------------------------------------------------------
-# configuration options related to the Perl module output
-#---------------------------------------------------------------------------
-GENERATE_PERLMOD       = NO
-PERLMOD_LATEX          = NO
-PERLMOD_PRETTY         = YES
-PERLMOD_MAKEVAR_PREFIX = 
-#---------------------------------------------------------------------------
-# Configuration options related to the preprocessor   
-#---------------------------------------------------------------------------
-ENABLE_PREPROCESSING   = YES
-MACRO_EXPANSION        = YES
-EXPAND_ONLY_PREDEF     = YES
-SEARCH_INCLUDES        = YES
-INCLUDE_PATH           = 
-INCLUDE_FILE_PATTERNS  = 
-PREDEFINED             = "YAML_DECLARE(type)=type"
-EXPAND_AS_DEFINED      = 
-SKIP_FUNCTION_MACROS   = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to external references   
-#---------------------------------------------------------------------------
-TAGFILES               = 
-GENERATE_TAGFILE       = 
-ALLEXTERNALS           = NO
-EXTERNAL_GROUPS        = YES
-PERL_PATH              = /usr/bin/perl
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool   
-#---------------------------------------------------------------------------
-CLASS_DIAGRAMS         = NO
-HIDE_UNDOC_RELATIONS   = YES
-HAVE_DOT               = NO
-CLASS_GRAPH            = YES
-COLLABORATION_GRAPH    = YES
-GROUP_GRAPHS           = YES
-UML_LOOK               = NO
-TEMPLATE_RELATIONS     = NO
-INCLUDE_GRAPH          = YES
-INCLUDED_BY_GRAPH      = YES
-CALL_GRAPH             = NO
-GRAPHICAL_HIERARCHY    = YES
-DIRECTORY_GRAPH        = YES
-DOT_IMAGE_FORMAT       = png
-DOT_PATH               = 
-DOTFILE_DIRS           = 
-MAX_DOT_GRAPH_WIDTH    = 1024
-MAX_DOT_GRAPH_HEIGHT   = 1024
-MAX_DOT_GRAPH_DEPTH    = 0
-DOT_TRANSPARENT        = NO
-DOT_MULTI_TARGETS      = NO
-GENERATE_LEGEND        = YES
-DOT_CLEANUP            = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to the search engine   
-#---------------------------------------------------------------------------
-SEARCHENGINE           = NO

include/Makefile.am

 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
-/**
- * @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
 #define YAML_H
 
 #include <stdio.h>
 #include <string.h>
 
-/**
- * @defgroup export Export Definitions
- * @{
+/*****************************************************************************
+ * 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.
  */
 
-/** The public API declaration. */
-
 #ifdef WIN32
 #   if defined(YAML_DECLARE_STATIC)
 #       define  YAML_DECLARE(type)  type
 #   define  YAML_DECLARE(type)  type
 #endif
 
-/** @} */
-
-/**
- * @defgroup version Version Information
- * @{
+/*****************************************************************************
+ * Version Information
+ *****************************************************************************/
+
+/*
+ * The major, minor and patch version numbers of LibYAML.
  */
 
-/** The major version number. */
 #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_DECLARE(void)
 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_DECLARE(const char *)
 yaml_get_version_string(void);
 
-/** @} */
-
-/**
- * @defgroup styles Error Handling
- * @{
+/*****************************************************************************
+ * 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.
  */
 
-/** Many bad things could happen with the parser and the emitter. */
 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_DECLARE(int)
 yaml_error_message(yaml_error_t *error, char *buffer, size_t capacity);
 
-/** @} */
-
-/**
- * @defgroup basic Basic Types
- * @{
+/******************************************************************************
+ * 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.
  */
 
-/** The character type (UTF-8 octet). */
 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
- * @{
+/******************************************************************************
+ * 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.
  */
 
-/** Scalar styles. */
 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
- * @{
+/******************************************************************************
+ * 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.
  */
 
-/** Token types. */
 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_DECLARE(yaml_token_t *)
 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_DECLARE(void)
 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_DECLARE(int)
 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
- * @{
+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
  */
 
-/** Event types. */
 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_DECLARE(yaml_event_t *)
 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_DECLARE(void)
 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_DECLARE(int)
 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_DECLARE(int)
 yaml_event_create_stream_start(yaml_event_t *event,
         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_DECLARE(int)
 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_DECLARE(int)
 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_DECLARE(int)
 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_DECLARE(int)
 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_DECLARE(int)
 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_DECLARE(int)
 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_DECLARE(int)
 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_DECLARE(int)
 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_DECLARE(int)
 yaml_event_create_mapping_end(yaml_event_t *event);
 
-/**
- * Free any memory allocated for an event object.
- *
- * @param[in,out]   event   An event object.
+/******************************************************************************
+ * Documents and Nodes
+ ******************************************************************************/
+
+/*
+ * Well-known scalar tags.
  */
 
-YAML_DECLARE(void)
-yaml_event_destroy(yaml_event_t *event);
-
-/** @} */
-
-/**
- * @defgroup nodes Nodes
- * @{
+#define YAML_NULL_TAG       ((const yaml_char_t *) "tag:yaml.org,2002:null")
+#define YAML_BOOL_TAG       ((const yaml_char_t *) "tag:yaml.org,2002:bool")
+#define YAML_STR_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:str")
+#define YAML_INT_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:int")
+#define YAML_FLOAT_TAG      ((const yaml_char_t *) "tag:yaml.org,2002:float")
+
+/*
+ * Basic collection tags.
  */
 
-/** The tag @c !!null with the only possible value: @c null. */
-#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. */
 #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;
 
     /** The beginning of the document. */
 
 } 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_DECLARE(yaml_document_t *)
 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.
  */