From 9b71cc49f5822c87a0eead584ff934c943b1c260 Mon Sep 17 00:00:00 2001
From: Alessandro Simovic <alessandro@auterion.com>
Date: Tue, 31 Jan 2023 17:26:45 +0100
Subject: [PATCH] add missing documentation for winch/gripper items

---
 protos/gripper/gripper.proto |  9 +++++++++
 protos/winch/winch.proto     | 15 +++++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/protos/gripper/gripper.proto b/protos/gripper/gripper.proto
index 9463312e..50a3a7fb 100644
--- a/protos/gripper/gripper.proto
+++ b/protos/gripper/gripper.proto
@@ -5,6 +5,9 @@ package mavsdk.rpc.gripper;
 option java_package = "io.mavsdk.gripper";
 option java_outer_classname = "GripperProto";
 
+/*
+ * Allows users to send gripper actions.
+ */
 service GripperService {
     /*
      * Gripper grab cargo.
@@ -17,6 +20,12 @@ service GripperService {
     rpc Release(ReleaseRequest) returns(ReleaseResponse) {}
 }
 
+/*
+ * Gripper Actions.
+ *
+ * Available gripper actions are defined in mavlink under
+ * https://mavlink.io/en/messages/common.html#GRIPPER_ACTIONS
+ */
 enum GripperAction {
     GRIPPER_ACTION_RELEASE = 0; // Open the gripper to release the cargo
     GRIPPER_ACTION_GRAB = 1; // Close the gripper and grab onto cargo
diff --git a/protos/winch/winch.proto b/protos/winch/winch.proto
index afdb3dcb..9f7e9478 100644
--- a/protos/winch/winch.proto
+++ b/protos/winch/winch.proto
@@ -7,6 +7,10 @@ import "mavsdk_options.proto";
 option java_package = "io.mavsdk.winch";
 option java_outer_classname = "WinchProto";
 
+/*
+ * Allows users to send winch actions, as well as receive status information from winch systems.
+ *
+ */
 service WinchService {
     // Subscribe to 'winch status' updates.
     rpc SubscribeStatus(SubscribeStatusRequest) returns(stream StatusResponse) {}
@@ -70,6 +74,15 @@ message StatusResponse {
     Status status = 1; // The next 'winch status' state
 }
 
+/*
+ * Winch Status Flags.
+ *
+ * The status flags are defined in mavlink
+ * https://mavlink.io/en/messages/common.html#MAV_WINCH_STATUS_FLAG.
+ *
+ * Multiple status fields can be set simultaneously. Mavlink does
+ * not specify which states are mutually exclusive.
+ */
 message StatusFlags {
     bool healthy = 1;           // Winch is healthy
     bool fully_retracted = 2;   // Winch line is fully retracted
@@ -87,6 +100,7 @@ message StatusFlags {
     bool load_payload = 14;     // Winch is loading a payload
 }
 
+// Status type.
 message Status {
     uint64 time_usec = 1; // Time in usec
     float line_length_m = 2; // Length of the line in meters
@@ -98,6 +112,7 @@ message Status {
     StatusFlags status_flags = 8; // Status flags
 }
 
+// Winch Action type.
 enum WinchAction {
     WINCH_ACTION_RELAXED = 0;       // Allow motor to freewheel
     WINCH_ACTION_RELATIVE_LENGTH_CONTROL = 1; // Wind or unwind specified length of line, optionally using specified rate