feat(doc): add doc comments

Co-authored-by: Luca Arato <luca.arato@secomind.com>
Signed-off-by: Luca Arato <luca.arato@secomind.com>

proto/astarteplatform/msghub/message_hub_service.proto

@@ -42,10 +42,10 @@ service MessageHub {
   rpc AddInterfaces(InterfacesJson) returns (google.protobuf.Empty){}
   /* This function should be used to remove one or more interfaces from an instance of the Astarte message hub. */
   rpc RemoveInterfaces(InterfacesName) returns (google.protobuf.Empty){}
-  /*  */
+  /* Get properties associated with the passed interfaces. */
   rpc GetProperties(InterfacesName) returns (StoredProperties){}
-  /*  */
+  /* Get all the properties, allowing also filtering by interface ownership. */
   rpc GetAllProperties(StoredPropertiesFilter) returns (StoredProperties){}
-  /*  */
+  /* Get a property defined by the passed interface and path. */
   rpc GetProperty(PropertyIdentifier) returns (Property) {}
 }

proto/astarteplatform/msghub/property.proto

@@ -25,37 +25,40 @@ package astarteplatform.msghub;
 
 import "astarteplatform/msghub/astarte_type.proto";
 
-/*  */
+/* Enum representing an Astarte interface ownership. */
 enum Ownership {
   DEVICE = 0;
   SERVER = 1;
 }
 
-/*  */
+/* A message representing the property value associated to a certain interface and path. */
 message Property {
-  string path = 1;
-  AstarteDataTypeIndividual value = 2;
+  string path = 1;                      // Property path.
+  AstarteDataTypeIndividual value = 2;  // Astarte data.
 }
 
-/* */
+/* A message containing all the properties values and information associated to a given astarte interface. */
 message InterfaceProperties {
-  Ownership ownership = 1;
-  uint32 version_major = 2;
-  repeated Property properties = 3;
+  Ownership ownership = 1;            // Interface ownership.
+  uint32 version_major = 2;           // Interface major version.
+  repeated Property properties = 3;   // A list of Properties values.
 }
 
-/*  */
+/* This message is the response to the GetProperties rpc method. */
 message StoredProperties {
-  map<string, InterfaceProperties> interface_properties = 1;
+  map<string, InterfaceProperties> interface_properties = 1; // Map interface names to interface property data.
 }
 
-/*  */
+/* This message is the request to the GetAllProperties rpc.
+ * If the ownership is not specified, all the interfaces are retrieved, both device and server owned.
+ * Otherwise, only the interfaces with the specified interfaces are retrieved.
+ */
 message StoredPropertiesFilter {
-  optional Ownership ownership = 1;
+  optional Ownership ownership = 1;   // Optional field representing the ownership of the interface to retrieve.
 }
 
-/*  */
+/* This message is the request for a single property identified by interface name and path. */
 message PropertyIdentifier {
-  string interface_name = 1;
-  string path = 2;
+  string interface_name = 1;    // Interface name.
+  string path = 2;              // Property path.
 }

python/astarteplatform/msghub/message_hub_service_pb2_grpc.py

@@ -46,16 +46,16 @@ def __init__(self, channel):
         self.GetProperties = channel.unary_unary(
                 '/astarteplatform.msghub.MessageHub/GetProperties',
                 request_serializer=astarteplatform_dot_msghub_dot_interface__pb2.InterfacesName.SerializeToString,
-                response_deserializer=astarteplatform_dot_msghub_dot_property__pb2.GetPropertiesResponse.FromString,
+                response_deserializer=astarteplatform_dot_msghub_dot_property__pb2.StoredProperties.FromString,
                 _registered_method=True)
         self.GetAllProperties = channel.unary_unary(
                 '/astarteplatform.msghub.MessageHub/GetAllProperties',
-                request_serializer=astarteplatform_dot_msghub_dot_property__pb2.GetAllPropertiesRequest.SerializeToString,
-                response_deserializer=astarteplatform_dot_msghub_dot_property__pb2.GetPropertiesResponse.FromString,
+                request_serializer=astarteplatform_dot_msghub_dot_property__pb2.StoredPropertiesFilter.SerializeToString,
+                response_deserializer=astarteplatform_dot_msghub_dot_property__pb2.StoredProperties.FromString,
                 _registered_method=True)
         self.GetProperty = channel.unary_unary(
                 '/astarteplatform.msghub.MessageHub/GetProperty',
-                request_serializer=astarteplatform_dot_msghub_dot_property__pb2.GetPropertyRequest.SerializeToString,
+                request_serializer=astarteplatform_dot_msghub_dot_property__pb2.PropertyIdentifier.SerializeToString,
                 response_deserializer=astarteplatform_dot_msghub_dot_property__pb2.Property.FromString,
                 _registered_method=True)
 
