Merge pull request #267 from PJK/fix-docs

Fix doxygen warnings, fix expansion of _CBOR_NODISCARD, improve doc strings

.circleci/config.yml

@@ -48,6 +48,11 @@ jobs:
             echo "Excerpt of the diff follows"
             git diff | head -n 20
           fi
+      - run: >
+          if doxygen Doxyfile | grep 'warning: '; then
+            echo "Doxygen warning (see above) -- misformatted docs?"
+            exit 1
+          fi
       - run: >
           cd doc &&
           pip3 install -r source/requirements.txt &&

src/cbor.h

@@ -39,19 +39,25 @@ extern "C" {
  *
  * @param source The buffer
  * @param source_size
- * @param result[out] Result indicator. #CBOR_ERR_NONE on success
- * @return **new** CBOR item or `NULL` on failure. In that case, \p result
- * contains location and description of the error.
+ * @param[out] result Result indicator. #CBOR_ERR_NONE on success
+ * @return Decoded CBOR item. The item's reference count is initialized to one.
+ * @return `NULL` on failure. In that case, \p result contains the location and
+ * description of the error.
  */
 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t* cbor_load(
     cbor_data source, size_t source_size, struct cbor_load_result* result);
 
 /** Take a deep copy of an item
  *
- * All the reference counts in the new structure are set to one.
+ * All items this item points to (array and map members, string chunks, tagged
+ * items) will be copied recursively using #cbor_copy. The new item doesn't
+ * alias or point to any items from the original \p item. All the reference
+ * counts in the new structure are set to one.
  *
- * @param item[borrow] item to copy
- * @return **new** CBOR deep copy or `NULL` on failure.
+ * @param item item to copy
+ * @return Reference to the new item. The item's reference count is initialized
+ * to one.
+ * @return `NULL` if memory allocation fails
  */
 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t* cbor_copy(cbor_item_t* item);
 

src/cbor/arrays.h

@@ -17,25 +17,28 @@ extern "C" {
 
 /** Get the number of members
  *
- * @param item[borrow] An array
+ * @param item An array
  * @return The number of members
  */
 _CBOR_NODISCARD
 CBOR_EXPORT size_t cbor_array_size(const cbor_item_t* item);
 
 /** Get the size of the allocated storage
  *
- * @param item[borrow] An array
+ * @param item An array
  * @return The size of the allocated storage (number of items)
  */
 _CBOR_NODISCARD
 CBOR_EXPORT size_t cbor_array_allocated(const cbor_item_t* item);
 
 /** Get item by index
  *
- * @param item[borrow] An array
- * @param index The index
- * @return **incref** The item, or `NULL` in case of boundary violation
+ * @param item An array
+ * @param index The index (zero-based)
+ * @return Reference to the item, or `NULL` in case of boundary violation.
+ *
+ * Increases the reference count of the underlying item. The returned reference
+ * must be released using #cbor_decref.
  */
 _CBOR_NODISCARD
 CBOR_EXPORT cbor_item_t* cbor_array_get(const cbor_item_t* item, size_t index);
@@ -45,22 +48,23 @@ CBOR_EXPORT cbor_item_t* cbor_array_get(const cbor_item_t* item, size_t index);
  * If the index is out of bounds, the array is not modified and false is
  * returned. Creating arrays with holes is not possible.
  *
- * @param item[borrow] An array
- * @param value[incref] The item to assign
- * @param index The index, first item is 0.
- * @return true on success, false on allocation failure.
+ * @param item An array
+ * @param value The item to assign
+ * @param index The index (zero-based)
+ * @return `true` on success, `false` on allocation failure.
  */
 _CBOR_NODISCARD
 CBOR_EXPORT bool cbor_array_set(cbor_item_t* item, size_t index,
                                 cbor_item_t* value);
 
 /** Replace item at an index
  *
- * The item being replace will be #cbor_decref 'ed.
+ * The reference to the item being replaced will be released using #cbor_decref.
  *
- * @param item[borrow] An array
- * @param value[incref] The item to assign
- * @param index The index, first item is 0.
+ * @param item An array
+ * @param value The item to assign. Its reference count will be increased by
+ * one.
+ * @param index The index (zero-based)
  * @return true on success, false on allocation failure.
  */
 _CBOR_NODISCARD
@@ -69,15 +73,15 @@ CBOR_EXPORT bool cbor_array_replace(cbor_item_t* item, size_t index,
 
 /** Is the array definite?
  *
- * @param item[borrow] An array
+ * @param item An array
  * @return Is the array definite?
  */
 _CBOR_NODISCARD
 CBOR_EXPORT bool cbor_array_is_definite(const cbor_item_t* item);
 
 /** Is the array indefinite?
  *
- * @param item[borrow] An array
+ * @param item An array
  * @return Is the array indefinite?
  */
 _CBOR_NODISCARD
@@ -88,23 +92,27 @@ CBOR_EXPORT bool cbor_array_is_indefinite(const cbor_item_t* item);
  * The items may be reordered and modified as long as references remain
  * consistent.
  *
- * @param item[borrow] An array
- * @return #cbor_array_size items
+ * @param item An array item
+ * @return An array of #cbor_item_t pointers of size #cbor_array_size.
  */
 _CBOR_NODISCARD
 CBOR_EXPORT cbor_item_t** cbor_array_handle(const cbor_item_t* item);
 
 /** Create new definite array
  *
  * @param size Number of slots to preallocate
- * @return **new** array or `NULL` upon malloc failure
+ * @return Reference to the new array item. The item's reference count is
+ * initialized to one.
+ * @return `NULL` if memory allocation fails
  */
 _CBOR_NODISCARD
 CBOR_EXPORT cbor_item_t* cbor_new_definite_array(size_t size);
 
 /** Create new indefinite array
  *
- * @return **new** array or `NULL` upon malloc failure
+ * @return Reference to the new array item. The item's reference count is
+ * initialized to one.
+ * @return `NULL` if memory allocation fails
  */
 _CBOR_NODISCARD
 CBOR_EXPORT cbor_item_t* cbor_new_indefinite_array(void);
@@ -114,9 +122,10 @@ CBOR_EXPORT cbor_item_t* cbor_new_indefinite_array(void);
  * For indefinite items, storage may be reallocated. For definite items, only
  * the preallocated capacity is available.
  *
- * @param array[borrow] An array
- * @param pushee[incref] The item to push
- * @return true on success, false on failure
+ * @param array An array
+ * @param pushee The item to push. Its reference count will be increased by
+ * one.
+ * @return `true` on success, `false` on failure
  */
 _CBOR_NODISCARD
 CBOR_EXPORT bool cbor_array_push(cbor_item_t* array, cbor_item_t* pushee);

src/cbor/bytestrings.h

@@ -25,23 +25,23 @@ extern "C" {
  *
  * For definite byte strings only
  *
- * @param item[borrow] a definite bytestring
+ * @param item a definite bytestring
  * @return length of the binary data. Zero if no chunk has been attached yet
  */
 _CBOR_NODISCARD
 CBOR_EXPORT size_t cbor_bytestring_length(const cbor_item_t *item);
 
 /** Is the byte string definite?
  *
- * @param item[borrow] a byte string
+ * @param item a byte string
  * @return Is the byte string definite?
  */
 _CBOR_NODISCARD
 CBOR_EXPORT bool cbor_bytestring_is_definite(const cbor_item_t *item);
 
 /** Is the byte string indefinite?
  *
- * @param item[borrow] a byte string
+ * @param item a byte string
  * @return Is the byte string indefinite?
  */
 _CBOR_NODISCARD
@@ -52,18 +52,20 @@ CBOR_EXPORT bool cbor_bytestring_is_indefinite(const cbor_item_t *item);
  * Definite items only. Modifying the data is allowed. In that case, the caller
  * takes responsibility for the effect on items this item might be a part of
  *
- * @param item[borrow] A definite byte string
- * @return The address of the binary data. `NULL` if no data have been assigned
+ * @param item A definite byte string
+ * @return The address of the underlying binary data
+ * @return `NULL` if no data have been assigned
  * yet.
  */
 _CBOR_NODISCARD
 CBOR_EXPORT cbor_mutable_data cbor_bytestring_handle(const cbor_item_t *item);
 
 /** Set the handle to the binary data
  *
- * @param item[borrow] A definite byte string
+ * @param item A definite byte string
  * @param data The memory block. The caller gives up the ownership of the block.
- * libcbor will deallocate it when appropriate using its free function
+ * libcbor will deallocate it when appropriate using the `free` implementation
+ * configured using #cbor_set_allocs
  * @param length Length of the data block
  */
 CBOR_EXPORT void cbor_bytestring_set_handle(
@@ -75,7 +77,7 @@ CBOR_EXPORT void cbor_bytestring_set_handle(
  * Manipulations with the memory block (e.g. sorting it) are allowed, but the
  * validity and the number of chunks must be retained.
  *
- * @param item[borrow] A indefinite byte string
+ * @param item A indefinite byte string
  * @return array of #cbor_bytestring_chunk_count definite bytestrings
  */
 _CBOR_NODISCARD
@@ -84,7 +86,7 @@ CBOR_EXPORT cbor_item_t **cbor_bytestring_chunks_handle(
 
 /** Get the number of chunks this string consist of
  *
- * @param item[borrow] A indefinite bytestring
+ * @param item A indefinite bytestring
  * @return The chunk count. 0 for freshly created items.
  */
 _CBOR_NODISCARD
@@ -96,8 +98,9 @@ CBOR_EXPORT size_t cbor_bytestring_chunk_count(const cbor_item_t *item);
  *
  * May realloc the chunk storage.
  *
- * @param item[borrow] An indefinite byte string
- * @param item[incref] A definite byte string
+ * @param item An indefinite byte string
+ * @param chunk A definite byte string. Its reference count will be be increased
+ * by one.
  * @return true on success, false on realloc failure. In that case, the refcount
  * of `chunk` is not increased and the `item` is left intact.
  */
@@ -109,7 +112,9 @@ CBOR_EXPORT bool cbor_bytestring_add_chunk(cbor_item_t *item,
  *
  * The handle is initialized to `NULL` and length to 0
  *
- * @return **new** definite bytestring. `NULL` on malloc failure.
+ * @return Reference to the new bytestring item. The item's reference count is
+ * initialized to one.
+ * @return `NULL` if memory allocation fails
  */
 _CBOR_NODISCARD
 CBOR_EXPORT cbor_item_t *cbor_new_definite_bytestring(void);
@@ -118,7 +123,9 @@ CBOR_EXPORT cbor_item_t *cbor_new_definite_bytestring(void);
  *
  * The chunks array is initialized to `NULL` and chunk count to 0
  *
- * @return **new** indefinite bytestring. `NULL` on malloc failure.
+ * @return Reference to the new bytestring item. The item's reference count is
+ * initialized to one.
+ * @return `NULL` if memory allocation fails
  */
 _CBOR_NODISCARD
 CBOR_EXPORT cbor_item_t *cbor_new_indefinite_bytestring(void);
@@ -129,8 +136,9 @@ CBOR_EXPORT cbor_item_t *cbor_new_indefinite_bytestring(void);
  *
  * @param handle Block of binary data
  * @param length Length of `data`
- * @return A **new** byte string with content `handle`. `NULL` on malloc
- * failure.
+ * @return Reference to the new bytestring item. The item's reference count is
+ * initialized to one.
+ * @return `NULL` if memory allocation fails
  */
 _CBOR_NODISCARD
 CBOR_EXPORT cbor_item_t *cbor_build_bytestring(cbor_data handle, size_t length);