Docs and comments updates

Many thanks to Edward Welbourne for pointing them all out.

Signed-off-by: Thiago Macieira <thiago.macieira@intel.com>

src/cbor.dox

@@ -80,7 +80,7 @@
  * \value CborArrayType             Type is a CBOR array
  * \value CborMapType               Type is a CBOR map (an associative container with key and value pairs)
  * \value CborTagType               Type is a CBOR tag (a 64-bit integer describing the item that follows, see CborKnownTags)
- * \value CborSimpleType            Type is one of CBOR Simple Types
+ * \value CborSimpleType            Type is one of the CBOR Simple Types
  * \value CborBooleanType           Type is a boolean (true or false)
  * \value CborNullType              Type encodes a null
  * \value CborUndefinedType         Type encodes an undefined value
@@ -105,7 +105,7 @@
  * \value CborExpectedBase64urlTag  Item is a CBOR byte string that is expected to be encoded as Base64Url
  * \value CborExpectedBase64Tag     Item is a CBOR byte string that is expected to be encoded as Base64
  * \value CborExpectedBase16Tag     Item is a CBOR byte string that is expected to be encoded as Base16 (also known as "hexdump")
- * \value CborUriTag                Item is a CBOR text string containing an URI (RFC 3986) or IRI (RFC 3987)
+ * \value CborUriTag                Item is a CBOR text string containing a URI (RFC 3986) or IRI (RFC 3987)
  * \value CborBase64urlTag          Item is a CBOR text string that was encoded as Base64Url
  * \value CborBase64Tag             Item is a CBOR text string that was encoded as Base64
  * \value CborRegularExpressionTag  Item is a CBOR text string containing a regular expression

src/cborencoder.c

@@ -83,7 +83,7 @@
  *      cbor_encoder_close_container(&encoder, &mapEncoder);
  * \endcode
  *
- * <h3 class="groupheader">Error checking and buffer size</h2>
+ * <h3 class="groupheader">Error checking and buffer size</h3>
  *
  * All functions operating on CborEncoder return a condition of type CborError.
  * If the encoding was successful, they return CborNoError. Some functions do
@@ -134,7 +134,7 @@
  *      return CborNoError;
  * \endcode
  *
- * Finally, the example below illustrates expands on the one above and also
+ * Finally, the example below expands on the one above and also
  * deals with dynamically growing the buffer if the initial allocation wasn't
  * big enough. Note the two places where the error checking was replaced with
  * an cbor_assertion, showing where the author assumes no error can occur.
@@ -332,7 +332,7 @@ CborError cbor_encode_uint(CborEncoder *encoder, uint64_t value)
  * Appends the negative 64-bit integer whose absolute value is \a
  * absolute_value to the CBOR stream provided by \a encoder.
  *
- * If the value \a absolute_value is zero, this function encodes -2^64 - 1.
+ * If the value \a absolute_value is zero, this function encodes -2^64.
  *
  * \sa cbor_encode_uint, cbor_encode_int
  */
