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/interface.proto

@@ -33,7 +33,7 @@ message InterfacesName {
   repeated string names = 1; // An array of interfaces' names
 }
 
-/*  */
+/* Enum representing an Astarte interface ownership. */
 enum Ownership {
   DEVICE = 0;
   SERVER = 1;

proto/astarteplatform/msghub/message_hub_service.proto

@@ -42,9 +42,9 @@ 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){}
   /*  */
   rpc GetProperty(PropertyIdentifier) returns (Property) {}

proto/astarteplatform/msghub/property.proto

@@ -27,7 +27,9 @@ import "astarteplatform/msghub/astarte_message.proto";
 import "astarteplatform/msghub/astarte_type.proto";
 import "astarteplatform/msghub/interface.proto";
 
-/*  */
+/* A message representing the property value associated to a certain interface and path.
+ * Required for the `GetProperty` method that could need to return an unset property.
+ */
 message Property {
   string path = 1;                      // Property path.
   oneof value {                         // Astarte data.
@@ -36,25 +38,28 @@ message Property {
   }
 }
 
-/* */
+/* A message containing all the properties values and information associated to a given astarte interface. */
 message InterfaceProperties {
-  Ownership ownership = 1;
-  int32 version_major = 2;
-  repeated Property properties = 3;
+  Ownership ownership = 1;            // Interface ownership.
+  int32 version_major = 2;           // Interface major version.
+  repeated Property properties = 3;   // A list of Properties values. These properties should not be unset
 }
 
-/*  */
+/* 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

@@ -100,14 +100,14 @@ def RemoveInterfaces(self, request, context):
         raise NotImplementedError('Method not implemented!')
 
     def GetProperties(self, request, context):
-        """
+        """Get properties associated with the passed interfaces. 
         """
         context.set_code(grpc.StatusCode.UNIMPLEMENTED)
         context.set_details('Method not implemented!')
         raise NotImplementedError('Method not implemented!')
 
     def GetAllProperties(self, request, context):
-        """
+        """Get all the properties, allowing also filtering by interface ownership. 
         """
         context.set_code(grpc.StatusCode.UNIMPLEMENTED)
         context.set_details('Method not implemented!')

rust/astarte-message-hub-proto/src/astarteplatform.msghub.rs

@@ -229,7 +229,7 @@ pub struct InterfacesName {
     #[prost(string, repeated, tag = "1")]
     pub names: ::prost::alloc::vec::Vec<::prost::alloc::string::String>,
 }
-///
+/// Enum representing an Astarte interface ownership.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)]
 #[repr(i32)]
 pub enum Ownership {
@@ -256,7 +256,8 @@ impl Ownership {
         }
     }
 }
-///
+/// A message representing the property value associated to a certain interface and path.
+/// Required for the `GetProperty` method that could need to return an unset property.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct Property {
@@ -281,40 +282,49 @@ pub mod property {
         AstarteUnset(super::AstarteUnset),
     }
 }
-///
+/// A message containing all the properties values and information associated to a given astarte interface.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct InterfaceProperties {
+    /// Interface ownership.
     #[prost(enumeration = "Ownership", tag = "1")]
     pub ownership: i32,
+    /// Interface major version.
     #[prost(int32, tag = "2")]
     pub version_major: i32,
+    /// A list of Properties values. These properties should not be unset
     #[prost(message, repeated, tag = "3")]
     pub properties: ::prost::alloc::vec::Vec<Property>,
 }
-///
+/// This message is the response to the GetProperties rpc method.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct StoredProperties {
+    /// Map interface names to interface property data.
     #[prost(map = "string, message", tag = "1")]
     pub interface_properties: ::std::collections::HashMap<
         ::prost::alloc::string::String,
         InterfaceProperties,
     >,
 }
-///
+/// 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.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct StoredPropertiesFilter {
+    /// Optional field representing the ownership of the interface to retrieve.
     #[prost(enumeration = "Ownership", optional, tag = "1")]
     pub ownership: ::core::option::Option<i32>,
 }
-///
+/// This message is the request for a single property identified by interface name and path.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct PropertyIdentifier {
+    /// Interface name.
     #[prost(string, tag = "1")]
     pub interface_name: ::prost::alloc::string::String,
+    /// Property path.
     #[prost(string, tag = "2")]
     pub path: ::prost::alloc::string::String,
 }
@@ -529,7 +539,7 @@ pub mod message_hub_client {
                 );
             self.inner.unary(req, path, codec).await
         }
-        ///
+        /// Get properties associated with the passed interfaces.
         pub async fn get_properties(
             &mut self,
             request: impl tonic::IntoRequest<super::InterfacesName>,
@@ -557,7 +567,7 @@ pub mod message_hub_client {
                 );
             self.inner.unary(req, path, codec).await
         }
-        ///
+        /// Get all the properties, allowing also filtering by interface ownership.
         pub async fn get_all_properties(
             &mut self,
             request: impl tonic::IntoRequest<super::StoredPropertiesFilter>,
@@ -654,15 +664,15 @@ pub mod message_hub_server {
             &self,
             request: tonic::Request<super::InterfacesName>,
         ) -> std::result::Result<tonic::Response<::pbjson_types::Empty>, tonic::Status>;
-        ///
+        /// Get properties associated with the passed interfaces.
         async fn get_properties(
             &self,
             request: tonic::Request<super::InterfacesName>,
         ) -> std::result::Result<
             tonic::Response<super::StoredProperties>,
             tonic::Status,
         >;
-        ///
+        /// Get all the properties, allowing also filtering by interface ownership.
         async fn get_all_properties(
             &self,
             request: tonic::Request<super::StoredPropertiesFilter>,