From fd0b8aa80f49fc45b06dcbd2ceb1c7694ff59856 Mon Sep 17 00:00:00 2001
From: per1234 <accounts@perglass.com>
Date: Sun, 19 Apr 2020 03:31:59 -0700
Subject: [PATCH] [skip changelog] Add documentation for Settings service

Comments added to the .proto files are included in the generated gRPC interface documentation.
---
 rpc/settings/settings.pb.go | 14 +++++++++++++-
 rpc/settings/settings.proto | 14 +++++++++++++-
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/rpc/settings/settings.pb.go b/rpc/settings/settings.pb.go
index 1bbc54f255d..fc5a583eb53 100644
--- a/rpc/settings/settings.pb.go
+++ b/rpc/settings/settings.pb.go
@@ -23,6 +23,7 @@ var _ = math.Inf
 const _ = proto.ProtoPackageIsVersion3 // please upgrade the proto package
 
 type RawData struct {
+	// The settings, in JSON format.
 	JsonData             string   `protobuf:"bytes,1,opt,name=jsonData,proto3" json:"jsonData,omitempty"`
 	XXX_NoUnkeyedLiteral struct{} `json:"-"`
 	XXX_unrecognized     []byte   `json:"-"`
@@ -62,7 +63,9 @@ func (m *RawData) GetJsonData() string {
 }
 
 type Value struct {
-	Key                  string   `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
+	// The key of the setting.
+	Key string `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
+	// The setting, in JSON format.
 	JsonData             string   `protobuf:"bytes,2,opt,name=jsonData,proto3" json:"jsonData,omitempty"`
 	XXX_NoUnkeyedLiteral struct{} `json:"-"`
 	XXX_unrecognized     []byte   `json:"-"`
@@ -140,6 +143,7 @@ func (m *GetAllRequest) XXX_DiscardUnknown() {
 var xxx_messageInfo_GetAllRequest proto.InternalMessageInfo
 
 type GetValueRequest struct {
+	// The key of the setting.
 	Key                  string   `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
 	XXX_NoUnkeyedLiteral struct{} `json:"-"`
 	XXX_unrecognized     []byte   `json:"-"`
@@ -285,9 +289,13 @@ const _ = grpc.SupportPackageIsVersion4
 //
 // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.
 type SettingsClient interface {
+	// List all the settings.
 	GetAll(ctx context.Context, in *GetAllRequest, opts ...grpc.CallOption) (*RawData, error)
+	// Set multiple settings values at once.
 	Merge(ctx context.Context, in *RawData, opts ...grpc.CallOption) (*MergeResponse, error)
+	// Get the value of a specific setting.
 	GetValue(ctx context.Context, in *GetValueRequest, opts ...grpc.CallOption) (*Value, error)
+	// Set the value of a specific setting.
 	SetValue(ctx context.Context, in *Value, opts ...grpc.CallOption) (*SetValueResponse, error)
 }
 
@@ -337,9 +345,13 @@ func (c *settingsClient) SetValue(ctx context.Context, in *Value, opts ...grpc.C
 
 // SettingsServer is the server API for Settings service.
 type SettingsServer interface {
+	// List all the settings.
 	GetAll(context.Context, *GetAllRequest) (*RawData, error)
+	// Set multiple settings values at once.
 	Merge(context.Context, *RawData) (*MergeResponse, error)
+	// Get the value of a specific setting.
 	GetValue(context.Context, *GetValueRequest) (*Value, error)
+	// Set the value of a specific setting.
 	SetValue(context.Context, *Value) (*SetValueResponse, error)
 }
 
diff --git a/rpc/settings/settings.proto b/rpc/settings/settings.proto
index e7302c34817..6183ba16db3 100644
--- a/rpc/settings/settings.proto
+++ b/rpc/settings/settings.proto
@@ -19,23 +19,35 @@ package cc.arduino.cli.settings;
 
 option go_package = "github.com/arduino/arduino-cli/rpc/settings";
 
+// The Settings service provides an interface to Arduino CLI's configuration
+// options
 service Settings {
+  // List all the settings.
   rpc GetAll(GetAllRequest) returns (RawData);
+  // Set multiple settings values at once.
   rpc Merge(RawData) returns (MergeResponse);
+  // Get the value of a specific setting.
   rpc GetValue(GetValueRequest) returns (Value);
+  // Set the value of a specific setting.
   rpc SetValue(Value) returns (SetValueResponse);
 }
 
 message RawData {
+    // The settings, in JSON format.
     string jsonData = 1;
 }
 
 message Value {
+  // The key of the setting.
   string key = 1;
+  // The setting, in JSON format.
   string jsonData = 2;
 }
 
 message GetAllRequest {}
-message GetValueRequest { string key = 1; }
+message GetValueRequest {
+  // The key of the setting.
+  string key = 1;
+}
 message MergeResponse {}
 message SetValueResponse {}