Updates to rcutils to make rosdoc2 generation happier. (ros2#416)

* Updates to rcutils to make rosdoc2 generation happier.

In particular:

* Fix a mostly duplicated and slightly wrong formatted docblock
at the top of sha256.c
* Add in a few field names so doxygen can resolve them.
* Make a doxygen-only function signature of sha256_final, since
rosdoc2 doesn't understand uint8_t[]
* Modify the configuration to include all needed files.

With this in place, all but one warning are removed when generating
the documentation.

Signed-off-by: Chris Lalancette <clalancette@gmail.com>

Author: clalancette

Doxyfile

@@ -5,10 +5,8 @@ PROJECT_NUMBER         = master
 PROJECT_BRIEF          = "C API providing common utilities and data structures."
 
 # Use these lines to include the generated logging_macro.h (update install path if needed)
-#INPUT                  = README.md ../../../install_isolated/rcutils/include
-#STRIP_FROM_PATH        = /Users/william/ros2_ws/install_isolated/rcutils/include
 # Otherwise just generate for the local (non-generated header files)
-INPUT                  = README.md ./include
+INPUT                  = CONTRIBUTING.md README.md QUALITY_DECLARATION.md ./include
 EXCLUDE_PATTERNS       = */stdatomic_helper/*
 USE_MDFILE_AS_MAINPAGE = README.md
 RECURSIVE              = YES
@@ -26,6 +24,7 @@ PREDEFINED             += RCUTILS_PUBLIC=
 PREDEFINED             += RCUTILS_PUBLIC_TYPE=
 PREDEFINED             += RCUTILS_WARN_UNUSED=
 PREDEFINED             += RCUTILS_ENABLE_FAULT_INJECTION=
+PREDEFINED             += DOXYGEN_ONLY
 
 # Tag files that do not exist will produce a warning and cross-project linking will not work.
 TAGFILES += "../../../doxygen_tag_files/cppreference-doxygen-web.tag.xml=http://en.cppreference.com/w/"

include/rcutils/logging.h

@@ -215,12 +215,12 @@ rcutils_logging_severity_level_from_string(
  * \param[in] args The variable argument list
  */
 typedef void (* rcutils_logging_output_handler_t)(
-  const rcutils_log_location_t *,  // location
-  int,  // severity
-  const char *,  // name
-  rcutils_time_point_value_t,  // timestamp
-  const char *,  // format
-  va_list *  // args
+  const rcutils_log_location_t * location,
+  int severity,
+  const char * name,
+  rcutils_time_point_value_t timestamp,
+  const char * format,
+  va_list * args
 );
 
 /// Get the current output handler.

include/rcutils/sha256.h

@@ -12,12 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-/// \file Provides a simple SHA256 algorithm for hashing.
-/// This implementation makes no security guarantees, its use case
-/// is for non-sensitive comparison of message digests
-/// Implementation originally copied from Brad Conte
-/// https://github.com/B-Con/crypto-algorithms/blob/master/sha256.c
-
 /** \file sha256.h
  *  \brief SHA256 implementation
  *
@@ -28,6 +22,8 @@
  *  Algorithm specification can be found here:
  *  http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf
  *  This implementation uses little endian byte order.
+ *  This implementation makes no security guarantees, its use case if for
+ *  non-sensitive comparison of message digests.
  */
 
 #ifndef RCUTILS__SHA256_H_
@@ -83,10 +79,19 @@ void rcutils_sha256_update(rcutils_sha256_ctx_t * ctx, const uint8_t * data, siz
  * \param[out] output_hash Calculated sha256 message digest to be filled
  * \return void
  */
+#ifdef DOXYGEN_ONLY
+// One of the tools used by rosdoc2 misunderstands uint8_t[] as a uint8_t,
+// so make it a pointer for documentation purposes.
+RCUTILS_PUBLIC
+void rcutils_sha256_final(
+  rcutils_sha256_ctx_t * ctx,
+  uint8_t * output_hash);
+#else
 RCUTILS_PUBLIC
 void rcutils_sha256_final(
   rcutils_sha256_ctx_t * ctx,
   uint8_t output_hash[RCUTILS_SHA256_BLOCK_SIZE]);
+#endif
 
 #ifdef __cplusplus
 }

include/rcutils/types/hash_map.h

@@ -44,7 +44,7 @@ typedef struct RCUTILS_PUBLIC_TYPE rcutils_hash_map_s
  * \return A hash value for the provided string
  */
 typedef size_t (* rcutils_hash_map_key_hasher_t)(
-  const void *  // key to hash
+  const void * key
 );
 
 /// The function signature for a key comparison function.
@@ -56,8 +56,8 @@ typedef size_t (* rcutils_hash_map_key_hasher_t)(
  * \return Zero if val1 == val2.
  */
 typedef int (* rcutils_hash_map_key_cmp_t)(
-  const void *,  // val1
-  const void *  // val2
+  const void * val1,
+  const void * val2
 );
 
 /**