Fix up documentation build for rcl when using rosdoc2 (#932)

* Use leading * for pointer types, not trailing []
* Skip internal documentation
* Avoid duplicate type names
* Keep *_impl_t type names
* Use _t types wherever possible

Signed-off-by: Michel Hidalgo <michel@ekumenlabs.com>

rcl/Doxyfile

@@ -15,13 +15,10 @@ GENERATE_LATEX         = NO
 ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             += RCL_ALIGNAS(x)=
 PREDEFINED             += RCL_PUBLIC=
 PREDEFINED             += RCL_WARN_UNUSED=
 
-# Uncomment to generate internal documentation.
-ENABLED_SECTIONS       = INTERNAL
-INPUT                  += ./src/rcl/arguments.c
-
 # 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/"
 # Consider changing "latest" to the version you want to reference (e.g. beta1 or 1.0.0)

rcl/include/rcl/arguments.h

@@ -29,13 +29,13 @@ extern "C"
 {
 #endif
 
-struct rcl_arguments_impl_t;
+typedef struct rcl_arguments_impl_s rcl_arguments_impl_t;
 
 /// Hold output of parsing command line arguments.
-typedef struct rcl_arguments_t
+typedef struct rcl_arguments_s
 {
   /// Private implementation pointer.
-  struct rcl_arguments_impl_t * impl;
+  rcl_arguments_impl_t * impl;
 } rcl_arguments_t;
 
 /// The command-line flag that delineates the start of ROS arguments.
@@ -151,7 +151,7 @@ RCL_WARN_UNUSED
 rcl_ret_t
 rcl_parse_arguments(
   int argc,
-  const char * const argv[],
+  const char * const * argv,
   rcl_allocator_t allocator,
   rcl_arguments_t * args_output);
 
@@ -369,11 +369,11 @@ RCL_PUBLIC
 RCL_WARN_UNUSED
 rcl_ret_t
 rcl_remove_ros_arguments(
-  char const * const argv[],
+  const char * const * argv,
   const rcl_arguments_t * args,
   rcl_allocator_t allocator,
   int * nonros_argc,
-  const char ** nonros_argv[]);
+  const char *** nonros_argv);
 
 /// Return log levels parsed from the command line.
 /**

rcl/include/rcl/client.h

@@ -29,17 +29,17 @@ extern "C"
 #include "rcl/visibility_control.h"
 
 /// Internal rcl client implementation struct.
-struct rcl_client_impl_t;
+typedef struct rcl_client_impl_s rcl_client_impl_t;
 
 /// Structure which encapsulates a ROS Client.
-typedef struct rcl_client_t
+typedef struct rcl_client_s
 {
   /// Pointer to the client implementation
-  struct rcl_client_impl_t * impl;
+  rcl_client_impl_t * impl;
 } rcl_client_t;
 
 /// Options available for a rcl_client_t.
-typedef struct rcl_client_options_t
+typedef struct rcl_client_options_s
 {
   /// Middleware quality of service settings for the client.
   rmw_qos_profile_t qos;

rcl/include/rcl/context.h

@@ -43,7 +43,7 @@ extern "C"
 /// A unique ID per context instance.
 typedef uint64_t rcl_context_instance_id_t;
 
-struct rcl_context_impl_t;
+typedef struct rcl_context_impl_s rcl_context_impl_t;
 
 /// Encapsulates the non-global state of an init/shutdown cycle.
 /**
@@ -110,14 +110,14 @@ struct rcl_context_impl_t;
  * it directly (e.g. nodes and guard conditions) or indirectly (e.g.
  * subscriptions and topics).
  */
-typedef struct rcl_context_t
+typedef struct rcl_context_s
 {
   /// Global arguments for all nodes which share this context.
   /** Typically generated by the parsing of argc/argv in rcl_init(). */
   rcl_arguments_t global_arguments;
 
   /// Implementation specific pointer.
-  struct rcl_context_impl_t * impl;
+  rcl_context_impl_t * impl;
 
   // The assumption that this is big enough for an atomic_uint_least64_t is
   // ensured with a static_assert in the context.c file.

rcl/include/rcl/event.h

@@ -32,15 +32,15 @@ extern "C"
 #include "rcl/visibility_control.h"
 
 /// Enumeration of all of the publisher events that may fire.
-typedef enum rcl_publisher_event_type_t
+typedef enum rcl_publisher_event_type_e
 {
   RCL_PUBLISHER_OFFERED_DEADLINE_MISSED,
   RCL_PUBLISHER_LIVELINESS_LOST,
   RCL_PUBLISHER_OFFERED_INCOMPATIBLE_QOS,
 } rcl_publisher_event_type_t;
 
 /// Enumeration of all of the subscription events that may fire.
-typedef enum rcl_subscription_event_type_t
+typedef enum rcl_subscription_event_type_e
 {
   RCL_SUBSCRIPTION_REQUESTED_DEADLINE_MISSED,
   RCL_SUBSCRIPTION_LIVELINESS_CHANGED,
@@ -49,13 +49,13 @@ typedef enum rcl_subscription_event_type_t
 } rcl_subscription_event_type_t;
 
 /// Internal rcl implementation struct.
-struct rcl_event_impl_t;
+typedef struct rcl_event_impl_s rcl_event_impl_t;
 
 /// Structure which encapsulates a ROS QoS event handle.
-typedef struct rcl_event_t
+typedef struct rcl_event_s
 {
   /// Pointer to the event implementation
-  struct rcl_event_impl_t * impl;
+  rcl_event_impl_t * impl;
 } rcl_event_t;
 
 /// Return a rcl_event_t struct with members set to `NULL`.

rcl/include/rcl/guard_condition.h

@@ -29,20 +29,20 @@ extern "C"
 #include "rcl/visibility_control.h"
 
 /// Internal rcl guard condition implementation struct.
-struct rcl_guard_condition_impl_t;
+typedef struct rcl_guard_condition_impl_s rcl_guard_condition_impl_t;
 
 /// Handle for a rcl guard condition.
-typedef struct rcl_guard_condition_t
+typedef struct rcl_guard_condition_s
 {
   /// Context associated with this guard condition.
   rcl_context_t * context;
 
   /// Pointer to the guard condition implementation
-  struct rcl_guard_condition_impl_t * impl;
+  rcl_guard_condition_impl_t * impl;
 } rcl_guard_condition_t;
 
 /// Options available for a rcl guard condition.
-typedef struct rcl_guard_condition_options_t
+typedef struct rcl_guard_condition_options_s
 {
   /// Custom allocator for the guard condition, used for internal allocations.
   rcl_allocator_t allocator;

rcl/include/rcl/init_options.h

@@ -29,13 +29,13 @@ extern "C"
 #include "rcl/types.h"
 #include "rcl/visibility_control.h"
 
-struct rcl_init_options_impl_t;
+typedef struct rcl_init_options_impl_s rcl_init_options_impl_t;
 
 /// Encapsulation of init options and implementation defined init options.
-typedef struct rcl_init_options_t
+typedef struct rcl_init_options_s
 {
   /// Implementation specific pointer.
-  struct rcl_init_options_impl_t * impl;
+  rcl_init_options_impl_t * impl;
 } rcl_init_options_t;
 
 /// Return a zero initialized rcl_init_options_t struct.

rcl/include/rcl/lexer.h

@@ -30,7 +30,7 @@ extern "C"
 #endif
 
 /// Type of lexeme found by lexical analysis.
-typedef enum rcl_lexeme_t
+typedef enum rcl_lexeme_e
 {
   /// Indicates no valid lexeme was found (end of input not reached)
   RCL_LEXEME_NONE = 0,

rcl/include/rcl/lexer_lookahead.h

@@ -31,13 +31,13 @@ extern "C"
 #endif
 
 // Forward declaration
-struct rcl_lexer_lookahead2_impl_t;
+typedef struct rcl_lexer_lookahead2_impl_s rcl_lexer_lookahead2_impl_t;
 
 /// Track lexical analysis and allow looking ahead 2 lexemes.
-typedef struct rcl_lexer_lookahead2_t
+typedef struct rcl_lexer_lookahead2_s
 {
   /// Pointer to the lexer look ahead2 implementation
-  struct rcl_lexer_lookahead2_impl_t * impl;
+  rcl_lexer_lookahead2_impl_t * impl;
 } rcl_lexer_lookahead2_t;
 
 /// Get a zero initialized rcl_lexer_lookahead2_t instance.

rcl/include/rcl/log_level.h

@@ -31,7 +31,7 @@ extern "C"
 typedef enum RCUTILS_LOG_SEVERITY rcl_log_severity_t;
 
 /// A logger item to specify a name and a log level.
-typedef struct rcl_logger_setting_t
+typedef struct rcl_logger_setting_s
 {
   /// Name for the logger.
   const char * name;
@@ -40,12 +40,12 @@ typedef struct rcl_logger_setting_t
 } rcl_logger_setting_t;
 
 /// Hold default logger level and other logger setting.
-typedef struct rcl_log_levels_t
+typedef struct rcl_log_levels_s
 {
   /// Minimum default logger level severity.
   rcl_log_severity_t default_logger_level;
   /// Array of logger setting.
-  struct rcl_logger_setting_t * logger_settings;
+  rcl_logger_setting_t * logger_settings;
   /// Number of logger settings.
   size_t num_logger_settings;
   /// Capacity of logger settings.

rcl/include/rcl/node.h

@@ -27,22 +27,22 @@ extern "C"
 #include "rcl/allocator.h"
 #include "rcl/arguments.h"
 #include "rcl/context.h"
+#include "rcl/guard_condition.h"
 #include "rcl/macros.h"
 #include "rcl/node_options.h"
 #include "rcl/types.h"
 #include "rcl/visibility_control.h"
 
-struct rcl_guard_condition_t;
-struct rcl_node_impl_t;
+typedef struct rcl_node_impl_s rcl_node_impl_t;
 
 /// Structure which encapsulates a ROS Node.
-typedef struct rcl_node_t
+typedef struct rcl_node_s
 {
   /// Context associated with this node.
   rcl_context_t * context;
 
   /// Private implementation pointer.
-  struct rcl_node_impl_t * impl;
+  rcl_node_impl_t * impl;
 } rcl_node_t;
 
 /// Return a rcl_node_t struct with members initialized to `NULL`.
@@ -462,7 +462,7 @@ rcl_node_get_rcl_instance_id(const rcl_node_t * node);
  */
 RCL_PUBLIC
 RCL_WARN_UNUSED
-const struct rcl_guard_condition_t *
+const rcl_guard_condition_t *
 rcl_node_get_graph_guard_condition(const rcl_node_t * node);
 
 /// Return the logger name of the node.

rcl/include/rcl/node_options.h

@@ -31,7 +31,7 @@ extern "C"
 #define RCL_NODE_OPTIONS_DEFAULT_DOMAIN_ID RCL_DEFAULT_DOMAIN_ID
 
 /// Structure which encapsulates the options for creating a rcl_node_t.
-typedef struct rcl_node_options_t
+typedef struct rcl_node_options_s
 {
   // bool anonymous_name;
 

rcl/include/rcl/publisher.h

@@ -30,17 +30,17 @@ extern "C"
 #include "rcl/time.h"
 
 /// Internal rcl publisher implementation struct.
-struct rcl_publisher_impl_t;
+typedef struct rcl_publisher_impl_s rcl_publisher_impl_t;
 
 /// Structure which encapsulates a ROS Publisher.
-typedef struct rcl_publisher_t
+typedef struct rcl_publisher_s
 {
   /// Pointer to the publisher implementation
-  struct rcl_publisher_impl_t * impl;
+  rcl_publisher_impl_t * impl;
 } rcl_publisher_t;
 
 /// Options available for a rcl publisher.
-typedef struct rcl_publisher_options_t
+typedef struct rcl_publisher_options_s
 {
   /// Middleware quality of service settings for the publisher.
   rmw_qos_profile_t qos;

rcl/include/rcl/remap.h

@@ -28,13 +28,13 @@ extern "C"
 {
 #endif
 
-struct rcl_remap_impl_t;
+typedef struct rcl_remap_impl_s rcl_remap_impl_t;
 
 /// Hold remapping rules.
-typedef struct rcl_remap_t
+typedef struct rcl_remap_s
 {
   /// Private implementation pointer.
-  struct rcl_remap_impl_t * impl;
+  rcl_remap_impl_t * impl;
 } rcl_remap_t;
 
 /// Return a rcl_remap_t struct with members initialized to `NULL`.

rcl/include/rcl/service.h

@@ -29,17 +29,17 @@ extern "C"
 #include "rcl/visibility_control.h"
 
 /// Internal rcl implementation struct.
-struct rcl_service_impl_t;
+typedef struct rcl_service_impl_s rcl_service_impl_t;
 
 /// Structure which encapsulates a ROS Service.
-typedef struct rcl_service_t
+typedef struct rcl_service_s
 {
   /// Pointer to the service implementation
-  struct rcl_service_impl_t * impl;
+  rcl_service_impl_t * impl;
 } rcl_service_t;
 
 /// Options available for a rcl service.
-typedef struct rcl_service_options_t
+typedef struct rcl_service_options_s
 {
   /// Middleware quality of service settings for the service.
   rmw_qos_profile_t qos;

rcl/include/rcl/subscription.h

@@ -31,17 +31,17 @@ extern "C"
 #include "rmw/message_sequence.h"
 
 /// Internal rcl implementation struct.
-struct rcl_subscription_impl_t;
+typedef struct rcl_subscription_impl_s rcl_subscription_impl_t;
 
 /// Structure which encapsulates a ROS Subscription.
-typedef struct rcl_subscription_t
+typedef struct rcl_subscription_s
 {
   /// Pointer to the subscription implementation
-  struct rcl_subscription_impl_t * impl;
+  rcl_subscription_impl_t * impl;
 } rcl_subscription_t;
 
 /// Options available for a rcl subscription.
-typedef struct rcl_subscription_options_t
+typedef struct rcl_subscription_options_s
 {
   /// Middleware quality of service settings for the subscription.
   rmw_qos_profile_t qos;