WSHUB-458: cbor: Document the reader interface.

Author: sjlongland

src/cbor.h

@@ -317,11 +317,80 @@ enum CborParserIteratorFlags
 };
 
 struct CborValue;
+
+/**
+ * Defines an interface for abstract document readers.  This structure is used
+ * in conjunction with \ref cbor_parser_init_reader to define how the various
+ * required operations are to be implemented.
+ */
 struct CborParserOperations
 {
+    /**
+     * Determines whether \a len bytes may be read from the reader.  This is
+     * called before \ref read_bytes and \ref transfer_bytes to ensure it is safe
+     * to read the requested number of bytes from the reader.
+     *
+     * \param   token   An opaque object passed to \ref cbor_parser_init_reader
+     *                  that may be used to pass context information between the
+     *                  \ref CborParserOperations methods.
+     *
+     * \param   len     The number of bytes sought.
+     *
+     * \retval  true    \a len bytes may be read from the reader.
+     * \retval  false   Insufficient data is available to be read at this time.
+     */
     bool (*can_read_bytes)(void *token, size_t len);
+
+    /**
+     * Reads \a len bytes from the reader starting at \a offset bytes from
+     * the current read position and copies them to \a dst.  The read pointer
+     * is *NOT* modified by this operation.
+     *
+     * \param   token   An opaque object passed to \ref cbor_parser_init_reader
+     *                  that may be used to pass context information between the
+     *                  \ref CborParserOperations methods.
+     *
+     * \param   dst     The buffer the read bytes will be copied to.
+     *
+     * \param   offset  The starting position for the read relative to the
+     *                  current read position.
+     *
+     * \param   len     The number of bytes sought.
+     */
     void *(*read_bytes)(void *token, void *dst, size_t offset, size_t len);
+
+    /**
+     * Skips past \a len bytes from the reader without reading them.  The read
+     * pointer is advanced in the process.
+     *
+     * \param   token   An opaque object passed to \ref cbor_parser_init_reader
+     *                  that may be used to pass context information between the
+     *                  \ref CborParserOperations methods.
+     *
+     * \param   len     The number of bytes skipped.
+     */
     void (*advance_bytes)(void *token, size_t len);
+
+    /**
+     * Overwrite the user-supplied pointer \a userptr with the address where the
+     * data indicated by \a offset is located, then advance the read pointer
+     * \a len bytes beyond that point.
+     *
+     * This routine is used for accessing strings embedded in CBOR documents
+     * (both text and binary strings).
+     *
+     * \param   token   An opaque object passed to \ref cbor_parser_init_reader
+     *                  that may be used to pass context information between the
+     *                  \ref CborParserOperations methods.
+     *
+     * \param   userptr The pointer that will be updated to reference the location
+     *                  of the data in the buffer.
+     *
+     * \param   offset  The starting position for the read relative to the
+     *                  current read position.
+     *
+     * \param   len     The number of bytes sought.
+     */
     CborError (*transfer_string)(void *token, const void **userptr, size_t offset, size_t len);
 };