more little fixes to documentation
diff --git a/inc/qcbor/UsefulBuf.h b/inc/qcbor/UsefulBuf.h
index 31a2868..990191a 100644
--- a/inc/qcbor/UsefulBuf.h
+++ b/inc/qcbor/UsefulBuf.h
@@ -172,7 +172,7 @@
  *
  * With these it is possible to write code that does little or no
  * direct pointer manipulation for copying and formatting data. For
- * example, the QCBOR encoder was written using these and has no less
+ * example, the QCBOR encoder was written using these and has less
  * pointer manipulation.
  *
  * While it is true that object code using these functions will be a
@@ -216,7 +216,7 @@
  * that has been filled in. The length is amount of valid data pointed
  * to.
  *
- * A commn use mode is to pass a @ref UsefulBuf to a function, the
+ * A common use mode is to pass a @ref UsefulBuf to a function, the
  * function puts some data in it, then the function returns a @ref
  * UsefulBufC refering to the data. The @ref UsefulBuf is a non-const
  * "in" parameter and the @ref UsefulBufC is a const "out" parameter
@@ -373,14 +373,15 @@
  *
  * @return A non-const @ref UsefulBuf struct.
  *
- * TODO: REWRITE THIS
- * It is better to avoid use of this. The intended convention for
- * UsefulBuf is to make an empty buffer, some memory, as a UsefulBuf,
- * fill it in, and then make it a UsefulBufC. In that convension this
- * function is not needed.
+ * Use of this is not necessary for the intended use mode of @ref
+ * UsefulBufC and @ref UsefulBuf.  In that mode, the @ref UsefulBuf is
+ * created to describe a buffer that has not had any data put in
+ * it. Then the data is put in it.  Then a @ref UsefulBufC is create
+ * to describe the part with the data in it. This goes from non-const
+ * to const, so this function is not needed.
  *
- * This is an explicit way to quiet compiler warnings from
- * -Wcast-qual.
+ * If the -Wcast-qual warning is enabled, this function can be used to
+ * avoid that warning.
  */
 static inline UsefulBuf UsefulBuf_Unconst(const UsefulBufC UBC);
 
@@ -504,7 +505,8 @@
  * @param[in] ptr       The source to copy from.
  * @param[in] uLen      Length of the source; amount to copy.
  *
- * @return 0 on success, 1 on failure.
+ * @return Filled in @ref UsefulBufC on success, @ref NULLUsefulBufC
+ *         on failure.
  *
  * This fails and returns @ref NULLUsefulBufC if @c uLen is greater
  * than @c pDest->len.
@@ -716,11 +718,11 @@
  *
  * There is no way to ever write off the end of that buffer when
  * calling the @c UsefulOutBuf_AddXxx() and
- * @ UsefulOutBuf_InsertXxx() functions.
+ * @c UsefulOutBuf_InsertXxx() functions.
  *
  * The functions to add data do not report success of failure. The
  * caller only needs to check for an error in the final call, either
- * UsefulOutBuf_OutUBuf( *) or UsefulOutBuf_CopyOut() to get the
+ * UsefulOutBuf_OutUBuf() or UsefulOutBuf_CopyOut() to get the
  * result. This makes the calling code cleaner.
  *
  * There is a utility function to get the error status anytime along
@@ -853,7 +855,7 @@
  *
  * @param[in] pUOutBuf  Pointer to the @ref UsefulOutBuf.
  *
- * @return 1 if output position is at start.
+ * @return 1 if output position is at start, 0 if not.
  */
 static inline int UsefulOutBuf_AtStart(UsefulOutBuf *pUOutBuf);
 
@@ -1159,7 +1161,7 @@
  * @return 0 if all OK, 1 on error.
  *
  * This returns the error status since a call to either
- * UsefulOutBuf_Reset() of UsefulOutBuf_Init().  Once a UsefulOutBuf
+ * UsefulOutBuf_Reset() of UsefulOutBuf_Init().  Once a @ref UsefulOutBuf
  * goes into the error state, it will stay until one of those
  * functions is called.
  *
@@ -1239,7 +1241,8 @@
  * @param[out] Dest     The destination buffer to copy into.
  *
  * @return Pointer and length of copied data or @c NULLUsefulBufC
- *         if it will not fit in the @c Dest buffer.
+ *         if it will not fit in the @c Dest buffer or the error
+ *         state was entered.
  *
  * This is the same as UsefulOutBuf_OutUBuf() except it copies the
  * data to @c Dest.
