Add missing docstrings (#369)

Author: julianoes

protos/arm_authorizer_server/arm_authorizer_server.proto

@@ -7,6 +7,7 @@ import "mavsdk_options.proto";
 option java_package = "io.mavsdk.arm_authorizer";
 option java_outer_classname = "ArmAuthorizerServerProto";
 
+// Use arm authorization.
 service ArmAuthorizerServerService {
     // Subscribe to arm authorization request messages. Each request received should respond to using RespondArmAuthorization
     rpc SubscribeArmAuthorization(SubscribeArmAuthorizationRequest) returns(stream ArmAuthorizationResponse) { option (mavsdk.options.async_type) = ASYNC; }
@@ -47,6 +48,7 @@ message RejectArmAuthorizationResponse {
 }
 
 message ArmAuthorizerServerResult {
+    // The result
     enum Result {
         RESULT_UNKNOWN = 0; // Unknown result
         RESULT_SUCCESS = 1; // Command accepted
@@ -57,6 +59,7 @@ message ArmAuthorizerServerResult {
     string result_str = 2; // Human-readable English string describing the result
 }
 
+// The rejection reason
 enum RejectionReason {
     REJECTION_REASON_GENERIC = 0; // Not a specific reason
     REJECTION_REASON_NONE = 1; // Authorizer will send the error as string to GCS

protos/camera/camera.proto

@@ -307,6 +307,7 @@ message CameraListResponse {
     CameraList camera_list = 1; // Camera list
 }
 
+// An update about the current mode
 message ModeUpdate {
     int32 component_id = 1; // Component ID
     Mode mode = 2; // Camera mode
@@ -317,6 +318,7 @@ message ModeResponse {
     ModeUpdate update = 1; // Mode update for camera
 }
 
+// An update about a video stream
 message VideoStreamUpdate {
     int32 component_id = 1; // Component ID
     VideoStreamInfo video_stream_info = 2; // Video stream info
@@ -369,6 +371,7 @@ message Storage {
     StorageType storage_type = 11; // Storage type
 }
 
+// An update about storage
 message StorageUpdate {
     int32 component_id = 1; // Component ID
     Storage storage = 2; // Storage
@@ -379,6 +382,7 @@ message StorageResponse {
     StorageUpdate update = 1; // Camera's storage status
 }
 
+// An update about a current setting
 message CurrentSettingsUpdate {
     int32 component_id = 1; // Component ID
     repeated Setting current_settings = 2; // List of current settings
@@ -389,6 +393,7 @@ message CurrentSettingsResponse {
     CurrentSettingsUpdate update = 1; // Current setting update per camera
 }
 
+// An update about possible setting options
 message PossibleSettingOptionsUpdate {
     int32 component_id = 1; // Component ID
     repeated SettingOptions setting_options = 2; // List of settings that can be changed

protos/camera_server/camera_server.proto

@@ -449,13 +449,16 @@ message StorageInformation {
     float write_speed_mib_s = 8; // Write speed [MiB/s]
 }
 
+// Capture status
 message CaptureStatus {
+    // The image status
     enum ImageStatus {
         IMAGE_STATUS_IDLE = 0; // idle
         IMAGE_STATUS_CAPTURE_IN_PROGRESS = 1; // capture in progress
         IMAGE_STATUS_INTERVAL_IDLE = 2; // interval set but idle
         IMAGE_STATUS_INTERVAL_IN_PROGRESS = 3; // interval set and capture in progress)
     }
+    // The video status
     enum VideoStatus {
         VIDEO_STATUS_IDLE = 0;  // idle
         VIDEO_STATUS_CAPTURE_IN_PROGRESS = 1;   // capture in progress

protos/component_metadata/component_metadata.proto

@@ -38,14 +38,16 @@ message RequestComponentRequest {
     uint32 compid = 1; // The component ID to request
 }
 
+message RequestComponentResponse {}
+
 message GetMetadataRequest {
     uint32 compid = 1; // The component ID to request
     MetadataType metadata_type = 2; // The metadata type
 }
 
 message GetMetadataResponse {
     ComponentMetadataResult component_metadata_result = 1;
-    MetadataData response = 2;
+    MetadataData response = 2; // The response
 }
 
 // Metadata response
@@ -55,32 +57,31 @@ message MetadataData {
 
 // Result type.
 message ComponentMetadataResult {
-    // Possible results returned for GetMetadata
+    // Possible results returned
     enum Result {
-        RESULT_SUCCESS = 0;
-        RESULT_NOT_AVAILABLE = 1;
-        RESULT_CONNECTION_ERROR = 2;
-        RESULT_UNSUPPORTED = 3;
-        RESULT_DENIED = 4;
-        RESULT_FAILED = 5;
-        RESULT_TIMEOUT = 6;
-        RESULT_NO_SYSTEM = 7;
-        RESULT_NOT_REQUESTED = 8;
+        RESULT_SUCCESS = 0; // Success
+        RESULT_NOT_AVAILABLE = 1; // Not available
+        RESULT_CONNECTION_ERROR = 2; // Connection error
+        RESULT_UNSUPPORTED = 3; // Unsupported
+        RESULT_DENIED = 4; // Denied
+        RESULT_FAILED = 5; // Failed
+        RESULT_TIMEOUT = 6; // Timeout
+        RESULT_NO_SYSTEM = 7; // No system
+        RESULT_NOT_REQUESTED = 8; // Not requested
     }
 
     Result result = 1; // Result enum value
     string result_str = 2; // Human-readable English string describing the result
 }
 
-message RequestComponentResponse {}
 message RequestAutopilotComponentRequest {}
 message RequestAutopilotComponentResponse {}
 
 message SubscribeMetadataAvailableRequest {}
 
-
+// An update about available metadata
 message MetadataAvailableResponse {
-    MetadataUpdate data = 1;
+    MetadataUpdate data = 1; // The metadata data
 }
 
 // Metadata for a given component and type
@@ -90,6 +91,7 @@ message MetadataUpdate {
     string json_metadata = 3; // The JSON metadata
 }
 
+// The metadata type
 enum MetadataType {
     METADATA_TYPE_ALL_COMPLETED = 0; // This is set in the subscription callback when all metadata types completed for a given component ID
     METADATA_TYPE_PARAMETER = 1; // Parameter metadata

protos/component_metadata_server/component_metadata_server.proto

@@ -20,11 +20,13 @@ message SetMetadataRequest {
 }
 message SetMetadataResponse {}
 
+// The metadata type and content
 message Metadata {
     MetadataType type = 1; // The metadata type
     string json_metadata = 2; // The JSON metadata
 }
 
+// The metadata type
 enum MetadataType {
     METADATA_TYPE_PARAMETER = 0; // Parameter metadata
     METADATA_TYPE_EVENTS = 1; // Event definitions

protos/events/events.proto

@@ -26,31 +26,34 @@ service EventsService {
     rpc GetHealthAndArmingChecksReport(GetHealthAndArmingChecksReportRequest) returns(GetHealthAndArmingChecksReportResponse) { option (mavsdk.options.async_type) = SYNC; }
 }
 
+// Log level type
 enum LogLevel {
-    LOG_LEVEL_EMERGENCY = 0;
-    LOG_LEVEL_ALERT = 1;
-    LOG_LEVEL_CRITICAL = 2;
-    LOG_LEVEL_ERROR = 3;
-    LOG_LEVEL_WARNING = 4;
-    LOG_LEVEL_NOTICE = 5;
-    LOG_LEVEL_INFO = 6;
-    LOG_LEVEL_DEBUG = 7;
+    LOG_LEVEL_EMERGENCY = 0; // Emergency
+    LOG_LEVEL_ALERT = 1; // Alert
+    LOG_LEVEL_CRITICAL = 2; // Critical
+    LOG_LEVEL_ERROR = 3; // Error
+    LOG_LEVEL_WARNING = 4; // Warning
+    LOG_LEVEL_NOTICE = 5; // Notice
+    LOG_LEVEL_INFO = 6; // Info
+    LOG_LEVEL_DEBUG = 7; // Debug
 }
 
+// Event type
 message Event {
     uint32 compid = 1; // The source component ID of the event
     string message = 2; // Short, single-line message
     string description = 3; // Detailed description (optional, might be multiple lines)
-    LogLevel log_level = 4;
+    LogLevel log_level = 4; // Log level of message
 
     string event_namespace = 5; // Namespace, e.g. "px4"
     string event_name = 6; // Event name (unique within the namespace)
 }
 
+// Health and arming check problem type
 message HealthAndArmingCheckProblem {
     string message = 1; // Short, single-line message
     string description = 2; // Detailed description (optional, might be multiple lines)
-    LogLevel log_level = 3;
+    LogLevel log_level = 3; // Log level of message
     string health_component = 4; // Associated health component, e.g. "gps"
 }
 
@@ -61,6 +64,7 @@ message HealthAndArmingCheckMode {
     repeated HealthAndArmingCheckProblem problems = 3; // List of reported problems for the mode
 }
 
+// Health component report type
 message HealthComponentReport {
     string name = 1; // Unique component name, e.g. "gps"
     string label = 2; // Human readable label of the component, e.g. "GPS" or "Accelerometer"
@@ -69,6 +73,7 @@ message HealthComponentReport {
     bool has_warning = 5; // If the component has warnings
 }
 
+// Health and arming check report type
 message HealthAndArmingCheckReport {
     HealthAndArmingCheckMode current_mode_intention = 1; // Report for currently intended mode
     // TODO: we can add reports for different modes here too (e.g. Takeoff or Mission)
@@ -79,15 +84,17 @@ message HealthAndArmingCheckReport {
 
 // Result type.
 message EventsResult {
+    // Possible results returned
     enum Result {
-        RESULT_SUCCESS = 0;
-        RESULT_NOT_AVAILABLE = 1;
-        RESULT_CONNECTION_ERROR = 2;
-        RESULT_UNSUPPORTED = 3;
-        RESULT_DENIED = 4;
-        RESULT_FAILED = 5;
-        RESULT_TIMEOUT = 6;
-        RESULT_NO_SYSTEM = 7;
+        RESULT_SUCCESS = 0; // Successful result
+        RESULT_NOT_AVAILABLE = 1; // Not available
+        RESULT_CONNECTION_ERROR = 2; // Connection error
+        RESULT_UNSUPPORTED = 3; // Unsupported
+        RESULT_DENIED = 4; // Denied
+        RESULT_FAILED = 5; // Failed
+        RESULT_TIMEOUT = 6; // Timeout
+        RESULT_NO_SYSTEM = 7; // No system available
+        RESULT_UNKNOWN = 8; // Unknown result
     }
 
     Result result = 1; // Result enum value
@@ -98,17 +105,17 @@ message EventsResult {
 message SubscribeEventsRequest {}
 
 message EventsResponse {
-    Event event = 1;
+    Event event = 1; // The event
 }
 
 message SubscribeHealthAndArmingChecksRequest {}
 
 message HealthAndArmingChecksResponse {
-    HealthAndArmingCheckReport report = 1;
+    HealthAndArmingCheckReport report = 1; // The report
 }
 
 message GetHealthAndArmingChecksReportRequest {}
 message GetHealthAndArmingChecksReportResponse {
-    EventsResult events_result = 1;
-    HealthAndArmingCheckReport report = 2;
+    EventsResult events_result = 1; // The events result
+    HealthAndArmingCheckReport report = 2; // The report
 }

protos/ftp/ftp.proto

@@ -78,6 +78,7 @@ message ListDirectoryRequest {
     string remote_dir = 1; // The remote directory to list the contents for.
 }
 
+// The output of a directory list
 message ListDirectoryData {
     repeated string dirs = 1; // The found directories.
     repeated string files = 2; // The found files.

protos/gimbal/gimbal.proto

@@ -241,6 +241,7 @@ enum ControlMode {
     CONTROL_MODE_SECONDARY = 2; // To take secondary control over the gimbal
 }
 
+// The send mode type
 enum SendMode {
     SEND_MODE_ONCE = 0; // Send command exactly once with quality of service (use for sporadic commands slower than 1 Hz)
     SEND_MODE_STREAM = 1; // Stream setpoint without quality of service (use for setpoints faster than 1 Hz).