Create package-level READMEs and add some inline comments

Signed-off-by: Stephen Brawner <brawner@gmail.com>

README.md

@@ -1,2 +1,11 @@
 # rcl_interfaces repository
 This repository contains a set of packages that primarily contain interface files (.msg and .srv) which are used both to implement client library concepts and for testing.
+
+# rcl_interface packages
+* [action_msgs](action_msgs/README.md): Messages and services for [ROS 2 actions](http://design.ros2.org/articles/actions.html)
+* [builtin_interfaces](builtin_interfaces/README.md): Message definitions for types in the OMG IDL Platform Specific Model
+* [composition_interfaces](composition_interfaces/README.md): Services for managing composeable nodes.
+* [lifecycle_msgs](lifecycle_msgs/README.md): Message and service definitions for managing lifecycle nodes.
+* [rcl_interfaces](rcl_interfaces/README.md): Message and service definitions for ROS client libraries
+* [rosgraph_msgs](rosgraph_msgs/README.md): Message definitions relating the ROS Computation Graph
+* test_msgs: Used exclusively for testing purposes

action_msgs/README.md

@@ -0,0 +1,13 @@
+# action_msgs
+This package contains several messages and services useful for ROS 2 actions.
+More information about actions can be found on its [design article](http://design.ros2.org/articles/actions.html).
+
+For more information about ROS 2 interfaces, see [index.ros2.org](https://index.ros.org/doc/ros2/Concepts/About-ROS-Interfaces/)
+
+## Messages (.msg)
+* [GoalInfo](msg/GoalInfo.msg): Goal identifier message, with a goal id and time stamp
+* [GoalStatus](msg/GoalStatus.msg): Describes a goal's current state machine status
+* [GoalStatusArray](msg/GoalStatusArray.msg): An array of [GoalStatus](msg/GoalStatus.msg) messages
+
+## Services (.srv)
+* [CancelGoal](srv/CancelGoal.srv): Cancel Goals either by id and/or timestamp

action_msgs/msg/GoalStatus.msg

@@ -1,15 +1,32 @@
-# An action goal can be in one of these states after it is accepted by an action server.
+# An action goal can be in one of these states after it is accepted by an action
+# server.
+#
 # For more information, see http://design.ros2.org/articles/actions.html
+
+# Indicates status has not been properly set
 int8 STATUS_UNKNOWN   = 0
+
+# The goal has been accepted and is awaiting execution.
 int8 STATUS_ACCEPTED  = 1
+
+# The goal is currently being executed by the action server.
 int8 STATUS_EXECUTING = 2
+
+# The client has requested that the goal be canceled and the action server has
+# accepted the cancel request.
 int8 STATUS_CANCELING = 3
+
+# The goal was achieved successfully by the action server.
 int8 STATUS_SUCCEEDED = 4
+
+# The goal was canceled after an external request from an action client.
 int8 STATUS_CANCELED  = 5
+
+# The goal was terminated by the action server without an external request.
 int8 STATUS_ABORTED   = 6
 
 # Goal info (contains ID and timestamp)
 GoalInfo goal_info
 
-# Goal status
+# Action goal state-machine status
 int8 status

action_msgs/srv/CancelGoal.srv

@@ -8,28 +8,39 @@
 # - If the goal ID is not zero and timestamp is not zero, cancel the goal with
 #   the given ID and all goals accepted at or before the timestamp.
 
-# Goal info containing an ID and timestamp
+# Goal info describing the goals to cancel, see above
 GoalInfo goal_info
 ---
-# Return codes
+##
+## Return codes
+##
+
 # Indicates the request was accepted without any errors.
-# One or more goals have transitioned to the CANCELING state.
-# The goals_canceling list is not empty.
+#
+# One or more goals have transitioned to the CANCELING state. The
+# goals_canceling list is not empty.
 int8 ERROR_NONE=0
+
 # Indicates the request was rejected.
-# No goals have transitioned to the CANCELING state.
-# The goals_canceling list is empty.
+#
+# No goals have transitioned to the CANCELING state. The goals_canceling list is
+# empty.
 int8 ERROR_REJECTED=1
+
 # Indicates the requested goal ID does not exist.
-# No goals have transitioned to the CANCELING state.
-# The goals_canceling list is empty.
+#
+# No goals have transitioned to the CANCELING state. The goals_canceling list is
+# empty.
 int8 ERROR_UNKNOWN_GOAL_ID=2
+
 # Indicates the goal is not cancelable because it is already in a terminal state.
-# No goals have transitioned to the CANCELING state.
-# The goals_canceling list is empty.
+#
+# No goals have transitioned to the CANCELING state. The goals_canceling list is
+# empty.
 int8 ERROR_GOAL_TERMINATED=3
 
-# Return code
+# Return code, see above definitions
 int8 return_code
+
 # Goals that accepted the cancel request
 GoalInfo[] goals_canceling

builtin_interfaces/README.md

@@ -0,0 +1,10 @@
+# builtin_interfaces
+A package containing message definitions for types defined in the OMG IDL Platform Specific Model.
+
+For more information about ROS 2 time, see [design.ros2.org](https://design.ros2.org/articles/clock_and_time.html)
+
+For more information about ROS 2 interfaces, see [index.ros2.org](https://index.ros.org/doc/ros2/Concepts/About-ROS-Interfaces/)
+
+## Messages (.msg)
+* [Duration](msg/Duration.msg): Describes a time duration composed of seconds and nanoseconds components.
+* [Time](msg/Time.msg): Describes a point in time, composed of seconds and nanoseconds components.

builtin_interfaces/msg/Duration.msg

@@ -1,2 +1,8 @@
+# Duration defines a period between two time points. It is comprised of a
+# seconds component and a nanoseconds component.
+
+# Seconds component, range is valid over any possible int32 value.
 int32 sec
+
+# Nanoseconds component in the range of [0, 10e9)
 uint32 nanosec

builtin_interfaces/msg/Time.msg

@@ -1,2 +1,7 @@
+# Time indicates a specific point in time, relative to a clock's 0 point.
+
+# The seconds component, valid over all int32 values
 int32 sec
+
+# The nanoseconds component, valid in the range [0, 10e9)
 uint32 nanosec

composition_interfaces/README.md

@@ -0,0 +1,9 @@
+# composition_interfaces
+This is a package containing message and service definitions for managing composable nodes in a container process. Generally these services are used by the ROS 2 [`roslaunch`](https://design.ros2.org/articles/roslaunch.html) system.
+
+For more information about ROS 2 interfaces, see [index.ros2.org](https://index.ros.org/doc/ros2/Concepts/About-ROS-Interfaces/)
+
+## Services (.srv)
+* [ListNodes](srv/ListNodes.srv): Retrieve a list of running composable nodes, including their names and ids.
+* [LoadNodes](srv/LoadNode.srv): Load a composable node
+* [UnloadNode](UnloadNode.srv): Unload a specified node by its id

composition_interfaces/srv/LoadNode.srv

@@ -1,28 +1,42 @@
-# A ROS package the composable node can be found in
+# The ROS package in which the composable node can be found
 string package_name
-# a plugin within that package
+
+# A plugin within the ROS package "package_name"
 string plugin_name
 
-# Name the composable node should use, or empty to use the node's default name
+# The assigned name of the composable node. Leave empty to use the node's
+# default name
 string node_name
-# Namespace the composable node should use, or empty to use the node's default namespace
+
+# The assigned namespace of the composable node. Leave empty to use the node's
+# default namespace
 string node_namespace
-# Values from message rcl_interfaces/Log
+
+# The assigned log level of the composable node. Enum values are found in
+# message rcl_interfaces/Log
 uint8 log_level
-# Remap rules
+
+# Remapping rules for this composable node.
+#
+# For more info about static_remapping rules and their syntax, see
+# https://design.ros2.org/articles/static_remapping.html
 # TODO(sloretz) rcl_interfaces message for remap rules?
 string[] remap_rules
-# Parameters to set
+
+# The Parameters of this composable node to set
 rcl_interfaces/Parameter[] parameters
 
 # key/value arguments that are specific to a type of container process
 rcl_interfaces/Parameter[] extra_arguments
 ---
 # True if the node was successfully loaded
 bool success
+
 # Human readable error message if success is false, else empty string
 string error_message
+
 # Name of the loaded composable node (including namespace)
 string full_node_name
+
 # A unique identifier for the loaded node
 uint64 unique_id

composition_interfaces/srv/UnloadNode.srv

@@ -3,5 +3,6 @@ uint64 unique_id
 ---
 # True if the node existed and was unloaded
 bool success
+
 # Human readable error message if success is false, else empty string
 string error_message

lifecycle_msgs/README.md

@@ -0,0 +1,20 @@
+# lifecycle_msgs
+This package contains message and service definitions for managing lifecycle nodes.
+These messages and services form a standardized interface for transitioning these
+managed nodes through a known state-machine.
+
+For more information about life cycle nodes see: [design.ros2.org](http://design.ros2.org/articles/node_lifecycle.html)
+
+For more information about ROS 2 interfaces, see [index.ros2.org](https://index.ros.org/doc/ros2/Concepts/About-ROS-Interfaces/)
+
+## Messages (.msg)
+* [State](msg/State.msg): A lifecycle node's state-machine state
+* [Transition](msg/Transition.msg): A state transition with specific id and label
+* [TransitionDescription](msg/TransitionDescription.msg): A description of a transition from one state-machine state to another.
+* [TransitionEvent](msg/TransitionEvent.msg): A timestamped state transition
+
+## Services (.srv)
+* [ChangeState](srv/ChangeState.srv): Request a node change states with a specific transition
+* [GetAvailableStates](srv/GetAvailableStates.srv): Request an array of states that this node can transition to.
+* [GetAvailableTransitions](srv/GetAvailableTransitions.srv): Request an array of lifecycle state transitions available for this node
+* [GetState](srv/GetState.srv): Request the current lifecycle state of this node

lifecycle_msgs/msg/State.msg

@@ -1,26 +1,57 @@
-# Primary state definitions
-# as depicted in
+# Primary state definitions as depicted in
 # http://design.ros2.org/articles/node_lifecycle.html
 
-# These are the primary states
-# State changes can only be requested
-# when the node is in one of these states.
+# These are the primary states. State changes can only be requested when the
+# node is in one of these states.
+
+# Indicates state has not yet been set
 uint8 PRIMARY_STATE_UNKNOWN = 0
+
+# This is the life cycle state the node is in immediately after being
+# instantiated.
 uint8 PRIMARY_STATE_UNCONFIGURED = 1
+
+# This state represents a node that is not currently performing any processing.
 uint8 PRIMARY_STATE_INACTIVE = 2
+
+# This is the main state of the node’s life cycle. While in this state, the node
+# performs any processing, responds to service requests, reads and processes
+# data, produces output, etc.
 uint8 PRIMARY_STATE_ACTIVE = 3
+
+# The Finalized state is the state in which the node ends immediately before
+# being destroyed
 uint8 PRIMARY_STATE_FINALIZED = 4
 
-# Temporary intermediate states
-# When a transition is requested, the
-# node changes its state into one
-# of these states.
+# Temporary intermediate states. When a transition is requested, the node
+# changes its state into one of these states.
+
+# In this transition state the node’s onConfigure callback will be called to
+# allow the node to load its configuration and conduct any required setup.
 uint8 TRANSITION_STATE_CONFIGURING = 10
+
+# In this transition state the node’s callback onCleanup will be called to clear
+# all state and return the node to a functionally equivalent state as when
+# first created.
 uint8 TRANSITION_STATE_CLEANINGUP = 11
+
+# In this transition state the callback onShutdown will be executed to do any
+# cleanup necessary before destruction
 uint8 TRANSITION_STATE_SHUTTINGDOWN = 12
+
+# In this transition state the callback onActivate will be executed to do any
+# final preparations to start executing
 uint8 TRANSITION_STATE_ACTIVATING = 13
+
+# In this transition state the callback onDeactivate will be executed to do any
+# cleanup to start executing, and reverse the onActivate changes.
 uint8 TRANSITION_STATE_DEACTIVATING = 14
+
+# This transition state is where any error may be cleaned up
 uint8 TRANSITION_STATE_ERRORPROCESSING = 15
 
+# The state id value from the above definitions
 uint8 id
+
+# A text label of the state
 string label

lifecycle_msgs/msg/Transition.msg

@@ -1,25 +1,49 @@
-# Default values for transitions
-# as described on
+# Default values for transitions as described on
 # http://design.ros2.org/articles/node_lifecycle.html
 
-# Externally available transitions.
-# When a node is in one of these primary states,
-# these transitions can be invoked.
+# Reserved [0-9], publicly available transitions.
+# When a node is in one of these primary states, these transitions can be
+# invoked.
+
+# This transition will instantiate the node, but will not run any code beyond
+# the constructor
 uint8 TRANSITION_CREATE = 0
+
+# The node’s onConfigure callback will be called to allow the node to load its
+# configuration and conduct any required setup
 uint8 TRANSITION_CONFIGURE = 1
+
+# The node’s callback onCleanup will be called in this transition to allow the
+# node to load its configuration and conduct any required setup
 uint8 TRANSITION_CLEANUP = 2
+
+# The node's callback onActivate will be executed to do any final preparations
+# to start executing
 uint8 TRANSITION_ACTIVATE = 3
+
+# The node's callback onDeactivate will be executed to do any cleanup to start
+# executing, and reverse the onActivate changes
 uint8 TRANSITION_DEACTIVATE = 4
+
+# This signals shutdown during an unconfigured state, the node's callback
+# onShutdown will be executed to do any cleanup necessary before destruction
 uint8 TRANSITION_UNCONFIGURED_SHUTDOWN  = 5
+
+# This signals shutdown during an inactive state, the node's callback onShutdown
+# will be executed to do any cleanup necessary before destruction
 uint8 TRANSITION_INACTIVE_SHUTDOWN = 6
+
+# This signals shutdown during an active state, the node's callback onShutdown
+# will be executed to do any cleanup necessary before destruction
 uint8 TRANSITION_ACTIVE_SHUTDOWN = 7
+
+# This transition will simply cause the deallocation of the node
 uint8 TRANSITION_DESTROY = 8
 
-# These transitions are not publically
-# available and cannot be invoked by a user.
-# The following transitions are implicitly
-# invoked based on the callback feedback
-# of the intermediate transition states.
+# Reserved [10-69], private transitions
+# These transitions are not publicly available and cannot be invoked by a user.
+# The following transitions are implicitly invoked based on the callback
+# feedback of the intermediate transition states.
 uint8 TRANSITION_ON_CONFIGURE_SUCCESS = 10
 uint8 TRANSITION_ON_CONFIGURE_FAILURE = 11
 uint8 TRANSITION_ON_CONFIGURE_ERROR = 12
@@ -44,14 +68,27 @@ uint8 TRANSITION_ON_ERROR_SUCCESS = 60
 uint8 TRANSITION_ON_ERROR_FAILURE = 61
 uint8 TRANSITION_ON_ERROR_ERROR = 62
 
-# These return values ought to be set
-# as a return value for each callback.
-# Depending on which return value,
-# the transition will be executed correctly
-# or fallback/error callbacks will be triggered.
+# Reserved [90-99]. Transition callback success values
+# These return values ought to be set as a return value for each callback.
+# Depending on which return value, the transition will be executed correctly or
+# fallback/error callbacks will be triggered.
+
+# The transition callback successfully performed its required functionality
 uint8 TRANSITION_CALLBACK_SUCCESS = 97
+
+# The transition callback failed to perform its required functionality
 uint8 TRANSITION_CALLBACK_FAILURE = 98
+
+# The transition callback encountered an error that requires special cleanup, if
+# possible
 uint8 TRANSITION_CALLBACK_ERROR = 99
 
+##
+## Fields
+##
+
+# The transition id from above definitions
 uint8 id
+
+# A text label of the transition
 string label

lifecycle_msgs/msg/TransitionDescription.msg

@@ -1,3 +1,8 @@
+# The transition id and label of this description
 Transition transition
+
+# The current state from which this transition transitions 
 State start_state
+
+# The desired target state of this transition
 State goal_state