more documentation

Author: MaximilianToe

include/up-cpp/client/usubscription/v3/RequestBuilder.h

@@ -42,7 +42,6 @@ struct USubscriptionOptions {
 /// This struct facilitates the construction of requests based on
 /// `USubscriptionOptions`, providing methods to build different requests.
 struct RequestBuilder {
-
 	/// @brief Constructs a RequestBuilder with the given subscription options.
 	///
 	/// @param options Subscription options to configure the requests. Defaults
@@ -91,15 +90,17 @@ struct RequestBuilder {
 	static FetchSubscribersRequest buildFetchSubscribersRequest(
 	    const v1::UUri& topic);
 
-	/// @brief Build notifications request for a given topic. Subscription change
-	///notifications MUST use topic SubscriptionsChange with resource id 0x8000,
-	///as per the protobuf definition.
+	/// @brief Build notifications request for a given topic. Subscription
+	/// change
+	/// notifications MUST use topic SubscriptionsChange with resource id
+	/// 0x8000, as per the protobuf definition.
 	///
 	/// @param topic The `v1::UUri` representing the topic to (un)register
-	///for/from.
+	/// for/from.
 	///
 	/// @return An `NotificationsRequest` configured for the specified topic.
-	static NotificationsRequest buildNotificationsRequest(const v1::UUri& topic);
+	static NotificationsRequest buildNotificationsRequest(
+	    const v1::UUri& topic);
 
 private:
 	USubscriptionOptions options_;  ///< Options used to configure the requests.

include/up-cpp/client/usubscription/v3/RpcClientUSubscription.h

@@ -46,10 +46,7 @@ namespace uprotocol::core::usubscription::v3 {
 using v3::SubscriptionRequest;
 using v3::UnsubscribeRequest;
 
-/// @brief Interface for uEntities to create subscriptions.
-///
-/// Like all L3 client APIs, the RpcClientUSubscription is a wrapper on top of
-/// the L2 Communication APIs and USubscription service.
+/// @brief Client which implements the USubscription interface
 struct RpcClientUSubscription : USubscription {
 	using RpcClientUSubscriptionOrStatus =
 	    utils::Expected<std::unique_ptr<RpcClientUSubscription>, v1::UStatus>;
@@ -59,54 +56,69 @@ struct RpcClientUSubscription : USubscription {
 	template <typename Response>
 	Response invokeResponse(communication::RpcClient rpc_client);
 
-	/// @brief Subscribe to the topic
+	/// @brief Subscribes from a given topic
 	///
+	/// @param subscription_request The request object containing the topic to
+	/// subscribe to
+	/// @return Returns a SubscriptionResponse on success and a UStatus else
 	utils::Expected<SubscriptionResponse, v1::UStatus> subscribe(
 	    const SubscriptionRequest& subscription_request) override;
 
-	/// @brief Unsubscribe from the topic
+	/// @brief Unsubscribes from a given topic
 	///
+	/// @param unsubscribe_request The request object containing the topic to
+	/// unsubscribe from
+	/// @return Returns an UnsubscribeResponse on success and a UStatus else
 	utils::Expected<UnsubscribeResponse, v1::UStatus> unsubscribe(
 	    const UnsubscribeRequest& unsubscribe_request) override;
 
-	/// @brief Fetch all subscriptions either by topic or subscriber
+	/// @brief Fetches the list of topics the client is subscribed to
 	///
+	/// @param fetch_subscriptions_request The request object
+	/// @return Returns a FetchSubscriptionsResponse on success and a UStatus
+	/// else
 	utils::Expected<FetchSubscriptionsResponse, v1::UStatus>
 	fetch_subscriptions(
 	    const FetchSubscriptionsRequest& fetch_subscriptions_request) override;
 
-	/// @brief Fetch all subscribers
+	/// @brief Fetches the list of subscribers for a given topic
 	///
+	/// @param fetch_subscribers_request The request object containing the topic
+	/// for which the subscribers are to be fetched
+	/// @return Returns a FetchSubscribersResponse on success and a UStatus else
 	utils::Expected<FetchSubscribersResponse, v1::UStatus> fetch_subscribers(
 	    const FetchSubscribersRequest& fetch_subscribers_request) override;
 
-	/// @brief Register for notifications
+	/// @brief Registers to receive notifications
 	///
+	/// @param register_notifications_request The request object containing
+	///	       the details to register for notifications
+	/// @return Returns a NotificationResponse on success and a UStatus else
 	utils::Expected<NotificationsResponse, v1::UStatus>
 	register_for_notifications(
 	    const NotificationsRequest& register_notifications_request) override;
 
-	/// @brief Unregister for notifications
+	/// @brief Unregisters from receiving notifications.
 	///
+	/// @param unregister_notifications_request The request object containing
+	///        the details needed to stop receiving notifications.
+	/// @return Returns a NotificationResponse on success and a UStatus else
 	utils::Expected<NotificationsResponse, v1::UStatus>
 	unregister_for_notifications(
 	    const NotificationsRequest& unregister_notifications_request) override;
 
 	/// @brief Constructor
 	///
-	/// @param transport Transport to register with.
+	/// @param transport Transport used to send messages
 	explicit RpcClientUSubscription(
 	    std::shared_ptr<transport::UTransport> transport)
 	    : transport_(std::move(transport)) {}
 
-	/// @brief Destructor
 	~RpcClientUSubscription() override = default;
 
 private:
-	// Transport
 	std::shared_ptr<transport::UTransport> transport_;
 
-	// URI info about the uSubscription service
 	USubscriptionUUriBuilder uuri_builder_;
 };
 

include/up-cpp/client/usubscription/v3/USubscription.h

@@ -19,11 +19,11 @@
 
 namespace uprotocol::core::usubscription::v3 {
 
-/**
- *
- */
+/// @brief Interface for uEntities to create subscriptions.
+///
+/// Like all L3 client APIs, the RpcClientUSubscription is a wrapper on top of
+/// the L2 Communication APIs and USubscription service.
 struct USubscription {
-
 	template <typename R>
 	using ResponseOrStatus = utils::Expected<R, v1::UStatus>;
 
@@ -45,7 +45,7 @@ struct USubscription {
 	virtual ResponseOrStatus<UnsubscribeResponse> unsubscribe(
 	    const UnsubscribeRequest& unsubscribe_request) = 0;
 
-	/// @brief fetches all topic the client is subscribed to from the backend
+	/// @brief fetches all topics the client is subscribed to from the backend
 	///
 	/// @param fetch_subscriptions_request
 	/// @return FetchSubscriptionsResponse on success and UStatus else
@@ -69,7 +69,8 @@ struct USubscription {
 
 	/// @brief fetches all subscribers for a given topic from the backend
 	///
-	/// @param fetch_subscriptions_request containing the topic for which the subscribers are fetched
+	/// @param fetch_subscriptions_request containing the topic for which the
+	/// subscribers are fetched
 	/// @return FetchSubscriptionsResponse on success and UStatus else
 	virtual ResponseOrStatus<FetchSubscribersResponse> fetch_subscribers(
 	    const FetchSubscribersRequest& fetch_subscribers_request) = 0;

include/up-cpp/communication/RpcClient.h

@@ -185,7 +185,7 @@ struct RpcClient {
 			return ResponseOrStatus<T>(
 			    UnexpectedStatus(message_or_status.error()));
 		}
-		
+
 		auto response_or_status = utils::ProtoConverter::extractFromProtobuf<T>(
 		    message_or_status.value());
 

include/up-cpp/utils/ProtoConverter.h

@@ -18,13 +18,13 @@ using TOrStatus = utils::Expected<T, v1::UStatus>;
 using UnexpectedStatus = utils::Unexpected<v1::UStatus>;
 using PayloadOrStatus =
     utils::Expected<datamodel::builder::Payload, v1::UStatus>;
+using core::usubscription::v3::FetchSubscribersRequest;
+using core::usubscription::v3::FetchSubscriptionsRequest;
+using core::usubscription::v3::NotificationsRequest;
 using uprotocol::core::usubscription::v3::SubscribeAttributes;
 using uprotocol::core::usubscription::v3::SubscriberInfo;
 using uprotocol::core::usubscription::v3::SubscriptionRequest;
 using uprotocol::core::usubscription::v3::UnsubscribeRequest;
-using core::usubscription::v3::FetchSubscriptionsRequest;
-using core::usubscription::v3::FetchSubscribersRequest;
-using core::usubscription::v3::NotificationsRequest;
 
 struct ProtoConverter {
 	/// @brief Converts std::chrono::time_point to google::protobuf::Timestamp
@@ -71,25 +71,31 @@ struct ProtoConverter {
 	///
 	/// @param topic the UUri of the topic to fetch subscriptions for
 	/// @return the built FetchSubscriptionsRequest
-	static FetchSubscriptionsRequest BuildFetchSubscriptionsRequest(const v1::UUri& topic);
+	static FetchSubscriptionsRequest BuildFetchSubscriptionsRequest(
+	    const v1::UUri& topic);
 
-	/// @brief Builds a FetchSubscriptionsRequest from the given subscriber information
+	/// @brief Builds a FetchSubscriptionsRequest from the given subscriber
+	/// information
 	///
-	/// @param subscriber the SubscriberInfo containing details of the subscriber
+	/// @param subscriber the SubscriberInfo containing details of the
+	/// subscriber
 	/// @return the built FetchSubscriptionsRequest
-	static FetchSubscriptionsRequest BuildFetchSubscriptionsRequest(const SubscriberInfo& subscriber);
+	static FetchSubscriptionsRequest BuildFetchSubscriptionsRequest(
+	    const SubscriberInfo& subscriber);
 
 	/// @brief Builds a FetchSubscribersRequest from the given topic
 	///
 	/// @param topic the UUri of the topic to fetch subscribers for
 	/// @return the built FetchSubscribersRequest
-	static FetchSubscribersRequest BuildFetchSubscribersRequest(const v1::UUri& topic);
+	static FetchSubscribersRequest BuildFetchSubscribersRequest(
+	    const v1::UUri& topic);
 
 	/// @brief Builds a NotificationsRequest from the given topic
 	///
 	/// @param topic the UUri of the topic to build a notification request for
 	/// @return the built NotificationsRequest
-	static NotificationsRequest BuildNotificationsRequest(const v1::UUri& topic);
+	static NotificationsRequest BuildNotificationsRequest(
+	    const v1::UUri& topic);
 
 	/// @brief Deserializes a protobuf message from a given payload.
 	///
@@ -144,8 +150,7 @@ struct ProtoConverter {
 			    UPayloadFormat_INT_MAX_SENTINEL_DO_NOT_USE_: {
 				v1::UStatus status;
 				status.set_code(v1::UCode::UNIMPLEMENTED);
-				status.set_message(
-				    "Unimplemented payload format.");
+				status.set_message("Unimplemented payload format.");
 				return TOrStatus<T>(UnexpectedStatus(status));
 			}
 			default: {

src/utils/ProtoConverter.cpp

@@ -84,32 +84,36 @@ UnsubscribeRequest ProtoConverter::BuildUnSubscribeRequest(
 	return unsubscribe_request;
 }
 
-FetchSubscriptionsRequest ProtoConverter::BuildFetchSubscriptionsRequest(const v1::UUri& topic) {
-    FetchSubscriptionsRequest fetch_subscriptions_request;
-    *fetch_subscriptions_request.mutable_topic() = topic;
+FetchSubscriptionsRequest ProtoConverter::BuildFetchSubscriptionsRequest(
+    const v1::UUri& topic) {
+	FetchSubscriptionsRequest fetch_subscriptions_request;
+	*fetch_subscriptions_request.mutable_topic() = topic;
 
-    return fetch_subscriptions_request;
+	return fetch_subscriptions_request;
 }
 
-FetchSubscriptionsRequest ProtoConverter::BuildFetchSubscriptionsRequest(const SubscriberInfo& subscriber) {
-    FetchSubscriptionsRequest fetch_subscriptions_request;
-    *fetch_subscriptions_request.mutable_subscriber() = subscriber;
+FetchSubscriptionsRequest ProtoConverter::BuildFetchSubscriptionsRequest(
+    const SubscriberInfo& subscriber) {
+	FetchSubscriptionsRequest fetch_subscriptions_request;
+	*fetch_subscriptions_request.mutable_subscriber() = subscriber;
 
-    return fetch_subscriptions_request;
+	return fetch_subscriptions_request;
 }
 
-FetchSubscribersRequest ProtoConverter::BuildFetchSubscribersRequest(const v1::UUri& topic) {
-    FetchSubscribersRequest fetch_subscribers_request;
-    *fetch_subscribers_request.mutable_topic() = topic;
+FetchSubscribersRequest ProtoConverter::BuildFetchSubscribersRequest(
+    const v1::UUri& topic) {
+	FetchSubscribersRequest fetch_subscribers_request;
+	*fetch_subscribers_request.mutable_topic() = topic;
 
-    return fetch_subscribers_request;
+	return fetch_subscribers_request;
 }
 
-NotificationsRequest ProtoConverter::BuildNotificationsRequest(const v1::UUri& topic) {
-    NotificationsRequest notifications_request;
-    *notifications_request.mutable_topic() = topic;
+NotificationsRequest ProtoConverter::BuildNotificationsRequest(
+    const v1::UUri& topic) {
+	NotificationsRequest notifications_request;
+	*notifications_request.mutable_topic() = topic;
 
-    return notifications_request;
+	return notifications_request;
 }
 
 }  // namespace uprotocol::utils