From e33d26ca7dc1e8c3f8213fe58880af5ab77cc2bb Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 5 May 2020 23:23:34 -0700 Subject: [PATCH] [skip changelog] Add documentation for common and general components of the gRPC interface Comments added to the .proto files are included in the generated gRPC interface documentation. --- rpc/commands/commands.pb.go | 38 +++++++++++++++++++++++++++++-------- rpc/commands/commands.proto | 25 +++++++++++++++++++++++- rpc/commands/common.pb.go | 21 ++++++++++++++------ rpc/commands/common.proto | 13 ++++++++++++- 4 files changed, 81 insertions(+), 16 deletions(-) diff --git a/rpc/commands/commands.pb.go b/rpc/commands/commands.pb.go index 59fe7937ed8..af751e22958 100644 --- a/rpc/commands/commands.pb.go +++ b/rpc/commands/commands.pb.go @@ -23,6 +23,8 @@ var _ = math.Inf const _ = proto.ProtoPackageIsVersion3 // please upgrade the proto package type InitReq struct { + // Start a Arduino Core Service instance that will provide only Library + // Manager functionality. LibraryManagerOnly bool `protobuf:"varint,2,opt,name=library_manager_only,json=libraryManagerOnly,proto3" json:"library_manager_only,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -62,14 +64,21 @@ func (m *InitReq) GetLibraryManagerOnly() bool { } type InitResp struct { - Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"` - PlatformsIndexErrors []string `protobuf:"bytes,2,rep,name=platforms_index_errors,json=platformsIndexErrors,proto3" json:"platforms_index_errors,omitempty"` - LibrariesIndexError string `protobuf:"bytes,3,opt,name=libraries_index_error,json=librariesIndexError,proto3" json:"libraries_index_error,omitempty"` - DownloadProgress *DownloadProgress `protobuf:"bytes,4,opt,name=download_progress,json=downloadProgress,proto3" json:"download_progress,omitempty"` - TaskProgress *TaskProgress `protobuf:"bytes,5,opt,name=task_progress,json=taskProgress,proto3" json:"task_progress,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // An Arduino Core Service instance. + Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"` + // Error messages related to any problems encountered while parsing the + // platforms index files. + PlatformsIndexErrors []string `protobuf:"bytes,2,rep,name=platforms_index_errors,json=platformsIndexErrors,proto3" json:"platforms_index_errors,omitempty"` + // Error message if a problem was encountered while parsing the libraries + // index file. + LibrariesIndexError string `protobuf:"bytes,3,opt,name=libraries_index_error,json=librariesIndexError,proto3" json:"libraries_index_error,omitempty"` + // Progress of the downloads of platforms and libraries index files. + DownloadProgress *DownloadProgress `protobuf:"bytes,4,opt,name=download_progress,json=downloadProgress,proto3" json:"download_progress,omitempty"` + // Describes the current stage of the initialization. + TaskProgress *TaskProgress `protobuf:"bytes,5,opt,name=task_progress,json=taskProgress,proto3" json:"task_progress,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *InitResp) Reset() { *m = InitResp{} } @@ -133,6 +142,7 @@ func (m *InitResp) GetTaskProgress() *TaskProgress { } type DestroyReq struct { + // The Arduino Core Service instance to destroy. Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -203,6 +213,7 @@ func (m *DestroyResp) XXX_DiscardUnknown() { var xxx_messageInfo_DestroyResp proto.InternalMessageInfo type RescanReq struct { + // Arduino Core Service instance from the Init response. Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -242,7 +253,11 @@ func (m *RescanReq) GetInstance() *Instance { } type RescanResp struct { + // Error messages related to any problems encountered while parsing the + // platforms index file. PlatformsIndexErrors []string `protobuf:"bytes,1,rep,name=platforms_index_errors,json=platformsIndexErrors,proto3" json:"platforms_index_errors,omitempty"` + // Error message if a problem was encountered while parsing the libraries + // index file. LibrariesIndexError string `protobuf:"bytes,2,opt,name=libraries_index_error,json=librariesIndexError,proto3" json:"libraries_index_error,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -289,6 +304,7 @@ func (m *RescanResp) GetLibrariesIndexError() string { } type UpdateIndexReq struct { + // Arduino Core Service instance from the Init response. Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -328,6 +344,7 @@ func (m *UpdateIndexReq) GetInstance() *Instance { } type UpdateIndexResp struct { + // Progress of the platforms index download. DownloadProgress *DownloadProgress `protobuf:"bytes,1,opt,name=download_progress,json=downloadProgress,proto3" json:"download_progress,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -367,6 +384,7 @@ func (m *UpdateIndexResp) GetDownloadProgress() *DownloadProgress { } type UpdateLibrariesIndexReq struct { + // Arduino Core Service instance from the Init response. Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -406,6 +424,7 @@ func (m *UpdateLibrariesIndexReq) GetInstance() *Instance { } type UpdateLibrariesIndexResp struct { + // Progress of the libraries index download. DownloadProgress *DownloadProgress `protobuf:"bytes,1,opt,name=download_progress,json=downloadProgress,proto3" json:"download_progress,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -476,6 +495,7 @@ func (m *VersionReq) XXX_DiscardUnknown() { var xxx_messageInfo_VersionReq proto.InternalMessageInfo type VersionResp struct { + // The version of Arduino CLI in use. Version string `protobuf:"bytes,1,opt,name=version,proto3" json:"version,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -617,6 +637,7 @@ type ArduinoCoreClient interface { UpdateIndex(ctx context.Context, in *UpdateIndexReq, opts ...grpc.CallOption) (ArduinoCore_UpdateIndexClient, error) // Update libraries index UpdateLibrariesIndex(ctx context.Context, in *UpdateLibrariesIndexReq, opts ...grpc.CallOption) (ArduinoCore_UpdateLibrariesIndexClient, error) + // Get the version of Arduino CLI in use. Version(ctx context.Context, in *VersionReq, opts ...grpc.CallOption) (*VersionResp, error) // Requests details about a board BoardDetails(ctx context.Context, in *BoardDetailsReq, opts ...grpc.CallOption) (*BoardDetailsResp, error) @@ -1207,6 +1228,7 @@ type ArduinoCoreServer interface { UpdateIndex(*UpdateIndexReq, ArduinoCore_UpdateIndexServer) error // Update libraries index UpdateLibrariesIndex(*UpdateLibrariesIndexReq, ArduinoCore_UpdateLibrariesIndexServer) error + // Get the version of Arduino CLI in use. Version(context.Context, *VersionReq) (*VersionResp, error) // Requests details about a board BoardDetails(context.Context, *BoardDetailsReq) (*BoardDetailsResp, error) diff --git a/rpc/commands/commands.proto b/rpc/commands/commands.proto index ecc761eb87a..82965105a87 100644 --- a/rpc/commands/commands.proto +++ b/rpc/commands/commands.proto @@ -46,6 +46,7 @@ service ArduinoCore { // Update libraries index rpc UpdateLibrariesIndex(UpdateLibrariesIndexReq) returns (stream UpdateLibrariesIndexResp) {} + // Get the version of Arduino CLI in use. rpc Version(VersionReq) returns (VersionResp) {} // BOARD COMMANDS @@ -92,47 +93,69 @@ service ArduinoCore { } message InitReq { + // Start a Arduino Core Service instance that will provide only Library + // Manager functionality. bool library_manager_only = 2; } message InitResp { + // An Arduino Core Service instance. Instance instance = 1; + // Error messages related to any problems encountered while parsing the + // platforms index files. repeated string platforms_index_errors = 2; + // Error message if a problem was encountered while parsing the libraries + // index file. string libraries_index_error = 3; + // Progress of the downloads of platforms and libraries index files. DownloadProgress download_progress = 4; + // Describes the current stage of the initialization. TaskProgress task_progress = 5; } -message DestroyReq { Instance instance = 1; } +message DestroyReq { + // The Arduino Core Service instance to destroy. + Instance instance = 1; +} message DestroyResp {} message RescanReq { + // Arduino Core Service instance from the Init response. Instance instance = 1; } message RescanResp { + // Error messages related to any problems encountered while parsing the + // platforms index file. repeated string platforms_index_errors = 1; + // Error message if a problem was encountered while parsing the libraries + // index file. string libraries_index_error = 2; } message UpdateIndexReq { + // Arduino Core Service instance from the Init response. Instance instance = 1; } message UpdateIndexResp { + // Progress of the platforms index download. DownloadProgress download_progress = 1; } message UpdateLibrariesIndexReq { + // Arduino Core Service instance from the Init response. Instance instance = 1; } message UpdateLibrariesIndexResp { + // Progress of the libraries index download. DownloadProgress download_progress = 1; } message VersionReq {} message VersionResp { + // The version of Arduino CLI in use. string version = 1; } diff --git a/rpc/commands/common.pb.go b/rpc/commands/common.pb.go index 0d25d8218f5..cee26c9b025 100644 --- a/rpc/commands/common.pb.go +++ b/rpc/commands/common.pb.go @@ -21,6 +21,7 @@ var _ = math.Inf const _ = proto.ProtoPackageIsVersion3 // please upgrade the proto package type Instance struct { + // The ID of the instance. Id int32 `protobuf:"varint,1,opt,name=id,proto3" json:"id,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -60,10 +61,15 @@ func (m *Instance) GetId() int32 { } type DownloadProgress struct { - Url string `protobuf:"bytes,1,opt,name=url,proto3" json:"url,omitempty"` - File string `protobuf:"bytes,2,opt,name=file,proto3" json:"file,omitempty"` - TotalSize int64 `protobuf:"varint,3,opt,name=total_size,json=totalSize,proto3" json:"total_size,omitempty"` - Downloaded int64 `protobuf:"varint,4,opt,name=downloaded,proto3" json:"downloaded,omitempty"` + // URL of the download. + Url string `protobuf:"bytes,1,opt,name=url,proto3" json:"url,omitempty"` + // The file being downloaded. + File string `protobuf:"bytes,2,opt,name=file,proto3" json:"file,omitempty"` + // Total size of the file being downloaded. + TotalSize int64 `protobuf:"varint,3,opt,name=total_size,json=totalSize,proto3" json:"total_size,omitempty"` + // Size of the downloaded portion of the file. + Downloaded int64 `protobuf:"varint,4,opt,name=downloaded,proto3" json:"downloaded,omitempty"` + // Whether the download is complete. Completed bool `protobuf:"varint,5,opt,name=completed,proto3" json:"completed,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -131,8 +137,11 @@ func (m *DownloadProgress) GetCompleted() bool { } type TaskProgress struct { - Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` - Message string `protobuf:"bytes,2,opt,name=message,proto3" json:"message,omitempty"` + // Description of the task. + Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // Additional information about the task. + Message string `protobuf:"bytes,2,opt,name=message,proto3" json:"message,omitempty"` + // Whether the task is complete. Completed bool `protobuf:"varint,3,opt,name=completed,proto3" json:"completed,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` diff --git a/rpc/commands/common.proto b/rpc/commands/common.proto index 2324f4836b7..0c27645b771 100644 --- a/rpc/commands/common.proto +++ b/rpc/commands/common.proto @@ -19,18 +19,29 @@ package cc.arduino.cli.commands; option go_package = "github.com/arduino/arduino-cli/rpc/commands"; -message Instance { int32 id = 1; } +message Instance { + // The ID of the instance. + int32 id = 1; +} message DownloadProgress { + // URL of the download. string url = 1; + // The file being downloaded. string file = 2; + // Total size of the file being downloaded. int64 total_size = 3; + // Size of the downloaded portion of the file. int64 downloaded = 4; + // Whether the download is complete. bool completed = 5; } message TaskProgress { + // Description of the task. string name = 1; + // Additional information about the task. string message = 2; + // Whether the task is complete. bool completed = 3; }