X-Git-Url: http://andersk.mit.edu/gitweb/libyaml.git/blobdiff_plain/e35af832e9765e72b3ee3e337b2bfb958e3c5962..a907bf857a165a271a23140919c26cde14223dfc:/include/yaml.h

diff --git a/include/yaml.h b/include/yaml.h
index 0408a67..afb62f0 100644
--- a/include/yaml.h
+++ b/include/yaml.h
@@ -4,7 +4,7 @@
  * 
  * Include the header file with the code:
  * @code
- * #include <yaml/yaml.h>
+ * #include <yaml.h>
  * @endcode
  */
 
@@ -285,7 +285,7 @@ typedef struct {
 /**
  * Free any memory allocated for a token object.
  *
- * @param[in]   token   A token object.
+ * @param[in,out]   token   A token object.
  */
 
 YAML_DECLARE(void)
@@ -406,9 +406,9 @@ typedef struct {
 
     } data;
 
-    /** The beginning of the token. */
+    /** The beginning of the event. */
     yaml_mark_t start_mark;
-    /** The end of the token. */
+    /** The end of the event. */
     yaml_mark_t end_mark;
 
 } yaml_event_t;
@@ -416,7 +416,8 @@ typedef struct {
 /**
  * Create the STREAM-START event.
  *
- * @param[in]   event       An empty event object.
+ * @param[out]  event       An empty event object.
+ * @param[in]   encoding    The stream encoding.
  *
  * @returns @c 1 if the function succeeded, @c 0 on error.
  */
@@ -428,7 +429,7 @@ yaml_stream_start_event_initialize(yaml_event_t *event,
 /**
  * Create the STREAM-END event.
  *
- * @param[in]   event       An empty event object.
+ * @param[out]  event       An empty event object.
  *
  * @returns @c 1 if the function succeeded, @c 0 on error.
  */
@@ -442,7 +443,7 @@ yaml_stream_end_event_initialize(yaml_event_t *event);
  * The @a implicit argument is considered as a stylistic parameter and may be
  * ignored by the emitter.
  *
- * @param[in]   event                   An empty event object.
+ * @param[out]  event                   An empty event object.
  * @param[in]   version_directive       The %YAML directive value or @c NULL.
  * @param[in]   tag_directives_start    The beginning of the %TAG directives list.
  * @param[in]   tag_directives_end      The end of the %TAG directives list.
@@ -464,7 +465,7 @@ yaml_document_start_event_initialize(yaml_event_t *event,
  * The @a implicit argument is considered as a stylistic parameter and may be
  * ignored by the emitter.
  *
- * @param[in]   event       An empty event object.
+ * @param[out]  event       An empty event object.
  * @param[in]   implicit    If the document end indicator is implicit.
  *
  * @returns @c 1 if the function succeeded, @c 0 on error.
@@ -476,7 +477,7 @@ yaml_document_end_event_initialize(yaml_event_t *event, int implicit);
 /**
  * Create an ALIAS event.
  *
- * @param[in]   event       An empty event object.
+ * @param[out]  event       An empty event object.
  * @param[in]   anchor      The anchor value.
  *
  * @returns @c 1 if the function succeeded, @c 0 on error.
@@ -493,7 +494,7 @@ yaml_alias_event_initialize(yaml_event_t *event, yaml_char_t *anchor);
  * Either the @a tag attribute or one of the @a plain_implicit and
  * @a quoted_implicit flags must be set.
  *
- * @param[in]   event           An empty event object.
+ * @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.
  * @param[in]   value           The scalar value.
@@ -508,7 +509,7 @@ yaml_alias_event_initialize(yaml_event_t *event, yaml_char_t *anchor);
 YAML_DECLARE(int)
 yaml_scalar_event_initialize(yaml_event_t *event,
         yaml_char_t *anchor, yaml_char_t *tag,
-        yaml_char_t *value, size_t length,
+        yaml_char_t *value, int length,
         int plain_implicit, int quoted_implicit,
         yaml_scalar_style_t style);
 
@@ -519,7 +520,7 @@ yaml_scalar_event_initialize(yaml_event_t *event,
  *
  * Either the @a tag attribute or the @a implicit flag must be set.
  *
- * @param[in]   event       An empty event object.
+ * @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.
  * @param[in]   implicit    If the tag may be omitted.
@@ -536,7 +537,7 @@ yaml_sequence_start_event_initialize(yaml_event_t *event,
 /**
  * Create a SEQUENCE-END event.
  *
- * @param[in]   event       An empty event object.
+ * @param[out]  event       An empty event object.
  *
  * @returns @c 1 if the function succeeded, @c 0 on error.
  */
@@ -551,7 +552,7 @@ yaml_sequence_end_event_initialize(yaml_event_t *event);
  *
  * Either the @a tag attribute or the @a implicit flag must be set.
  *
- * @param[in]   event       An empty event object.
+ * @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.
  * @param[in]   implicit    If the tag may be omitted.
@@ -568,7 +569,7 @@ yaml_mapping_start_event_initialize(yaml_event_t *event,
 /**
  * Create a MAPPING-END event.
  *
- * @param[in]   event       An empty event object.
+ * @param[out]  event       An empty event object.
  *
  * @returns @c 1 if the function succeeded, @c 0 on error.
  */
@@ -579,12 +580,310 @@ yaml_mapping_end_event_initialize(yaml_event_t *event);
 /**
  * Free any memory allocated for an event object.
  *
- * @param[in]   event   An event object.
+ * @param[out]  event   An event object.
  */
 
 YAML_DECLARE(void)
 yaml_event_delete(yaml_event_t *event);
 
+/**
+ * @defgroup nodes Nodes
+ * @{
+ */
+
+#define YAML_NULL_TAG       "tag:yaml.org,2002:null"
+#define YAML_BOOL_TAG       "tag:yaml.org,2002:bool"
+#define YAML_STR_TAG        "tag:yaml.org,2002:str"
+#define YAML_INT_TAG        "tag:yaml.org,2002:int"
+#define YAML_FLOAT_TAG      "tag:yaml.org,2002:float"
+#define YAML_TIMESTAMP_TAG  "tag:yaml.org,2002:timestamp"
+
+#define YAML_SEQ_TAG        "tag:yaml.org,2002:seq"
+#define YAML_MAP_TAG        "tag:yaml.org,2002:map"
+
+#define YAML_DEFAULT_SCALAR_TAG     YAML_STR_TAG
+#define YAML_DEFAULT_SEQUENCE_TAG   YAML_SEQ_TAG
+#define YAML_DEFAULT_MAPPING_STYLE  YAML_MAP_TAG
+
+/** Node types. */
+typedef enum {
+    YAML_NO_NODE,
+
+    YAML_SCALAR_NODE,
+    YAML_SEQUENCE_NODE,
+    YAML_MAPPING_NODE
+} yaml_node_type_t;
+
+#if 0
+
+typedef struct _yaml_node_t yaml_node_item_t;
+
+typedef struct {
+    yaml_node_item_t key;
+    yaml_node_item_t value;
+} yaml_node_pair_t;
+
+/** The node structure. */
+typedef struct _yaml_node_t {
+
+    /** The node type. */
+    yaml_node_type_t type;
+
+    /* The reference counter. */
+    int references;
+
+    /** The node data. */
+    union {
+        
+        /** The scalar parameters (for @c YAML_SCALAR_NODE). */
+        struct {
+            /** The tag. */
+            yaml_char_t *tag;
+            /** The scalar value. */
+            yaml_char_t *value;
+            /** The length of the scalar value. */
+            size_t length;
+            /** The scalar style. */
+            yaml_scalar_style_t style;
+        } scalar;
+
+        /** The sequence parameters (for @c YAML_SEQUENCE_NODE). */
+        struct {
+            /** The tag. */
+            yaml_char_t *tag;
+            /** The stack of sequence items. */
+            struct {
+                /** The beginning of the stack. */
+                struct yaml_node_item_t *start;
+                /** The end of the stack. */
+                struct yaml_node_item_t *end;
+                /** The top of the stack. */
+                struct yaml_node_item_t *top;
+            } items;
+            /** The sequence style. */
+            yaml_sequence_style_t style;
+        } sequence;
+
+        /** The mapping parameters (for @c YAML_MAPPING_NODE). */
+        struct {
+            /** The tag. */
+            yaml_char_t *tag;
+            /** The stack of mapping pairs. */
+            struct {
+                /** The beginning of the stack. */
+                struct yaml_node_pair_t *start;
+                /** The end of the stack. */
+                struct yaml_node_pair_t *end;
+                /** The top of the stack. */
+                struct yaml_node_pair_t *top;
+            } pairs;
+            /** The mapping style. */
+            yaml_mapping_style_t style;
+        } mapping;
+
+    } data;
+
+    /** The beginning of the node. */
+    yaml_mark_t start_mark;
+    /** The end of the node. */
+    yaml_mark_t end_mark;
+
+} yaml_node_t;
+
+/**
+ * Create a SCALAR node.
+ *
+ * The @a style argument may be ignored by the emitter.
+ *
+ * @param[out]  node            An empty node object.
+ * @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 @c 1 if the function succeeded, @c 0 on error.
+ */
+
+YAML_DECLARE(int)
+yaml_scalar_node_initialize(yaml_node_t *node,
+        yaml_char_t *tag, yaml_char_t *value, int length,
+        yaml_scalar_style_t style);
+
+/**
+ * Create a SEQUENCE node.
+ *
+ * The @a style argument may be ignored by the emitter.
+ *
+ * @param[out]  node        An empty node object.
+ * @param[in]   tag         The sequence tag.
+ * @param[in]   style       The sequence style.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ */
+
+YAML_DECLARE(int)
+yaml_sequence_node_initialize(yaml_node_t *node,
+        yaml_char_t *tag, yaml_sequence_style_t style);
+
+/**
+ * Add an item to a SEQUENCE node
+ *
+ * @param[out]  node        A sequence node.
+ * @param[in]   item        An item node.
+*
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ */
+
+YAML_DECLARE(int)
+yaml_sequence_node_add_item(yaml_node_t *node, yaml_node_t *item)
+
+/**
+ * Create a SCALAR node and add it to a SEQUENCE node.
+ *
+ * @param[out]  node        A sequence node.
+ * @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 @c 1 if the function succeeded, @c 0 on error.
+ */
+
+YAML_DECLARE(int)
+yaml_sequence_node_add_scalar_item(yaml_node_t *node,
+        yaml_char_t *tag, yaml_char_t *value, int length,
+        yaml_scalar_style_t style);
+
+/**
+ * Get the number of subnodes of a SEQUENCE node.
+ *
+ * @param[in]  node         A sequence node.
+ *
+ * @returns the number of subnodes.
+ */
+
+YAML_DECLARE(size_t)
+yaml_sequence_node_get_length(yaml_node_t *node);
+
+/**
+ * Get a subnode of a SEQUENCE node.
+ *
+ * @param[in]   node        A sequence node.
+ * @param[in]   index       The index of a subnode.
+ * @param[out]  item        A subnode.
+ */
+
+YAML_DECLARE(void)
+yaml_sequence_node_get_item(yaml_node_t *node, size_t index,
+        yaml_node_t *item);
+
+/**
+ * Create a MAPPING node.
+ *
+ * The @a style argument may be ignored by the emitter.
+ *
+ * @param[out]  node        An empty node object.
+ * @param[in]   tag         The mapping tag.
+ * @param[in]   style       The mapping style.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ */
+
+YAML_DECLARE(int)
+yaml_mapping_node_initialize(yaml_node_t *node,
+        yaml_char_t *tag, yaml_mapping_style_t style);
+
+/**
+ * Add a key/value pair of nodes to a MAPPING node.
+ *
+ * @param[out]  node        A mapping node.
+ * @param[in]   key         A key node.
+ * @param[in]   value       A value node.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ */
+
+YAML_DECLARE(int)
+yaml_mapping_node_add_pair(yaml_node_t *node,
+        yaml_node_t *key, yaml_node_t *value)
+
+/**
+ * Create a scalar key and add the key/value pair to a MAPPING node.
+ *
+ * @param[out]  node        A mapping node.
+ * @param[in]   key_tag     The key node tag.
+ * @param[in]   key_value   The key node value.
+ * @param[in]   key_length  The length of the key node value.
+ * @param[in]   key_style   The key node style.
+ * @param[in]   value       A value node.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ */
+
+YAML_DECLARE(int)
+yaml_sequence_node_add_scalar_key_pair(yaml_node_t *node,
+        yaml_char_t *key_tag, yaml_char_t *key_value, int key_length,
+        yaml_scalar_style_t key_style,
+        yaml_node_t *value);
+
+/**
+ * Create a scalar key/value nodes and add the pair to a MAPPING node.
+ *
+ * @param[out]  node            A mapping node.
+ * @param[in]   key_tag         The key node tag.
+ * @param[in]   key_value       The key node value.
+ * @param[in]   key_length      The length of the key node value.
+ * @param[in]   key_style       The key node style.
+ * @param[in]   value_tag       The value node tag.
+ * @param[in]   value_value     The value node value.
+ * @param[in]   value_length    The length of the value node value.
+ * @param[in]   value_style     The value node style.
+ *
+ * @returns @c 1 if the function succeeded, @c 0 on error.
+ */
+
+YAML_DECLARE(int)
+yaml_sequence_node_add_scalar_pair(yaml_node_t *node,
+        yaml_char_t *key_tag, yaml_char_t *key_value, int key_length,
+        yaml_scalar_style_t key_style,
+        yaml_char_t *value_tag, yaml_char_t *value_value, int value_length,
+        yaml_scalar_style_t value_style);
+
+/**
+ * Get the number of subnode pairs of a MAPPING node.
+ *
+ * @param[in]  node         A mapping node.
+ *
+ * @returns the number of pairs.
+ */
+
+YAML_DECLARE(size_t)
+yaml_mapping_node_get_length(yaml_node_t *node);
+
+/**
+ * Get a subnode of a SEQUENCE node.
+ *
+ * @param[in]   node        A sequence node.
+ * @param[in]   index       The index of a subnode.
+ * @param[out]  key         The key subnode.
+ * @param[out]  value       The value subnode.
+ */
+
+YAML_DECLARE(void)
+yaml_mapping_node_get_pair(yaml_node_t *node, size_t index,
+        yaml_node_t *key, yaml_node_t *value);
+
+/**
+ * Delete a node and its subnodes.
+ *
+ * @param[out]  node    A node object.
+ */
+
+YAML_DECLARE(void)
+yaml_node_delete(yaml_node_t *node);
+
+#endif
+
 /** @} */
 
 /**
@@ -599,11 +898,11 @@ yaml_event_delete(yaml_event_t *event);
  * source.  The handler should write not more than @a size bytes to the @a
  * buffer.  The number of written bytes should be set to the @a length variable.
  *
- * @param[in]   data        A pointer to an application data specified by
- *                          @c yaml_parser_set_read_handler.
- * @param[out]  buffer      The buffer to write the data from the source.
- * @param[in]   size        The size of the buffer.
- * @param[out]  size_read   The actual number of bytes read from the source.
+ * @param[in,out]   data        A pointer to an application data specified by
+ *                              yaml_parser_set_input().
+ * @param[out]      buffer      The buffer to write the data from the source.
+ * @param[in]       size        The size of the buffer.
+ * @param[out]      size_read   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
@@ -710,11 +1009,11 @@ typedef struct {
         /** String input data. */
         struct {
             /** The string start pointer. */
-            unsigned char *start;
+            const unsigned char *start;
             /** The string end pointer. */
-            unsigned char *end;
+            const unsigned char *end;
             /** The string current position. */
-            unsigned char *current;
+            const unsigned char *current;
         } string;
 
         /** File input data. */
@@ -874,9 +1173,9 @@ typedef struct {
  * Initialize a parser.
  *
  * This function creates a new parser object.  An application is responsible
- * for destroying the object using the @c yaml_parser_delete function.
+ * for destroying the object using the yaml_parser_delete() function.
  *
- * @param[in]   parser  An empty parser object.
+ * @param[out]  parser  An empty parser object.
  *
  * @returns @c 1 if the function succeeded, @c 0 on error.
  */
@@ -887,7 +1186,7 @@ yaml_parser_initialize(yaml_parser_t *parser);
 /**
  * Destroy a parser.
  *
- * @param[in]   parser  A parser object.
+ * @param[in,out]   parser  A parser object.
  */
 
 YAML_DECLARE(void)
@@ -900,14 +1199,14 @@ yaml_parser_delete(yaml_parser_t *parser);
  * exists.  The application is responsible for destroing @a input after
  * destroying the @a parser.
  *
- * @param[in]   parser  A parser object.
- * @param[in]   input   A source data.
- * @param[in]   size    The length of the source data in bytes.
+ * @param[in,out]   parser  A parser object.
+ * @param[in]       input   A source data.
+ * @param[in]       size    The length of the source data in bytes.
  */
 
 YAML_DECLARE(void)
 yaml_parser_set_input_string(yaml_parser_t *parser,
-        unsigned char *input, size_t size);
+        const unsigned char *input, size_t size);
 
 /**
  * Set a file input.
@@ -915,8 +1214,8 @@ yaml_parser_set_input_string(yaml_parser_t *parser,
  * @a file should be a file object open for reading.  The application is
  * responsible for closing the @a file.
  *
- * @param[in]   parser  A parser object.
- * @param[in]   file    An open file.
+ * @param[in,out]   parser  A parser object.
+ * @param[in]       file    An open file.
  */
 
 YAML_DECLARE(void)
@@ -925,9 +1224,10 @@ yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
 /**
  * Set a generic input handler.
  *
- * @param[in]   parser  A parser object.
- * @param[in]   handler A read handler.
- * @param[in]   data    Any application data for passing to the read handler.
+ * @param[in,out]   parser  A parser object.
+ * @param[in]       handler A read handler.
+ * @param[in]       data    Any application data for passing to the read
+ *                          handler.
  */
 
 YAML_DECLARE(void)
@@ -937,8 +1237,8 @@ yaml_parser_set_input(yaml_parser_t *parser,
 /**
  * Set the source encoding.
  *
- * @param[in]   parser      A parser object.
- * @param[in]   encoding    The source encoding.
+ * @param[in,out]   parser      A parser object.
+ * @param[in]       encoding    The source encoding.
  */
 
 YAML_DECLARE(void)
@@ -955,11 +1255,11 @@ yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
  * 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. Doing this will break the parser.
+ * An application must not alternate the calls of yaml_parser_scan() with the
+ * calls of yaml_parser_parse(). Doing this will break the parser.
  *
- * @param[in]   parser      A parser object.
- * @param[in]   token       An empty token object.
+ * @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.
  */
@@ -976,13 +1276,13 @@ yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
  * @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.
+ * produced event object using the yaml_event_delete() function.
  *
- * An application must not alternate the calls of @c yaml_parser_scan with the
- * calls of @c yaml_parser_parse. Doing this will break the parser.
+ * An application must not alternate the calls of yaml_parser_scan() with the
+ * calls of yaml_parser_parse(). Doing this will break the parser.
  *
- * @param[in]   parser      A parser object.
- * @param[in]   event       An empty event object.
+ * @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.
  */
@@ -1004,10 +1304,10 @@ yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
  * characters to the output.  The handler should write @a size bytes of the
  * @a buffer to the output.
  *
- * @param[in]   data        A pointer to an application data specified by
- *                          @c yaml_emitter_set_write_handler.
- * @param[out]  buffer      The buffer with bytes to be written.
- * @param[in]   size        The size of the buffer.
+ * @param[in,out]   data        A pointer to an application data specified by
+ *                              yaml_emitter_set_output().
+ * @param[in]       buffer      The buffer with bytes to be written.
+ * @param[in]       size        The size of the buffer.
  *
  * @returns On success, the handler should return @c 1.  If the handler failed,
  * the returned value should be @c 0.
@@ -1255,9 +1555,9 @@ typedef struct {
  * Initialize an emitter.
  *
  * This function creates a new emitter object.  An application is responsible
- * for destroying the object using the @c yaml_emitter_delete function.
+ * for destroying the object using the yaml_emitter_delete() function.
  *
- * @param[in]   emitter An empty parser object.
+ * @param[out]      emitter     An empty parser object.
  *
  * @returns @c 1 if the function succeeded, @c 0 on error.
  */
@@ -1268,7 +1568,7 @@ yaml_emitter_initialize(yaml_emitter_t *emitter);
 /**
  * Destroy an emitter.
  *
- * @param[in]   emitter An emitter object.
+ * @param[in,out]   emitter     An emitter object.
  */
 
 YAML_DECLARE(void)
@@ -1282,10 +1582,11 @@ yaml_emitter_delete(yaml_emitter_t *emitter);
  * bytes.  If the buffer is smaller than required, the emitter produces the
  * YAML_WRITE_ERROR error.
  *
- * @param[in]   emitter         An emitter object.
- * @param[in]   output          An output buffer.
- * @param[in]   size            The buffer size.
- * @param[in]   size_written    The pointer to save the number of written bytes.
+ * @param[in,out]   emitter         An emitter object.
+ * @param[in]       output          An output buffer.
+ * @param[in]       size            The buffer size.
+ * @param[in]       size_written    The pointer to save the number of written
+ *                                  bytes.
  */
 
 YAML_DECLARE(void)
@@ -1298,8 +1599,8 @@ yaml_emitter_set_output_string(yaml_emitter_t *emitter,
  * @a file should be a file object open for writing.  The application is
  * responsible for closing the @a file.
  *
- * @param[in]   emitter An emitter object.
- * @param[in]   file    An open file.
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       file        An open file.
  */
 
 YAML_DECLARE(void)
@@ -1308,9 +1609,10 @@ yaml_emitter_set_output_file(yaml_emitter_t *emitter, FILE *file);
 /**
  * Set a generic output handler.
  *
- * @param[in]   emitter An emitter object.
- * @param[in]   handler A write handler.
- * @param[in]   data    Any application data for passing to the write handler.
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       handler     A write handler.
+ * @param[in]       data        Any application data for passing to the write
+ *                              handler.
  */
 
 YAML_DECLARE(void)
@@ -1320,8 +1622,8 @@ yaml_emitter_set_output(yaml_emitter_t *emitter,
 /**
  * Set the output encoding.
  *
- * @param[in]   emitter     An emitter object.
- * @param[in]   encoding    The output encoding.
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       encoding    The output encoding.
  */
 
 YAML_DECLARE(void)
@@ -1331,8 +1633,8 @@ 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]   emitter     An emitter object.
- * @param[in]   canonical   If the output is canonical.
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       canonical   If the output is canonical.
  */
 
 YAML_DECLARE(void)
@@ -1341,8 +1643,8 @@ yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical);
 /**
  * Set the intendation increment.
  *
- * @param[in]   emitter     An emitter object.
- * @param[in]   indent      The indentation increment (1 < . < 10).
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       indent      The indentation increment (1 < . < 10).
  */
 
 YAML_DECLARE(void)
@@ -1351,8 +1653,8 @@ yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
 /**
  * Set the preferred line width. @c -1 means unlimited.
  *
- * @param[in]   emitter     An emitter object.
- * @param[in]   width       The preferred line width.
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       width       The preferred line width.
  */
 
 YAML_DECLARE(void)
@@ -1361,8 +1663,8 @@ yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
 /**
  * Set if unescaped non-ASCII characters are allowed.
  *
- * @param[in]   emitter     An emitter object.
- * @param[in]   unicode     If unescaped Unicode characters are allowed.
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       unicode     If unescaped Unicode characters are allowed.
  */
 
 YAML_DECLARE(void)
@@ -1371,8 +1673,8 @@ yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode);
 /**
  * Set the preferred line break.
  *
- * @param[in]   emitter     An emitter object.
- * @param[in]   line_break  The preferred line break.
+ * @param[in,out]   emitter     An emitter object.
+ * @param[in]       line_break  The preferred line break.
  */
 
 YAML_DECLARE(void)
@@ -1381,13 +1683,13 @@ yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
 /**
  * Emit an event.
  *
- * The event object may be generated using the @c yaml_parser_parse function.
+ * 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]   emitter     An emitter object.
- * @param[in]   event       An event object.
+ * @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.
  */
@@ -1398,7 +1700,7 @@ yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
 /**
  * Flush the accumulated characters to the output.
  *
- * @param[in]   emitter     An emitter object.
+ * @param[in,out]   emitter     An emitter object.
  *
  * @returns @c 1 if the function succeeded, @c 0 on error.
  */