@@ -151,16 +151,16 @@ def add_MessageHubServicer_to_server(servicer, server):
             'GetProperties': grpc.unary_unary_rpc_method_handler(
                     servicer.GetProperties,
                     request_deserializer=astarteplatform_dot_msghub_dot_interface__pb2.InterfacesName.FromString,
-                    response_serializer=astarteplatform_dot_msghub_dot_property__pb2.GetPropertiesResponse.SerializeToString,
+                    response_serializer=astarteplatform_dot_msghub_dot_property__pb2.StoredProperties.SerializeToString,
             ),
             'GetAllProperties': grpc.unary_unary_rpc_method_handler(
                     servicer.GetAllProperties,
-                    request_deserializer=astarteplatform_dot_msghub_dot_property__pb2.GetAllPropertiesRequest.FromString,
-                    response_serializer=astarteplatform_dot_msghub_dot_property__pb2.GetPropertiesResponse.SerializeToString,
+                    request_deserializer=astarteplatform_dot_msghub_dot_property__pb2.StoredPropertiesFilter.FromString,
+                    response_serializer=astarteplatform_dot_msghub_dot_property__pb2.StoredProperties.SerializeToString,
             ),
             'GetProperty': grpc.unary_unary_rpc_method_handler(
                     servicer.GetProperty,
-                    request_deserializer=astarteplatform_dot_msghub_dot_property__pb2.GetPropertyRequest.FromString,
+                    request_deserializer=astarteplatform_dot_msghub_dot_property__pb2.PropertyIdentifier.FromString,
                     response_serializer=astarteplatform_dot_msghub_dot_property__pb2.Property.SerializeToString,
             ),
     }
@@ -325,7 +325,7 @@ def GetProperties(request,
             target,
             '/astarteplatform.msghub.MessageHub/GetProperties',
             astarteplatform_dot_msghub_dot_interface__pb2.InterfacesName.SerializeToString,
-            astarteplatform_dot_msghub_dot_property__pb2.GetPropertiesResponse.FromString,
+            astarteplatform_dot_msghub_dot_property__pb2.StoredProperties.FromString,
             options,
             channel_credentials,
             insecure,
@@ -351,8 +351,8 @@ def GetAllProperties(request,
             request,
             target,
             '/astarteplatform.msghub.MessageHub/GetAllProperties',
-            astarteplatform_dot_msghub_dot_property__pb2.GetAllPropertiesRequest.SerializeToString,
-            astarteplatform_dot_msghub_dot_property__pb2.GetPropertiesResponse.FromString,
+            astarteplatform_dot_msghub_dot_property__pb2.StoredPropertiesFilter.SerializeToString,
+            astarteplatform_dot_msghub_dot_property__pb2.StoredProperties.FromString,
             options,
             channel_credentials,
             insecure,
@@ -378,7 +378,7 @@ def GetProperty(request,
             request,
             target,
             '/astarteplatform.msghub.MessageHub/GetProperty',
-            astarteplatform_dot_msghub_dot_property__pb2.GetPropertyRequest.SerializeToString,
+            astarteplatform_dot_msghub_dot_property__pb2.PropertyIdentifier.SerializeToString,
             astarteplatform_dot_msghub_dot_property__pb2.Property.FromString,
             options,
             channel_credentials,

python/astarteplatform/msghub/property_pb2.pyi

@@ -32,7 +32,7 @@ class InterfaceProperties(_message.Message):
     properties: _containers.RepeatedCompositeFieldContainer[Property]
     def __init__(self, ownership: _Optional[_Union[Ownership, str]] = ..., version_major: _Optional[int] = ..., properties: _Optional[_Iterable[_Union[Property, _Mapping]]] = ...) -> None: ...
 
-class GetPropertiesResponse(_message.Message):
+class StoredProperties(_message.Message):
     __slots__ = ("interface_properties",)
     class InterfacePropertiesEntry(_message.Message):
         __slots__ = ("key", "value")
@@ -45,13 +45,13 @@ class GetPropertiesResponse(_message.Message):
     interface_properties: _containers.MessageMap[str, InterfaceProperties]
     def __init__(self, interface_properties: _Optional[_Mapping[str, InterfaceProperties]] = ...) -> None: ...
 
-class GetAllPropertiesRequest(_message.Message):
+class StoredPropertiesFilter(_message.Message):
     __slots__ = ("ownership",)
     OWNERSHIP_FIELD_NUMBER: _ClassVar[int]
     ownership: Ownership
     def __init__(self, ownership: _Optional[_Union[Ownership, str]] = ...) -> None: ...
 
-class GetPropertyRequest(_message.Message):
+class PropertyIdentifier(_message.Message):
     __slots__ = ("interface_name", "path")
     INTERFACE_NAME_FIELD_NUMBER: _ClassVar[int]
     PATH_FIELD_NUMBER: _ClassVar[int]