From 726014069d0f2bece14e91d2ed0e1e9fb142a24b Mon Sep 17 00:00:00 2001 From: Riccardo Gallo Date: Thu, 5 Dec 2024 12:26:39 +0100 Subject: [PATCH] feat(doc): add doc comments Co-authored-by: Luca Arato Signed-off-by: Luca Arato --- proto/astarteplatform/msghub/interface.proto | 2 +- .../msghub/message_hub_service.proto | 4 +-- proto/astarteplatform/msghub/property.proto | 29 ++++++++++-------- .../msghub/message_hub_service_pb2_grpc.py | 4 +-- .../src/astarteplatform.msghub.rs | 30 ++++++++++++------- 5 files changed, 42 insertions(+), 27 deletions(-) diff --git a/proto/astarteplatform/msghub/interface.proto b/proto/astarteplatform/msghub/interface.proto index e13e176..cf76d08 100644 --- a/proto/astarteplatform/msghub/interface.proto +++ b/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; diff --git a/proto/astarteplatform/msghub/message_hub_service.proto b/proto/astarteplatform/msghub/message_hub_service.proto index 319dc30..be64ecd 100644 --- a/proto/astarteplatform/msghub/message_hub_service.proto +++ b/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) {} diff --git a/proto/astarteplatform/msghub/property.proto b/proto/astarteplatform/msghub/property.proto index 3a0081a..3d10c02 100644 --- a/proto/astarteplatform/msghub/property.proto +++ b/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 interface_properties = 1; + map 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. } diff --git a/python/astarteplatform/msghub/message_hub_service_pb2_grpc.py b/python/astarteplatform/msghub/message_hub_service_pb2_grpc.py index ec59c24..bd90efe 100644 --- a/python/astarteplatform/msghub/message_hub_service_pb2_grpc.py +++ b/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!') diff --git a/rust/astarte-message-hub-proto/src/astarteplatform.msghub.rs b/rust/astarte-message-hub-proto/src/astarteplatform.msghub.rs index 10bb93a..670425b 100644 --- a/rust/astarte-message-hub-proto/src/astarteplatform.msghub.rs +++ b/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, } -/// +/// 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, } -/// +/// 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, @@ -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, @@ -654,7 +664,7 @@ pub mod message_hub_server { &self, request: tonic::Request, ) -> std::result::Result, tonic::Status>; - /// + /// Get properties associated with the passed interfaces. async fn get_properties( &self, request: tonic::Request, @@ -662,7 +672,7 @@ pub mod message_hub_server { tonic::Response, tonic::Status, >; - /// + /// Get all the properties, allowing also filtering by interface ownership. async fn get_all_properties( &self, request: tonic::Request,