@@ -1251,24 +1254,27 @@
 
 /**
  * @ref UsefulInputBuf is the counterpart to @ref UsefulOutBuf. It is
- * for parsing data received.  Initialize it with the data
- * from the network. Then use the functions like UsefulInputBuf_GetBytes() to get data chunks of
- * various types. A position cursor is maintained internally.
+ * for parsing data received.  Initialize it with the data from the
+ * network. Then use the functions like UsefulInputBuf_GetBytes() to
+ * get data chunks of various types. A position cursor is maintained
+ * internally.
  *
  * As long as the functions here are used, there will never be any
- * reference off the end of the given buffer (except UsefulInputBuf_SetBufferLength()). This is true even if
- * they are called incorrectly, an attempt is made to seek off the end
- * of the buffer or such. This makes it easier to write safe and
- * correct code.  For example, the QCBOR decoder implementation is
- * safer and easier to review through its use of @ref UsefulInputBuf.
+ * reference off the end of the given buffer (except
+ * UsefulInputBuf_SetBufferLength()). This is true even if they are
+ * called incorrectly, an attempt is made to seek off the end of the
+ * buffer or such. This makes it easier to write safe and correct
+ * code.  For example, the QCBOR decoder implementation is safer and
+ * easier to review through its use of @ref UsefulInputBuf.
  *
  * @ref UsefulInputBuf maintains an internal error state.  The
  * intended use is fetching data chunks without any error checks until
- * the end.  If there was any error, such as an attempt to fetch data off the end,
- * the error state is entered and no further data will be returned. In the error state the @c
- * UsefulInputBuf_GetXxxx() functions return 0, or @c NULL or @ref
- * NULLUsefulBufC. As long as null is not dereferenced, the error
- * check can be put off until the end, simplifying the calling code.
+ * the end.  If there was any error, such as an attempt to fetch data
+ * off the end, the error state is entered and no further data will be
+ * returned. In the error state the @c UsefulInputBuf_GetXxxx()
+ * functions return 0, or @c NULL or @ref NULLUsefulBufC. As long as
+ * null is not dereferenced, the error check can be put off until the
+ * end, simplifying the calling code.
  *
  * The integer and float parsing expects network byte order (big
  * endian).  Network byte order is what is used by TCP/IP, CBOR and
@@ -1279,7 +1285,8 @@
  * code size a lot. The only non-inline code is
  * UsefulInputBuf_GetBytes().  It is less than 100 bytes so use of
  * @ref UsefulInputBuf doesn't add much code for all the messy
- * hard-to-get right issues with parsing binary protocols in C that it solves.
+ * hard-to-get right issues with parsing binary protocols in C that it
+ * solves.
  *
  * The parse context size is:
  *   - 64-bit machine: 16 + 8 + 2 + 1 (+ 5 bytes padding to align) = 32 bytes
@@ -1341,7 +1348,7 @@
  * @return Number of bytes unconsumed or 0 on error.
  *
  * Returns 0 if the cursor is invalid or corruption of the
- * UsefulInputBuf structure is detected.
+ * @ref UsefulInputBuf structure is detected.
  */
 static size_t UsefulInputBuf_BytesUnconsumed(UsefulInputBuf *pUInBuf);
 
@@ -1357,18 +1364,17 @@
 static int UsefulInputBuf_BytesAvailable(UsefulInputBuf *pUInBuf, size_t uLen);
 
 
-
 /**
  * @brief Convert a pointer to an offset with bounds checking.
  *
- * @param[in] pUInBuf  Pointer to the UsefulInputBuf.
+ * @param[in] pUInBuf  Pointer to the @ref UsefulInputBuf.
  * @param[in] p        Pointer to convert to offset.
  *
  * @return SIZE_MAX if @c p is out of range, the byte offset if not.
- * TODO: details for this?
-*/
+ */
 static inline size_t UsefulInputBuf_PointerToOffset(UsefulInputBuf *pUInBuf, const void *p);
 
+
 /**
  * @brief Get pointer to bytes out of the input buffer.
  *
@@ -1524,13 +1530,13 @@
  * UsefulInputBuf_Init().
  *
  * For many use cases, it is possible to only call this once after all
- * the UsefulInputBuf_GetXxxx() calls have been made.  This is
+ * the @c UsefulInputBuf_GetXxxx() calls have been made.  This is
  * possible if no reference to the data returned are needed before the
  * error state is checked.
  *
  * In some cases UsefulInputBuf_GetUsefulBuf() or
  * UsefulInputBuf_GetBytes() can stand in for this because they return
- * NULL if the error state has been entered. (The others can't stand
+ * @c NULL if the error state has been entered. (The others can't stand
  * in because they don't return a clearly distinct error value.)
  */
 static int UsefulInputBuf_GetError(UsefulInputBuf *pUInBuf);
@@ -1553,6 +1559,7 @@
  * @brief Alters the input buffer length (use with caution).
  *
  * @param[in] pUInBuf  Pointer to the @ref UsefulInputBuf.
+ * @param[in] uNewLen  The new length of the input buffer.
  *
  * This alters the internal remembered length of the input buffer set
  * when UsefulInputBuf_Init() was called.
@@ -1566,9 +1573,9 @@
  * UsefulInputBuf_GetBufferLength() was called before this, then the
  * original length can be restored with another call to this.
  *
- * This should be used with caution. It is the only @ref
- * UsefulInputBuf method that can violate the safety of input buffer
- * parsing.
+ * This should be used with caution. It is the only
+ * @ref UsefulInputBuf method that can violate the safety of input
+ * buffer parsing.
  */
 static void UsefulInputBuf_SetBufferLength(UsefulInputBuf *pUInBuf, size_t uNewLen);