Address peer review comments

Signed-off-by: Michel Hidalgo <[email protected]>

proto2ros/README.md

@@ -1,5 +1,5 @@
 # Protobuf to ROS 2 interoperability 
 
-`proto2ros` helps maintain an interoperability layer between Protobuf dependent and ROS 2 aware code by generating equivalent ROS 2 message definitions given source Protobuf message definitions, as well bi-directional conversion APIs in relevant languages (such as Python).
+`proto2ros` helps maintain an interoperability layer between Protobuf dependent and ROS 2 aware code by generating equivalent ROS 2 message definitions given source Protobuf message definitions, as well bi-directional conversion APIs in relevant languages (such as Python). To date, Protobuf syntax versions 2 and 3 are supported but only syntax version 3 has been extensively tested.
 
 Continue on to the [`ros_utilities` wiki](https://github.com/bdaiinstitute/ros_utilities/wiki) for further reference.

proto2ros/msg/Any.msg

@@ -1,6 +1,6 @@
 # Copyright (c) 2023 Boston Dynamics AI Institute LLC. All rights reserved.
 
-# A type erased ROS 2 message.
+# A dynamically typed ROS 2 message.
 
-string  type    # ROS 2 message type name
-uint8[] value   # Serialized ROS 2 message instance
+string  type_name  # ROS 2 message type name
+uint8[] value      # Serialized ROS 2 message instance

proto2ros/msg/AnyProto.msg

@@ -1,6 +1,7 @@
 # Copyright (c) 2023 Boston Dynamics AI Institute LLC. All rights reserved.
 
-# A type erased Protobuf message. Equivalent to the google.protobuf.Any message.
+# A dynamically typed Protobuf message. Equivalent to the google.protobuf.Any message.
+# See https://protobuf.dev/reference/protobuf/google.protobuf/#any for further reference.
 
 string  type_url    # Protobuf message type URL.
 uint8[] value       # Packed Protobuf message instance.

proto2ros/msg/Bytes.msg

@@ -1,3 +1,6 @@
 # Copyright (c) 2023 Boston Dynamics AI Institute LLC. All rights reserved.
 
+# A binary blob. Equivalent to the google.protobuf.BytesValue message, also used to map repeated bytes fields to
+# the ROS 2 domain. See https://protobuf.dev/reference/protobuf/google.protobuf/#bytes-value for further reference.
+
 uint8[] data

proto2ros/msg/List.msg

@@ -1,3 +1,6 @@
 # Copyright (c) 2023 Boston Dynamics AI Institute LLC. All rights reserved.
 
+# A list of dynamically typed values. Equivalent to the google.protobuf.ListValue message.
+# See https://protobuf.dev/reference/protobuf/google.protobuf/#list-value for further reference.
+
 proto2ros/Value[] values

proto2ros/msg/Struct.msg

@@ -1,3 +1,6 @@
 # Copyright (c) 2023 Boston Dynamics AI Institute LLC. All rights reserved.
 
+# A structured data value with dynamically typed fields. Equivalent to the google.protobuf.Struct message.
+# See https://protobuf.dev/reference/protobuf/google.protobuf/#struct for further reference.
+
 proto2ros/StructEntry[] fields

proto2ros/msg/StructEntry.msg

@@ -1,4 +1,8 @@
 # Copyright (c) 2023 Boston Dynamics AI Institute LLC. All rights reserved.
 
+# Key-value entries in the proto2ros/Struct ROS 2 message. Equivalent to
+# the auxiliary Protobuf message used over-the-wire representation of the
+# google.protobuf.Struct message.
+
 string key
 proto2ros/Value value

proto2ros/msg/Value.msg

@@ -1,5 +1,8 @@
 # Copyright (c) 2023 Boston Dynamics AI Institute LLC. All rights reserved.
 
+# A dynamically typed (scalar or composite) value. Equivalent to the google.protobuf.Value message.
+# See https://protobuf.dev/reference/protobuf/google.protobuf/#value for further reference.
+
 int8 NO_VALUE_SET=0
 int8 NUMBER_VALUE_SET=1
 int8 STRING_VALUE_SET=2

proto2ros/proto2ros/descriptors/utilities.py

@@ -5,11 +5,13 @@
 
 Many of these utilities trade in terms of paths and locations.
 
-Paths are sequences of numbers that identify an arbitrarily nested field in a Protobuf message.
+Paths are sequences of numbers that refere to an arbitrarily nested value in a Protobuf message.
 Each part of a path is one or two numbers: the field number if it is not a repeated field, and
 the field number and item index if it is. For example, ``[4, 1, 3]`` can be (but it ultimately
 depends on the concrete Protobuf message type) a path to the third item of field number 1 of
-the message field number 4.
+the (sub)message that is field number 4 of the message this path applies to. This path can thus
+be used to access the target value: take field number 4 of the message, it is a message itself;
+then take field number 1 of this (sub)message, it is a repeated field; then take item 3.
 
 Locations refer to portions of a .proto source file. Locations specify a path to the descriptors
 of the constructs that are defined in the corresponding portion. See

proto2ros/proto2ros/equivalences.py

@@ -4,10 +4,11 @@
 This module provides APIs to extract Protobuf <-> ROS message equivalences.
 
 These equivalences are defined in terms of Protobuf composite descriptors
-and ROS message specifications. See
+and ROS message specifications. See Protobuf descriptor messages and ROS 2
+``MessageSpecification`` class definition and documentation in
 https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/descriptor.proto
-and https://github.com/ros2/rosidl/blob/rolling/rosidl_adapter/rosidl_adapter/parser.py#L386
-for further reference.
+and https://github.com/ros2/rosidl/blob/rolling/rosidl_adapter/rosidl_adapter/parser.py
+respectively for further reference.
 """
 
 import dataclasses