Merge pull request #159 from PJK/pk/man

Fix manpage generator warnings

CHANGELOG.md

@@ -6,6 +6,7 @@ Next
 - BREAKING: [`CBOR_DECODER_EBUFFER` removed from `cbor_decoder_status`](https://github.com/PJK/libcbor/pull/156)
     - `cbor_stream_decode` will set `CBOR_DECODER_NEDATA` instead if the input buffer is empty
 - [Fix `cbor_stream_decode`](https://github.com/PJK/libcbor/pull/156) to set `cbor_decoder_result.required` to the minimum number of input bytes necessary to receive the next callback (as long as at least one byte was passed) (discovered by [woefulwabbit](https://github.com/woefulwabbit))
+- Fixed several minor manpage issues [[#159]](https://github.com/PJK/libcbor/pull/159) (discovered by [kloczek@](https://github.com/kloczek))
 
 0.7.0 (2020-04-25)
 ---------------------

Doxyfile

@@ -2029,7 +2029,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = CBOR_CUSTOM_ALLOC CBOR_RESTRICT_POINTER=
+PREDEFINED             = CBOR_CUSTOM_ALLOC CBOR_RESTRICT_POINTER= CBOR_EXPORT
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

doc/source/conf.py

@@ -257,7 +257,7 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('index', 'libcbor', 'libcbor Documentation',
-     ['Pavel Kalvoda'], 1)
+     ['Pavel Kalvoda'], 3)
 ]
 
 # If true, show URL addresses after external links.

src/cbor/common.h

@@ -98,12 +98,14 @@ CBOR_EXPORT extern _cbor_free_t _cbor_free;
  *
  * \rst
  * .. warning:: This function modifies the global state and should therefore be
- * used accordingly. Changing the memory handlers while allocated items exist
- * will result in a ``free``/``malloc`` mismatch. This function is not thread
- * safe with respect to both itself and all the other *libcbor* functions that
- * work with the heap.
+ *  used accordingly. Changing the memory handlers while allocated items exist
+ *  will result in a ``free``/``malloc`` mismatch. This function is not thread
+ *  safe with respect to both itself and all the other *libcbor* functions that
+ *  work with the heap.
+ *
  * .. note:: `realloc` implementation must correctly support `NULL` reallocation
- * (see e.g. http://en.cppreference.com/w/c/memory/realloc) \endrst
+ *  (see e.g. http://en.cppreference.com/w/c/memory/realloc)
+ * \endrst
  *
  * @param custom_malloc malloc implementation
  * @param custom_realloc realloc implementation
@@ -210,18 +212,24 @@ CBOR_EXPORT bool cbor_is_float(const cbor_item_t *item);
 CBOR_EXPORT bool cbor_is_bool(const cbor_item_t *item);
 
 /** Does this item represent `null`
+ *
  * \rst
  * .. warning:: This is in no way related to the value of the pointer. Passing a
- * null pointer will most likely result in a crash. \endrst
+ *  null pointer will most likely result in a crash.
+ * \endrst
+ *
  * @param item[borrow] the item
  * @return  Is the item (CBOR logical) null?
  */
 CBOR_EXPORT bool cbor_is_null(const cbor_item_t *item);
 
 /** Does this item represent `undefined`
+ *
  * \rst
  * .. warning:: Care must be taken to distinguish nulls and undefined values in
- * C. \endrst
+ *  C.
+ * \endrst
+ *
  * @param item[borrow] the item
  * @return Is the item (CBOR logical) undefined?
  */
@@ -280,7 +288,8 @@ CBOR_EXPORT size_t cbor_refcount(const cbor_item_t *item);
  *
  * \rst
  * .. warning:: If the item is moved without correctly increasing the reference
- * count afterwards, the memory will be leaked. \endrst
+ *  count afterwards, the memory will be leaked.
+ * \endrst
  *
  * @param item[take] the item
  * @return the item with reference count decreased by one

src/cbor/floats_ctrls.h

@@ -133,7 +133,7 @@ CBOR_EXPORT cbor_item_t *cbor_build_bool(bool value);
  *
  * \rst
  * .. warning:: It is possible to produce an invalid CBOR value by assigning a
- * invalid value using this mechanism. Please consult the standard before use.
+ *  invalid value using this mechanism. Please consult the standard before use.
  * \endrst
  *
  * @param item[borrow] A ctrl item

src/cbor/serialization.h

@@ -35,7 +35,8 @@ CBOR_EXPORT size_t cbor_serialize(const cbor_item_t *item,
  *
  * \rst
  * .. warning:: It is your responsibility to free the buffer using an
- * appropriate ``free`` implementation. \endrst
+ *  appropriate ``free`` implementation.
+ * \endrst
  *
  * @param item[borrow] A data item
  * @param buffer[out] Buffer containing the result

src/cbor/strings.h

@@ -69,8 +69,9 @@ CBOR_EXPORT cbor_mutable_data cbor_string_handle(const cbor_item_t *item);
  *
  * \rst
  * .. warning:: Using a pointer to a stack allocated constant is a common
- * mistake. Lifetime of the string will expire when it goes out of scope and the
- * CBOR item will be left inconsistent. \endrst
+ *  mistake. Lifetime of the string will expire when it goes out of scope and
+ *  the CBOR item will be left inconsistent.
+ * \endrst
  *
  * @param item[borrow] A definite string
  * @param data The memory block. The caller gives up the ownership of the block.