@@ -3039,7 +3039,7 @@ rmw_count_services(
30393039 const char * service_name ,
30403040 size_t * count );
30413041
3042- /// Get the unique identifier (gid ) of a publisher.
3042+ /// Get the globally unique identifier (GID ) of a publisher.
30433043/**
30443044 * <hr>
30453045 * Attribute | Adherence
@@ -3055,12 +3055,16 @@ rmw_count_services(
30553055 * Publishers are thread-safe objects, and so are all operations on them except for
30563056 * finalization.
30573057 * Therefore, it is safe to get the unique identifier from the same publisher concurrently.
3058- * However, access to the gid is not synchronized.
3058+ * However, access to the GID is not synchronized.
30593059 * It is not safe to read or write `gid` while rmw_get_gid_for_publisher() uses it.
30603060 *
30613061 * \pre Given `publisher` must be a valid publisher, as returned by rmw_create_publisher().
30623062 *
3063- * \param[in] publisher Publisher to get a gid from.
3063+ * This is expected to be globally unique within a ROS domain.
3064+ * The identifier should be the same when reported both locally (where the entity was created)
3065+ * and on remote hosts or processes.
3066+ *
3067+ * \param[in] publisher Publisher to get a GID from.
30643068 * \param[out] gid Publisher's unique identifier, populated on success
30653069 * but left unchanged on failure.
30663070 * \return `RMW_RET_OK` if successful, or
@@ -3075,7 +3079,7 @@ RMW_WARN_UNUSED
30753079rmw_ret_t
30763080rmw_get_gid_for_publisher (const rmw_publisher_t * publisher , rmw_gid_t * gid );
30773081
3078- /// Get the unique identifier (gid ) of a service client.
3082+ /// Get the globally unique identifier (GID ) of a service client.
30793083/**
30803084 * <hr>
30813085 * Attribute | Adherence
@@ -3091,12 +3095,15 @@ rmw_get_gid_for_publisher(const rmw_publisher_t * publisher, rmw_gid_t * gid);
30913095 * Service clients are thread-safe objects, and so are all operations on them except for
30923096 * finalization.
30933097 * Therefore, it is safe to get the unique identifier from the same client concurrently.
3094- * However, access to the gid is not synchronized.
3098+ * However, access to the GID is not synchronized.
30953099 * It is not safe to read or write `gid` while rmw_get_gid_for_client() uses it.
30963100 *
30973101 * \pre Given `client` must be a valid service client, as returned by rmw_create_client().
30983102 *
3099- * \param[in] client Service client to get a gid from.
3103+ * This is expected to be globally unique within a ROS domain.
3104+ * The identifier should be the same when reported both locally (where the entity was created)
3105+ * and on remote hosts or processes.
3106+ * \param[in] client Service client to get a GID from.
31003107 * \param[out] gid Service client's unique identifier, populated on success
31013108 * but left unchanged on failure.
31023109 * \return `RMW_RET_OK` if successful, or
@@ -3111,7 +3118,7 @@ RMW_WARN_UNUSED
31113118rmw_ret_t
31123119rmw_get_gid_for_client (const rmw_client_t * client , rmw_gid_t * gid );
31133120
3114- /// Check if two unique identifiers (gids ) are equal.
3121+ /// Check if two globally unique identifiers (GIDs ) are equal.
31153122/**
31163123 * <hr>
31173124 * Attribute | Adherence
@@ -3125,14 +3132,14 @@ rmw_get_gid_for_client(const rmw_client_t * client, rmw_gid_t * gid);
31253132 *
31263133 * \par Thread-safety
31273134 * Unique identifier comparison is a reentrant function, but:
3128- * - Access to both gids is read-only but it is not synchronized.
3135+ * - Access to both GIDs is read-only but it is not synchronized.
31293136 * Concurrent `gid1` and `gid2` reads are safe, but concurrent reads and writes are not.
31303137 * - Access to primitive data-type arguments is not synchronized.
31313138 * It is not safe to read or write `result` while rmw_compare_gids_equal() uses it.
31323139 *
31333140 * \param[in] gid1 First unique identifier to compare.
31343141 * \param[in] gid2 Second unique identifier to compare.
3135- * \param[out] result true if both gids are equal, false otherwise.
3142+ * \param[out] result true if both GIDs are equal, false otherwise.
31363143 * \return `RMW_RET_OK` if successful, or
31373144 * \return `RMW_RET_INVALID_ARGUMENT` if `gid1` or `gid2` is NULL, or
31383145 * \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the implementation
0 commit comments