@@ -507,13 +507,14 @@ CborError cbor_encoder_create_array(CborEncoder *encoder, CborEncoder *arrayEnco
  * with the same \a encoder and \a mapEncoder parameters.
  *
  * The number of pair of items inserted into the map must be exactly \a length
- * items, otherwise the stream is invalid. If the number of items is not known
+ * items, otherwise the stream is invalid. If the number is not known
  * when creating the map, the constant \ref CborIndefiniteLength may be passed as
  * length instead.
  *
  * \b{Implementation limitation:} TinyCBOR cannot encode more than SIZE_MAX/2
  * key-value pairs in the stream. If the length \a length is larger than this
- * value, this function returns error CborErrorDataTooLarge.
+ * value (and is not \ref CborIndefiniteLength), this function returns error
+ * CborErrorDataTooLarge.
  *
  * \sa cbor_encoder_create_array
  */
@@ -530,8 +531,8 @@ CborError cbor_encoder_create_map(CborEncoder *encoder, CborEncoder *mapEncoder,
  * same as were passed to cbor_encoder_create_array() or
  * cbor_encoder_create_map().
  *
- * Since version 0.5, this function verifies that the number of items (or pair
- * of items, in the case of a map) was correct. It is no longer needed to call
+ * Since version 0.5, this function verifies that the number of items (or pairs
+ * of items, in the case of a map) was correct. It is no longer necessary to call
  * cbor_encoder_close_container_checked() instead.
  *
  * \sa cbor_encoder_create_array(), cbor_encoder_create_map()

src/cborparser.c

@@ -61,15 +61,15 @@
  *     CborParser parser;
  *     CborValue value;
  *     int result;
- *     cbor_parser_init(buffer, len, 0, &buffer, &value);
+ *     cbor_parser_init(buffer, len, 0, &parser, &value);
  *     cbor_value_get_int(&value, &result);
  *     return result;
  * }
  * \endcode
  *
  * The code above does no error checking, which means it assumes the data comes
  * from a source trusted to send one properly-encoded integer. The following
- * example does the exact same operation, but includes error parsing and
+ * example does the exact same operation, but includes error checking and
  * returns 0 on parsing failure:
  *
  * \code
@@ -78,7 +78,7 @@
  *     CborParser parser;
  *     CborValue value;
  *     int result;
- *     if (cbor_parser_init(buffer, len, 0, &buffer, &value) != CborNoError)
+ *     if (cbor_parser_init(buffer, len, 0, &parser, &value) != CborNoError)
  *         return 0;
  *     if (!cbor_value_is_integer(&value) ||
  *             cbor_value_get_int(&value, &result) != CborNoError)
@@ -461,7 +461,7 @@ CborError cbor_value_validate_basic(const CborValue *it)
  * If the type is not of fixed size, this function has undefined behavior. Code
  * must be sure that the current type is one of the fixed-size types before
  * calling this function. This function is provided because it can guarantee
- * that runs in constant time (O(1)).
+ * that it runs in constant time (O(1)).
  *
  * If the caller is not able to determine whether the type is fixed or not, code
  * can use the cbor_value_advance() function instead.
@@ -746,7 +746,7 @@ CborError cbor_value_leave_container(CborValue *it, const CborValue *recursed)
  *
  * Note that this function does not do range-checking: integral values that do
  * not fit in a variable of type \c{int} are silently truncated to fit. Use
- * cbor_value_get_int_checked() that is not acceptable.
+ * cbor_value_get_int_checked() if that is not acceptable.
  *
  * \sa cbor_value_get_type(), cbor_value_is_valid(), cbor_value_is_integer()
  */
@@ -804,7 +804,7 @@ CborError cbor_value_leave_container(CborValue *it, const CborValue *recursed)
  * behavior is undefined, so checking with \ref cbor_value_get_type or with
  * \ref cbor_value_is_integer is recommended.
  *
- * Unlike cbor_value_get_int64(), this function performs a check to see if the
+ * Unlike \ref cbor_value_get_int64(), this function performs a check to see if the
  * stored integer fits in \a result without data loss. If the number is outside
  * the valid range for the data type, this function returns the recoverable
  * error CborErrorDataTooLarge. In that case, use either
@@ -843,7 +843,7 @@ CborError cbor_value_get_int64_checked(const CborValue *value, int64_t *result)
  * behavior is undefined, so checking with \ref cbor_value_get_type or with
  * \ref cbor_value_is_integer is recommended.
  *
- * Unlike cbor_value_get_int(), this function performs a check to see if the
+ * Unlike \ref cbor_value_get_int(), this function performs a check to see if the
  * stored integer fits in \a result without data loss. If the number is outside
  * the valid range for the data type, this function returns the recoverable
  * error CborErrorDataTooLarge. In that case, use one of the other integer
@@ -863,8 +863,8 @@ CborError cbor_value_get_int_checked(const CborValue *value, int *result)
      *
      * But we can convert from signed to unsigned without fault (paragraph 2).
      *
-     * The range for int is implementation-defined and int is not guaranteed use
-     * two's complement representation (int32_t is).
+     * The range for int is implementation-defined and int is not guaranteed to use
+     * two's complement representation (although int32_t is).
      */
 
     if (value->flags & CborIteratorFlag_NegativeInteger) {
@@ -1120,7 +1120,7 @@ static CborError iterate_string_chunks(const CborValue *value, char *buffer, siz
 /**
  * \fn CborError cbor_value_copy_text_string(const CborValue *value, char *buffer, size_t *buflen, CborValue *next)
  *
- * Copies the string pointed by \a value into the buffer provided at \a buffer
+ * Copies the string pointed to by \a value into the buffer provided at \a buffer
  * of \a buflen bytes. If \a buffer is a NULL pointer, this function will not
  * copy anything and will only update the \a next value.
  *
@@ -1136,7 +1136,10 @@ static CborError iterate_string_chunks(const CborValue *value, char *buffer, siz
  * On success, this function sets the number of bytes copied to \c{*buflen}. If
  * the buffer is large enough, this function will insert a null byte after the
  * last copied byte, to facilitate manipulation of text strings. That byte is
- * not included in the returned value of \c{*buflen}.
+ * not included in the returned value of \c{*buflen}. If there was no space for
+ * the terminating null, no error is returned, so callers must check the value
+ * of *buflen after the call, before relying on the '\0'; if it has not been
+ * changed by the call, there is no '\0'-termination on the buffer's contents.
  *
  * The \a next pointer, if not null, will be updated to point to the next item
  * after this string. If \a value points to the last item, then \a next will be
@@ -1193,12 +1196,12 @@ CborError _cbor_value_copy_string(const CborValue *value, void *buffer,
 }
 
 /**
- * Compares the entry \a value with the string \a string and store the result
+ * Compares the entry \a value with the string \a string and stores the result
  * in \a result. If the value is different from \a string \a result will
  * contain \c false.
  *
- * The entry at \a value may be a tagged string. If \a is not a string or a
- * tagged string, the comparison result will be false.
+ * The entry at \a value may be a tagged string. If \a value is not a string or
+ * a tagged string, the comparison result will be false.
  *
  * CBOR requires text strings to be encoded in UTF-8, but this function does
  * not validate either the strings in the stream or the string \a string to be

src/cborparser_dup_string.c

@@ -41,7 +41,7 @@
  *
  * Allocates memory for the string pointed by \a value and copies it into this
  * buffer. The pointer to the buffer is stored in \a buffer and the number of
- * bytes copied is stored in \a len (those variables must not be NULL).
+ * bytes copied is stored in \a buflen (those variables must not be NULL).
  *
  * If the iterator \a value does not point to a text string, the behaviour is
  * undefined, so checking with \ref cbor_value_get_type or \ref
@@ -72,7 +72,7 @@
  *
  * Allocates memory for the string pointed by \a value and copies it into this
  * buffer. The pointer to the buffer is stored in \a buffer and the number of
- * bytes copied is stored in \a len (those variables must not be NULL).
+ * bytes copied is stored in \a buflen (those variables must not be NULL).
  *
  * If the iterator \a value does not point to a byte string, the behaviour is
  * undefined, so checking with \ref cbor_value_get_type or \ref

src/cborpretty.c

@@ -42,7 +42,7 @@
  * \defgroup CborPretty Converting CBOR to text
  * \brief Group of functions used to convert CBOR to text form.
  *
- * This group contains two functions that are can be used to convert one
+ * This group contains two functions that can be used to convert a \ref
  * CborValue object to a text representation. This module attempts to follow
  * the recommendations from RFC 7049 section 6 "Diagnostic Notation", though it
  * has a few differences. They are noted below.
@@ -58,13 +58,13 @@
  * error CborErrorIO.
  *
  * These functions also perform UTF-8 validation in CBOR text strings. If they
- * encounter a sequence of bytes that not permitted in UTF-8, they will return
+ * encounter a sequence of bytes that is not permitted in UTF-8, they will return
  * CborErrorInvalidUtf8TextString. That includes encoding of surrogate points
  * in UTF-8.
  *
  * \warning The output type produced by these functions is not guaranteed to
  * remain stable. A future update of TinyCBOR may produce different output for
- * the same input and parsers may be unable to handle them.
+ * the same input and parsers may be unable to handle it.
  *
  * \sa CborParsing, CborToJson, cbor_parser_init()
  */
@@ -102,7 +102,7 @@
  *      By default, float values are suffixed by "f" and half-float values suffixed by "f16" (doubles have no suffix).
  *      If the CborPrettyNumericEncodingIndicators flag is active, the values instead are encoded following the
  *      Section 6 recommended encoding indicators: float values are suffixed with "_2" and half-float with "_1".
- *      A dot is always present.
+ *      A decimal point is always present.
  * \par Arrays:
  *      Comma-separated list of elements, enclosed in square brackets ("[" and "]").
  * \par Maps:
@@ -139,11 +139,11 @@
  *
  * \value CborPrettyNumericEncodingIndicators   Use numeric encoding indicators instead of textual for float and half-float.
  * \value CborPrettyTextualEncodingIndicators   Use textual encoding indicators for float ("f") and half-float ("f16").
- * \value CborPrettyIndicateIndeterminateLength Indicate when a map or array has indeterminate length.
+ * \value CborPrettyIndicateIndeterminateLength (default) Indicate when a map or array has indeterminate length.
  * \value CborPrettyIndicateOverlongNumbers     Indicate when a number or length was encoded with more bytes than needed.
  * \value CborPrettyShowStringFragments         If the byte or text string is transmitted in chunks, show each individually.
  * \value CborPrettyMergeStringFragment         Merge all chunked byte or text strings and display them in a single entry.
- * \value CborPrettyDefaultFlags       Default conversion flags.
+ * \value CborPrettyDefaultFlags                Default conversion flags.
  */
 
 static void printRecursionLimit(CborStreamFunction stream, void *out)
@@ -507,14 +507,15 @@ static CborError value_to_pretty(CborStreamFunction stream, void *out, CborValue
  * Converts the current CBOR type pointed by \a value to its textual
  * representation and writes it to the stream by calling the \a streamFunction.
  * If an error occurs, this function returns an error code similar to
- * CborParsing.
+ * \ref CborParsing.
  *
  * The textual representation can be controlled by the \a flags parameter (see
- * CborPrettyFlags for more information).
+ * \ref CborPrettyFlags for more information).
  *
  * If no error ocurred, this function advances \a value to the next element.
  * Often, concatenating the text representation of multiple elements can be
- * done by appending a comma to the output stream.
+ * done by appending a comma to the output stream in between calls to this
+ * function.
  *
  * The \a streamFunction function will be called with the \a token value as the
  * first parameter and a printf-style format string as the second, with a variable

src/cborpretty_stdio.c

@@ -41,21 +41,22 @@ static CborError cbor_fprintf(void *out, const char *fmt, ...)
 /**
  * \fn CborError cbor_value_to_pretty(FILE *out, const CborValue *value)
  *
- * Converts the current CBOR type pointed by \a value to its textual
+ * Converts the current CBOR type pointed to by \a value to its textual
  * representation and writes it to the \a out stream. If an error occurs, this
  * function returns an error code similar to CborParsing.
  *
  * \sa cbor_value_to_pretty_advance(), cbor_value_to_json_advance()
  */
 
 /**
- * Converts the current CBOR type pointed by \a value to its textual
+ * Converts the current CBOR type pointed to by \a value to its textual
  * representation and writes it to the \a out stream. If an error occurs, this
  * function returns an error code similar to CborParsing.
  *
  * If no error ocurred, this function advances \a value to the next element.
  * Often, concatenating the text representation of multiple elements can be
- * done by appending a comma to the output stream.
+ * done by appending a comma to the output stream in between calls to this
+ * function.
  *
  * \sa cbor_value_to_pretty(), cbor_value_to_pretty_stream(), cbor_value_to_json_advance()
  */
@@ -65,7 +66,7 @@ CborError cbor_value_to_pretty_advance(FILE *out, CborValue *value)
 }
 
 /**
- * Converts the current CBOR type pointed by \a value to its textual
+ * Converts the current CBOR type pointed to by \a value to its textual
  * representation and writes it to the \a out stream. If an error occurs, this
  * function returns an error code similar to CborParsing.
  *
@@ -74,7 +75,8 @@ CborError cbor_value_to_pretty_advance(FILE *out, CborValue *value)
  *
  * If no error ocurred, this function advances \a value to the next element.
  * Often, concatenating the text representation of multiple elements can be
- * done by appending a comma to the output stream.
+ * done by appending a comma to the output stream in between calls to this
+ * function.
  *
  * \sa cbor_value_to_pretty_stream(), cbor_value_to_pretty(), cbor_value_to_json_advance()
  */