Feature documentation of rosidl_runtime_c/cpp and rosidl_typesupport_interface

rosidl_runtime_c/Doxyfile

@@ -4,7 +4,8 @@ PROJECT_NAME           = "rosidl_runtime_c"
 PROJECT_NUMBER         = master
 PROJECT_BRIEF          = "Generate the rosidl interfaces in C."
 
-INPUT                  = ./include
+INPUT                  = README.md ./include ./docs ./QUALITY_DECLARATION.md
+USE_MDFILE_AS_MAINPAGE = README.md
 RECURSIVE              = YES
 OUTPUT_DIRECTORY       = doc_output
 

rosidl_runtime_c/QUALITY_DECLARATION.md

@@ -1,6 +1,6 @@
 This document is a declaration of software quality for the `rosidl_runtime_c` package, based on the guidelines in [REP-2004](https://www.ros.org/reps/rep-2004.html).
 
-# `rosidl_runtime_c` Quality Declaration
+# rosidl_runtime_c Quality Declaration
 
 The package `rosidl_runtime_c` claims to be in the **Quality Level 4** category.
 
@@ -65,7 +65,7 @@ All pull requests must resolve related documentation changes before merging.
 
 ### Feature Documentation [3.i]
 
-`rosidl_runtime_c` does not have any feature documentation and it will need to be added for higher quality levels.
+`rosidl_runtime_c` has feature documentation and it is publicly [hosted](docs/FEATURES.md).
 
 ### Public API Documentation [3.ii]
 

rosidl_runtime_c/README.md

@@ -2,6 +2,10 @@
 
 `rosidl_runtime_c` is a package and provides runtime ROSIDL functionality C.
 
+## Features
+
+A list of features provided by `rosidl_runtime_c` is available in its [feature documentation](docs/FEATURES.md).
+
 ## Quality Declaration
 
 This package claims to be in the **Quality Level 4** category, see the [Quality Declaration](QUALITY_DECLARATION.md) for more details.

rosidl_runtime_c/docs/FEATURES.md

@@ -0,0 +1,29 @@
+# rosidl_runtime_c Features
+
+## Primitive sequence definitions initializations and finalizations
+
+`rosidl_runtime_c` provides default definitions, as well as initialization and finalization functions for the supported rosidl primitive sequence types.
+These functions are defined in the following headers:
+
+* `primitives_sequence.h`: C struct definitions for all supported primitive sequence types.
+* `primitive_sequence_functions.h`: initialization and finalization functionality for the above defined sequences.
+* `sequence_bound.h`: Struct designed to track the upper bounds size of a sequence. Currently unused.
+
+## String and u16string definitions, initializations and finalizations
+
+Like the sequences described above, `rosidl_runtime_c` provides definitions, as well as initialization and finalization functions for 8-bit and 16-bit character strings.
+
+* `string.h`: C struct definition for an 8-bit string.
+* `string_functions.h`: initialization and finalization functionality for the rosidl 8-bit string.
+* `string_bound.h`: Designed to track the upper bounds size of a string. Currently unused.
+
+* `u16string.h`: C struct definition for a 16-bit string.
+* `u16string_functions.h`: initialization and finalization functionality for the rosidl 16-bit string.
+
+## Typesupport structs
+
+This package defines several structs which are utilized for providing access to properties and functionality of different rosidl types.
+They are defined for the three main ROS 2 rosidl types:
+* Messages (`message_type_support_struct.h`)
+* Services (`service_type_support_struct.h`)
+* Actions (`action_type_support_struct.h`)

rosidl_runtime_cpp/Doxyfile

@@ -4,7 +4,8 @@ PROJECT_NAME           = "rosidl_runtime_cpp"
 PROJECT_NUMBER         = master
 PROJECT_BRIEF          = "Generate the rosidl interfaces in C++."
 
-INPUT                  = ./include
+INPUT                  = README.md ./include ./docs ./QUALITY_DECLARATION.md
+USE_MDFILE_AS_MAINPAGE = README.md
 RECURSIVE              = YES
 OUTPUT_DIRECTORY       = doc_output
 

rosidl_runtime_cpp/QUALITY_DECLARATION.md

@@ -1,6 +1,6 @@
 This document is a declaration of software quality for the `rosidl_runtime_cpp` package, based on the guidelines in [REP-2004](https://www.ros.org/reps/rep-2004.html).
 
-# `rosidl_runtime_cpp` Quality Declaration
+# rosidl_runtime_cpp Quality Declaration
 
 The package `rosidl_runtime_cpp` claims to be in the **Quality Level 4** category.
 
@@ -65,7 +65,7 @@ All pull requests must resolve related documentation changes before merging.
 
 ### Feature Documentation [3.i]
 
-`rosidl_runtime_cpp` does not have any feature documentation and it will need to be added for higher quality levels.
+`rosidl_runtime_cpp` has feature documentation and it is publicly [hosted](docs/FEATURES.md).
 
 ### Public API Documentation [3.ii]
 

rosidl_runtime_cpp/README.md

@@ -1,6 +1,10 @@
 # rosidl_generator_cpp
 
-`rosidl_runtime_c` is a package generates and provides runtime ROSIDL interfaces files in C++.
+`rosidl_runtime_cpp` is a package generates and provides runtime ROSIDL interfaces files in C++.
+
+## Features
+
+The features provided by `rosidl_runtime_cpp` are documented in its [feature documentation](docs/FEATURES.md).
 
 ## Quality Declaration
 

rosidl_runtime_cpp/docs/FEATURES.md

@@ -0,0 +1,27 @@
+# rosidl_runtime_cpp Features
+
+## Typesupport function handler  
+
+`rosidl_runtime_cpp` provides several templated function declarations for getting the type support handler.
+They are meant to be defined in each rosidl definition's C++ generated code.
+They are defined for both the `rosidl_runtime_cpp` and `rosidl_typesupport_cpp` namespaces.
+
+`rosidl_runtime_cpp`
+* Messages (`message_type_support_decl.hpp`)
+* Services (`service_type_support_decl.hpp`)
+* Actions (`action_type_support_decl.hpp`)
+
+`rosidl_typesupport_cpp`
+* Messages (`message_type_support.hpp`)
+* Services (`service_type_support.hpp`)
+* Actions (`action_type_support.hpp`)
+
+## C++ Type Traits
+
+`rosidl_runtime_c` provides numerous C++ Type Traits for rosidl interfaces in `traits.hpp`.
+These type traits are useful for providing compile-time checks of rosidl C++ types.
+
+## Bounded Vector
+
+Provided in `bounded_vector.hpp` is an implementation of a std::vector like container class, that has a bounded capacity.
+This class is utilized by rosidl types that declare a bounded sequence.

rosidl_typesupport_interface/Doxyfile

@@ -0,0 +1,24 @@
+# All settings not listed here will use the Doxygen default values.
+
+PROJECT_NAME           = "rosidl_typesupport_interface"
+PROJECT_NUMBER         = master
+PROJECT_BRIEF          = "The C/C++ interface for rosidl typesupport packages."
+
+INPUT                  = README.md ./include ./QUALITY_DECLARATION.md
+USE_MDFILE_AS_MAINPAGE = README.md
+RECURSIVE              = YES
+OUTPUT_DIRECTORY       = doc_output
+
+EXTRACT_ALL            = YES
+SORT_MEMBER_DOCS       = NO
+
+GENERATE_LATEX         = NO
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+
+# 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/"
+# Uncomment to generate tag files for cross-project linking.
+GENERATE_TAGFILE = "../../../../doxygen_tag_files/rosidl_runtime_cpp.tag"

rosidl_typesupport_interface/QUALITY_DECLARATION.md

@@ -1,6 +1,6 @@
 This document is a declaration of software quality for the `rosidl_typesupport_interface` package, based on the guidelines in [REP-2004](https://www.ros.org/reps/rep-2004.html).
 
-# `rosidl_typesupport_interface` Quality Declaration
+# rosidl_typesupport_interface Quality Declaration
 
 The package `rosidl_typesupport_interface` claims to be in the **Quality Level 4** category.
 
@@ -65,7 +65,7 @@ All pull requests must resolve related documentation changes before merging.
 
 ### Feature Documentation [3.i]
 
-`rosidl_typesupport_interface` does not have any feature documentation and it will need to be added for higher quality levels.
+`rosidl_typesupport_interface` has feature documentation and it is publicly [hosted](README.md).
 
 ### Public API Documentation [3.ii]
 

rosidl_typesupport_interface/README.md

@@ -2,6 +2,11 @@
 
 `rosidl_typesupport_interface` is a package that provides macros that define the rosidl typesupport interface.
 
+## Features
+
+`rosidl_typesupport_interface` provides an interface of C/C++ macros for rosidl typesupport packages.
+They are available in the `macros.h` header.
+
 ## Quality Declaration
 
 This package claims to be in the **Quality Level 4** category, see the [Quality Declaration](QUALITY_DECLARATION.md) for more details.

rosidl_typesupport_interface/include/rosidl_typesupport_interface/macros.h

@@ -15,23 +15,27 @@
 #ifndef ROSIDL_TYPESUPPORT_INTERFACE__MACROS_H_
 #define ROSIDL_TYPESUPPORT_INTERFACE__MACROS_H_
 
+/// Declare the typesupport symbol name. Note: this should not be called directly.
 #define ROSIDL_TYPESUPPORT_INTERFACE__SYMBOL_NAME( \
     typesupport_name, function_name, package_name, interface_type, interface_name) \
   typesupport_name ## __ ## function_name ## __ ## \
   package_name ## __ ## interface_type ## __ ## interface_name
 
+/// Declare a typesupport symbol name for a rosidl message definition.
 #define ROSIDL_TYPESUPPORT_INTERFACE__MESSAGE_SYMBOL_NAME( \
     typesupport_name, package_name, interface_type, message_name) \
   ROSIDL_TYPESUPPORT_INTERFACE__SYMBOL_NAME( \
     typesupport_name, get_message_type_support_handle, \
     package_name, interface_type, message_name)
 
+/// Declare a typesupport symbol name for a rosidl service definition.
 #define ROSIDL_TYPESUPPORT_INTERFACE__SERVICE_SYMBOL_NAME( \
     typesupport_name, package_name, interface_type, service_name) \
   ROSIDL_TYPESUPPORT_INTERFACE__SYMBOL_NAME( \
     typesupport_name, get_service_type_support_handle, \
     package_name, interface_type, service_name)
 
+/// Declare a typesupport symbol name for a rosidl action definition.
 #define ROSIDL_TYPESUPPORT_INTERFACE__ACTION_SYMBOL_NAME( \
     typesupport_name, package_name, interface_type, action_name) \
   ROSIDL_TYPESUPPORT_INTERFACE__SYMBOL_NAME( \