Update documented expectations for GIDs

* Clarify that GIDs are globally unique within a ROS domain.
* Specify that any unused bytes in the GID should be set to zero (e.g. in cases where not all 24 bytes are used).
  This allows application code to directly compare GIDs without having to ask the middleware.

Signed-off-by: Jacob Perron <[email protected]>

rmw/include/rmw/rmw.h

@@ -2937,7 +2937,7 @@ rmw_count_subscribers(
   const char * topic_name,
   size_t * count);
 
-/// Get the unique identifier (gid) of a publisher.
+/// Get the globally unique identifier (GID) of a publisher.
 /**
  * <hr>
  * Attribute          | Adherence
@@ -2953,14 +2953,20 @@ rmw_count_subscribers(
  *   Publishers are thread-safe objects, and so are all operations on them except for
  *   finalization.
  *   Therefore, it is safe to get the unique identifier from the same publisher concurrently.
- *   However, access to the gid is not synchronized.
+ *   However, access to the GID is not synchronized.
  *   It is not safe to read or write `gid` while rmw_get_gid_for_publisher() uses it.
  *
  * \pre Given `publisher` must be a valid publisher, as returned by rmw_create_publisher().
  *
- * \param[in] publisher Publisher to get a gid from.
+ * This is expected to be globally unique within a ROS domain.
+ * The identifier should be the same when reported both locally (where the entity was created)
+ * and on remote hosts or processes.
+ *
+ * \param[in] publisher Publisher to get a GID from.
  * \param[out] gid Publisher's unique identifier, populated on success
  *   but left unchanged on failure.
+ *   If the GID from the middleware is smaller than RMW_GID_STORAGE_SIZE, any bytes not used
+ *   should be set to zero.
  * \return `RMW_RET_OK` if successful, or
  * \return `RMW_RET_INVALID_ARGUMENT` if `publisher` is NULL, or
  * \return `RMW_RET_INVALID_ARGUMENT` if `gid` is NULL, or
@@ -2973,7 +2979,7 @@ RMW_WARN_UNUSED
 rmw_ret_t
 rmw_get_gid_for_publisher(const rmw_publisher_t * publisher, rmw_gid_t * gid);
 
-/// Get the unique identifier (gid) of a service client.
+/// Get the globally unique identifier (GID) of a service client.
 /**
  * <hr>
  * Attribute          | Adherence
@@ -2989,14 +2995,19 @@ rmw_get_gid_for_publisher(const rmw_publisher_t * publisher, rmw_gid_t * gid);
  *   Service clients are thread-safe objects, and so are all operations on them except for
  *   finalization.
  *   Therefore, it is safe to get the unique identifier from the same client concurrently.
- *   However, access to the gid is not synchronized.
+ *   However, access to the GID is not synchronized.
  *   It is not safe to read or write `gid` while rmw_get_gid_for_client() uses it.
  *
  * \pre Given `client` must be a valid service client, as returned by rmw_create_client().
  *
- * \param[in] client Service client to get a gid from.
+ * This is expected to be globally unique within a ROS domain.
+ * The identifier should be the same when reported both locally (where the entity was created)
+ * and on remote hosts or processes.
+ * \param[in] client Service client to get a GID from.
  * \param[out] gid Service client's unique identifier, populated on success
  *   but left unchanged on failure.
+ *   If the GID from the middleware is smaller than RMW_GID_STORAGE_SIZE, any bytes not used
+ *   should be set to zero.
  * \return `RMW_RET_OK` if successful, or
  * \return `RMW_RET_INVALID_ARGUMENT` if `publisher` is NULL, or
  * \return `RMW_RET_INVALID_ARGUMENT` if `gid` is NULL, or
@@ -3009,7 +3020,7 @@ RMW_WARN_UNUSED
 rmw_ret_t
 rmw_get_gid_for_client(const rmw_client_t * client, rmw_gid_t * gid);
 
-/// Check if two unique identifiers (gids) are equal.
+/// Check if two globally unique identifiers (GIDs) are equal.
 /**
  * <hr>
  * Attribute          | Adherence
@@ -3023,14 +3034,14 @@ rmw_get_gid_for_client(const rmw_client_t * client, rmw_gid_t * gid);
  *
  * \par Thread-safety
  *   Unique identifier comparison is a reentrant function, but:
- *   - Access to both gids is read-only but it is not synchronized.
+ *   - Access to both GIDs is read-only but it is not synchronized.
  *     Concurrent `gid1` and `gid2` reads are safe, but concurrent reads and writes are not.
  *   - Access to primitive data-type arguments is not synchronized.
  *     It is not safe to read or write `result` while rmw_compare_gids_equal() uses it.
  *
  * \param[in] gid1 First unique identifier to compare.
  * \param[in] gid2 Second unique identifier to compare.
- * \param[out] result true if both gids are equal, false otherwise.
+ * \param[out] result true if both GIDs are equal, false otherwise.
  * \return `RMW_RET_OK` if successful, or
  * \return `RMW_RET_INVALID_ARGUMENT` if `gid1` or `gid2` is NULL, or
  * \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the implementation

rmw/include/rmw/types.h

@@ -41,13 +41,22 @@ extern "C"
 // implementation. It may need to be increased in the future.
 #define RMW_GID_STORAGE_SIZE 24u
 
-/// ROS graph ID of the topic
+/// Globally unique identifier for a ROS graph entity
+/**
+ * This is expected to be globally unique within a ROS domain.
+ * The identifier should be the same when reported both locally (where the entity was created)
+ * and on remote hosts or processes.
+ */
 typedef struct RMW_PUBLIC_TYPE rmw_gid_s
 {
   /// Name of the rmw implementation
   const char * implementation_identifier;
 
-  /// Bype data Gid value
+  /// Byte data GID value
+  /**
+   * If the GID from the middleware is smaller than RMW_GID_STORAGE_SIZE, any bytes not used
+   * should be set to zero.
+   */
   uint8_t data[RMW_GID_STORAGE_SIZE];
 } rmw_gid_t;