More documentation fixes
diff --git a/doc/Tagging.md b/doc/Tagging.md
index 1f1b61a..acaa1f7 100644
--- a/doc/Tagging.md
+++ b/doc/Tagging.md
@@ -6,7 +6,7 @@
## New Types
CBOR allows for the definition of new data types beyond basic
-primitives like integers and strings. These new types can either be
+primitives like integers, strings, array and such. These new types can either be
simple extensions of a primitive type with additional semantics or
more complex structures involving large aggregations.
@@ -14,6 +14,9 @@
Tagging uses a simple unsigned integer to indicate that the following
CBOR item is a different type.
+For example, when an encoded integer is preceeded by the encoded
+tag number 1, the integer represents an epoch date.
+
It's important to note that CBOR uses the word "tag" in an unusual
way. In CBOR, a "tag" refers to the combination of the tag number and
the tag content. By the normal dictionary definition, a "tag" would
@@ -22,7 +25,7 @@
"tag" in CBOR terms would be the combination of the label (tag number)
and the elephant (tag content).
-QCBOR always uses the terms "tag number" to refer to the integer that
+QCBOR always uses the term "tag number" to refer to the integer that
identifies the type, "tag content" to refer to the target of the
indicating integer and "tag" as the full combination of both.
@@ -51,7 +54,7 @@
ignoring a typedef or struct in C.
However, it is common in CBOR-based protocols to use the format,
-semantics or definition of the tag content without it actually being a
+semantics and definition of the tag content without it actually being a
*tag*. One can think of this as *borrowing* the tag content or implied
type information.
@@ -89,28 +92,29 @@
Finally, every CBOR protocol should explicitly spell out how it is
using each tag, borrowing tag content and such. If the protocol you
are trying to implement doesn't, ask the designer. Generally,
-protocols designs should not allow for some data item to optional be
+protocols designs should not allow for some data item to be
either a tag or to be the borrowed tag content. While allowing this
tag optionality is a form of Postel's law, "be liberal in what you
accept", current wisdom is somewhat the opposite.
-## Types and Tags in QCBOR
+## QCBOR Tag APIs
-TODO: bring in AddTagNumber() and GetTagNumber()
+The encode APIs are in @ref inc/qcbor/qcbor_tag_encode.h "qcbor_tag_encode.h"
+and decoding APIs in @ref inc/qcbor/qcbor_tag_decode.h "qcbor_tag_decode.h"
-QCBOR explicitly supports all the tags standardized in
-[RFC 8949](https://tools.ietf.org/html/rfc8949) for dates, big numbers and
-such. It has specific APIs and data structures for encoding and
-decoding them.
+The base primitives for encoding and decoding tag numbers are
+QCBOREncode_AddTagNumber() and QCBORDecode_VGetNextTagNumber(). These
+are used in constructing and decoding tags. Note that for decoding,
+all tag numbers have to be consumed before decoding the tag
+content. This is different from QCBOR v1 where tag numbers did not
+have to be explicitly consumed.
-The encode APIs are in @ref inc/qcbor/qcbor_encode_tag.h "qcbor_encode_tag.h".
-Their names start with
-"QCBOREncode_AddT". Decoding can be done by installing the provided
-callbacks, @ref QCBORDecode_TagDecoderTablev1, in which case they get
-decoded by QCBORDecode_VGetNext() and appear in a @ref
-QCBORItem. Alternative spiffy decode style functions from
-@ref inc/qcbor/qcbor_decode_tag.h "qcbor_decode_tag.h" can be called.
+QCBOR also provides APIs for directly encoding and decoding all the
+tags standardized in [RFC 8949](https://tools.ietf.org/html/rfc8949)
+for dates, big numbers and such. For encoding their names start with
+"QCBOREncode_AddT" and for decoding they start with "QCBOREncode_Get"
+(TODO: fix this). These APIs can handle
These APIs and structures support both the full tag form and the
borrowed content form that is not a tag. An argument of type @ref xxx
@@ -118,27 +122,22 @@
and decode functions to distinguish between full tags and borrowed
content.
-Early versions of QCBOR did not support encoding borrowed content. The
+Early versions of QCBOR do not support encoding borrowed content. The
old APIs for dates, big numbers and such are listed as deprecated, but
will continue to be supported. The encode side has functions like
QCBOREncode_AddDateEpoch() rather than
QCBOREncode_AddTDateEpoch(). The tag decode APIs always supported
borrowed content.
-When decoding with QCBORDecode_GetNext(), the non-spiffy decode API,
-the proper tag form is automatically recognized by the tag number and
-decoded into @ref QCBORItem. This decoding API however cannot recognize
-borrowed content format. The caller must tell QCBOR when borrowed
-content format is expected.
+Last, QCBORDecode_InstallTagDecoders() allows callbacks to be
+installed that will fire on a particular tag number. These callbacks
+decode the tag content and put it into a QCBORItem with a new QCBOR
+data type. The decoded tags show up as a @ref QCBORItem fetched by
+QCBORDecode_VGetNext().
-The spiffy decode APIs for the particular tags are the way the caller
-tells QCBOR to expect borrowed content format. These spiffy decode
-APIs can also decode the proper tag as well. When asked to decode a
-proper tag and the input CBOR is not, it is a decode validity
-error. These APIs take an argument which says whether to expect the
-proper tag or just the borrowed content. They can also be told to
-allow either to "be liberal in what you accept", but this is not
-recommended.
+A set of callbacks called @ref QCBORDecode_TagDecoderTablev1 is
+provided for all the standard tags from RFC 8949. These are not
+automatically installed in QCBOR v2. These were built into QCBOR v1.
## Nested Tags
@@ -147,8 +146,9 @@
encloses another, the enclosed tag is the content for the enclosing
tag.
-Encoding nested tags is easy with QCBOREncode_AddTagNumber(). Just call it
-several times before calling the functions to encode the tag content.
+Encoding nested tags is easy with QCBOREncode_AddTagNumber(). Just
+call it several times before calling the functions to encode the tag
+content.
When QCBOR decodes tags it does so by first completely processing the
built-in tags that it knows how to process. It returns that processed
@@ -261,9 +261,3 @@
As described above, it is common to use data types from the registry
in a CBOR protocol without the explicit tag, to borrow the content, so
in a way the IANA registry is a registry of data types.
-
-
-## See Also
-
-See @ref Tags-Overview and @ref Tag-Usage.
-
diff --git a/inc/qcbor/qcbor_main_decode.h b/inc/qcbor/qcbor_main_decode.h
index bb0bd61..3bb5756 100644
--- a/inc/qcbor/qcbor_main_decode.h
+++ b/inc/qcbor/qcbor_main_decode.h
@@ -681,7 +681,7 @@
/**
* PRIVATE MEMBER
* Use QCBORDecode_GetNthTagNumber() to retrieve tag numbers on an item.
- * Also see @ref Tags-Overview.
+ * Also see @ref CBORTags
*
* In QCBOR v1 this was named uTags and was in the reverse order.
* It wasn't explicitly described as private, but was implicitly private.
@@ -909,8 +909,8 @@
*
* - @c uDataType which indicates which member of the @c val union the
* data is in. This decoder figures out the type based on the CBOR
- * major type, the CBOR "additionalInfo", the CBOR optional tags and
- * the value of the integer.
+ * major type, the CBOR "additionalInfo", and sometimes by
+ * preceding tag numbers.
*
* - The value of the item, which might be an integer, a pointer and a
* length, the count of items in an array, a floating-point number or
@@ -921,7 +921,7 @@
* - The label for an item in a map, which may be a text or byte string
* or an integer.
*
- * - The unprocessed tag numbers for which the item is the tag content.
+ * - When @ref QCBOR_DECODE_ALLOW_UNPROCESSED_TAG_NUMBERS is set, unprocessed tag numbers.
*
* See @ref QCBORItem for all the details about what is returned.
*
@@ -987,8 +987,6 @@
* array. For indefinite-length arrays, @c QCBORItem.val.uCount
* is @c UINT16_MAX.
*
- * See extensive discussion in @ref Tag-Decoding.
- *
* See [Decode Error Overview](#Decode-Errors-Overview).
*
* If a decoding error occurs or previously occured, @c uDataType and
diff --git a/inc/qcbor/qcbor_number_decode.h b/inc/qcbor/qcbor_number_decode.h
index 7031bfd..5ea7597 100644
--- a/inc/qcbor/qcbor_number_decode.h
+++ b/inc/qcbor/qcbor_number_decode.h
@@ -651,7 +651,7 @@
*
* Please see @ref Decode-Errors-Overview "Decode Errors Overview".
*
- * See @ref Tag-Usage for discussion on tag requirements.
+ * See @ref QCBORDecodeTagReq for discussion on tag requirements.
*/
void
QCBORDecode_GetTBigNumber(QCBORDecodeContext *pCtx,
@@ -811,7 +811,7 @@
*
* Depending on @c uTagRequirement, the tag number
* @ref CBOR_TAG_DECIMAL_FRACTION (4) may or may not need to be
- * present before the array. See @ref Tag-Usage.
+ * present before the array. See @ref QCBORDecodeTagReq.
*
* The exponent must always be an integer (CBOR type 0 or 1). The
* mantissa may be an integer or a big number. If it is a big number,
@@ -998,7 +998,7 @@
*
* Depending on @c uTagRequirement, the tag number
* @ref CBOR_TAG_BIGFLOAT (5) may or may not need to be present
- * before the array. See @ref Tag-Usage.
+ * before the array. See @ref QCBORDecodeTagReq.
*
* The exponent must always be an integer (CBOR type 0 or 1). The
* mantissa may be an integer or a big number. If it is a big number,
diff --git a/inc/qcbor/qcbor_spiffy_decode.h b/inc/qcbor/qcbor_spiffy_decode.h
index 90dd898..f79c256 100644
--- a/inc/qcbor/qcbor_spiffy_decode.h
+++ b/inc/qcbor/qcbor_spiffy_decode.h
@@ -601,7 +601,7 @@
* every pItemList.auTagNumbers is empty or has tag numbers that are
* expected. While tag numbers were once described as "optional",
* they really do have critical information that should not be ignored.
- * See @ref Tag-Decoding
+ * See @ref TagDecoding
*
* This function works well with tag content decoders as described in
* QCBORDecode_InstallTagDecoders().
diff --git a/inc/qcbor/qcbor_tag_decode.h b/inc/qcbor/qcbor_tag_decode.h
index 83c6b74..b6b5dce 100644
--- a/inc/qcbor/qcbor_tag_decode.h
+++ b/inc/qcbor/qcbor_tag_decode.h
@@ -287,7 +287,7 @@
* the constant can be increased and the library recompiled. It will
* use more memory).
*
- * See also @ref Tag-Decoding @ref CBORTags, @ref Tag-Usage and @ref Tags-Overview.
+ * See also @ref TagDecoding @ref CBORTags.
*
* To reduce memory used by a @ref QCBORItem, tag numbers larger than
* @c UINT16_MAX are mapped so the tag numbers in @c uTags should be
@@ -342,7 +342,7 @@
* and 63 a CBOR sequence. This implementation doesn't distinguish
* between the two (it would be more code and doesn't seem important).
*
- * The @ref Tag-Usage discussion on the tag requirement applies here
+ * The @ref QCBORDecodeTagReq discussion on the tag requirement applies here
* just the same as any other tag.
*
* In other cases, CBOR is wrapped in a byte string, but it is
diff --git a/inc/qcbor/qcbor_tag_encode.h b/inc/qcbor/qcbor_tag_encode.h
index efec90d..f69ff16 100644
--- a/inc/qcbor/qcbor_tag_encode.h
+++ b/inc/qcbor/qcbor_tag_encode.h
@@ -112,14 +112,13 @@
/**
- * Output the full CBOR tag. See @ref CBORTags, @ref Tag-Usage and
- * @ref Tags-Overview.
+ * Output the full CBOR tag. See @ref CBORTags.
*/
#define QCBOR_ENCODE_AS_TAG 0
/**
* Output only the 'borrowed' content format for the relevant tag.
- * See @ref CBORTags, @ref Tag-Usage and @ref Tags-Overview.
+ * See @ref CBORTags..
*/
#define QCBOR_ENCODE_AS_BORROWED 1
@@ -132,7 +131,7 @@
* @param[in] uTagNumber The tag number to add.
*
* This outputs a CBOR major type 6 item, a tag number that indicates
- * the next item is a different type. See @ref Tags-Overview.
+ * the next item is a different type. See @ref TagEncoding.
*
* For many of the common standard tags, a function to encode data
* using it is provided and this is not needed. For example,
@@ -144,7 +143,7 @@
* major CBOR type. Any number of tag numbers can be added to a data
* item by calling this multiple times before the data item is added.
*
- * See also @ref TagDecoding.
+ * See also @ref TagEncoding.
*/
static void
QCBOREncode_AddTagNumber(QCBOREncodeContext *pCtx, uint64_t uTagNumber);