More documentation fixes

doc/Tagging.md

@@ -6,14 +6,17 @@
 ## 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.
 
 The mechanism for identifying these new types is called tagging.
 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 @@ By analogy, if you attach a small label to an elephant's ear, the
 "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 @@ indicate something is of a data type. Ignoring it would be like
 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,56 +92,52 @@ particular content format. A CWT is of the later sort.
 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
 and @ref QCBORDecodeTagReq is provided respectively to the tag encode
 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 @@ CBOR tags are an enclosing or encapsulating format. When one tag
 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 @@ accommodate this.
 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.
-

inc/qcbor/qcbor_main_decode.h

@@ -681,7 +681,7 @@ typedef struct _QCBORItem {
    /**
     * 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 @@ QCBORDecode_SetUpAllocator(QCBORDecodeContext *pCtx,
  *
  * - @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 @@ QCBORDecode_SetUpAllocator(QCBORDecodeContext *pCtx,
  * - 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 @@ QCBORDecode_SetUpAllocator(QCBORDecodeContext *pCtx,
  * 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

inc/qcbor/qcbor_number_decode.h

@@ -651,7 +651,7 @@ QCBORDecode_ProcessBigNumberNoPreferred(const QCBORItem Item,
  *
  * 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 @@ QCBORDecode_GetTBigNumberRawInMapSZ(QCBORDecodeContext    *pMe,
  *
  * 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 @@ QCBORDecode_GetTDecimalFractionBigMantissaRawInMapSZ(QCBORDecodeContext    *pCtx
  *
  * 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,

inc/qcbor/qcbor_spiffy_decode.h

@@ -601,7 +601,7 @@ QCBORDecode_GetItemInMapSZ(QCBORDecodeContext *pCtx,
  * 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().

inc/qcbor/qcbor_tag_decode.h

@@ -287,7 +287,7 @@ QCBORDecode_GetNextTagNumberInMapSZ(QCBORDecodeContext *pCtx, const char *szLabe
  * 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 @@ QCBORDecode_GetNthTagNumberOfLast(QCBORDecodeContext *pCtx, uint8_t uIndex);
  * 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

inc/qcbor/qcbor_tag_encode.h

@@ -112,14 +112,13 @@ extern "C" {
 
 
 /**
- * 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 @@ extern "C" {
  * @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 @@ extern "C" {
  * 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);