[skip changelog] Add documentation for library components of the gRPC interface (#692)

* [skip changelog] Add documentation for library components of the gRPC interface

Comments added to the .proto files are included in the generated gRPC interface documentation.

* Correct documentation re: relative vs absolute paths provided by Library message fields
Co-authored-by: Roberto Sora <r.sora@arduino.cc>

* Use preferred "platform" term in gRPC interface documentation

The official term is now "platform", rather than the previous ambiguous "core".
Co-authored-by: Roberto Sora <r.sora@arduino.cc>

* Fix formatting of gRPC interface documentation

* Fix incorrect documentation for task_progress field of LibraryUninstall response

* Document that library version is the key of the releases map

* Update gRPC interface code comments
Co-authored-by: Roberto Sora <r.sora@arduino.cc>

rpc/commands/commands.pb.go

@@ -675,12 +675,21 @@ type ArduinoCoreClient interface {
 	PlatformSearch(ctx context.Context, in *PlatformSearchReq, opts ...grpc.CallOption) (*PlatformSearchResp, error)
 	// List all installed platforms.
 	PlatformList(ctx context.Context, in *PlatformListReq, opts ...grpc.CallOption) (*PlatformListResp, error)
+	// Download the archive file of an Arduino library in the libraries index to
+	// the staging directory.
 	LibraryDownload(ctx context.Context, in *LibraryDownloadReq, opts ...grpc.CallOption) (ArduinoCore_LibraryDownloadClient, error)
+	// Download and install an Arduino library from the libraries index.
 	LibraryInstall(ctx context.Context, in *LibraryInstallReq, opts ...grpc.CallOption) (ArduinoCore_LibraryInstallClient, error)
+	// Uninstall an Arduino library.
 	LibraryUninstall(ctx context.Context, in *LibraryUninstallReq, opts ...grpc.CallOption) (ArduinoCore_LibraryUninstallClient, error)
+	// Upgrade all installed Arduino libraries to the newest version available.
 	LibraryUpgradeAll(ctx context.Context, in *LibraryUpgradeAllReq, opts ...grpc.CallOption) (ArduinoCore_LibraryUpgradeAllClient, error)
+	// List the recursive dependencies of a library, as defined by the `depends`
+	// field of the library.properties files.
 	LibraryResolveDependencies(ctx context.Context, in *LibraryResolveDependenciesReq, opts ...grpc.CallOption) (*LibraryResolveDependenciesResp, error)
+	// Search the Arduino libraries index for libraries.
 	LibrarySearch(ctx context.Context, in *LibrarySearchReq, opts ...grpc.CallOption) (*LibrarySearchResp, error)
+	// List the installed libraries.
 	LibraryList(ctx context.Context, in *LibraryListReq, opts ...grpc.CallOption) (*LibraryListResp, error)
 }
 
@@ -1324,12 +1333,21 @@ type ArduinoCoreServer interface {
 	PlatformSearch(context.Context, *PlatformSearchReq) (*PlatformSearchResp, error)
 	// List all installed platforms.
 	PlatformList(context.Context, *PlatformListReq) (*PlatformListResp, error)
+	// Download the archive file of an Arduino library in the libraries index to
+	// the staging directory.
 	LibraryDownload(*LibraryDownloadReq, ArduinoCore_LibraryDownloadServer) error
+	// Download and install an Arduino library from the libraries index.
 	LibraryInstall(*LibraryInstallReq, ArduinoCore_LibraryInstallServer) error
+	// Uninstall an Arduino library.
 	LibraryUninstall(*LibraryUninstallReq, ArduinoCore_LibraryUninstallServer) error
+	// Upgrade all installed Arduino libraries to the newest version available.
 	LibraryUpgradeAll(*LibraryUpgradeAllReq, ArduinoCore_LibraryUpgradeAllServer) error
+	// List the recursive dependencies of a library, as defined by the `depends`
+	// field of the library.properties files.
 	LibraryResolveDependencies(context.Context, *LibraryResolveDependenciesReq) (*LibraryResolveDependenciesResp, error)
+	// Search the Arduino libraries index for libraries.
 	LibrarySearch(context.Context, *LibrarySearchReq) (*LibrarySearchResp, error)
+	// List the installed libraries.
 	LibraryList(context.Context, *LibraryListReq) (*LibraryListResp, error)
 }
 

rpc/commands/commands.proto

@@ -96,18 +96,27 @@ service ArduinoCore {
   // List all installed platforms.
   rpc PlatformList(PlatformListReq) returns (PlatformListResp);
 
+  // Download the archive file of an Arduino library in the libraries index to
+  // the staging directory.
   rpc LibraryDownload(LibraryDownloadReq) returns (stream LibraryDownloadResp);
 
+  // Download and install an Arduino library from the libraries index.
   rpc LibraryInstall(LibraryInstallReq) returns (stream LibraryInstallResp);
 
+  // Uninstall an Arduino library.
   rpc LibraryUninstall(LibraryUninstallReq) returns (stream LibraryUninstallResp);
 
+  // Upgrade all installed Arduino libraries to the newest version available.
   rpc LibraryUpgradeAll(LibraryUpgradeAllReq) returns (stream LibraryUpgradeAllResp);
 
+  // List the recursive dependencies of a library, as defined by the `depends`
+  // field of the library.properties files.
   rpc LibraryResolveDependencies(LibraryResolveDependenciesReq) returns (LibraryResolveDependenciesResp);
 
+  // Search the Arduino libraries index for libraries.
   rpc LibrarySearch(LibrarySearchReq) returns (LibrarySearchResp);
 
+  // List the installed libraries.
   rpc LibraryList(LibraryListReq) returns (LibraryListResp);
 }
 

rpc/commands/lib.pb.go

@@ -23,7 +23,9 @@ const _ = proto.ProtoPackageIsVersion3 // please upgrade the proto package
 type LibrarySearchStatus int32
 
 const (
+	// No search results were found.
 	LibrarySearchStatus_failed LibrarySearchStatus = 0
+	// Search results were found.
 	LibrarySearchStatus_success LibrarySearchStatus = 1
 )
 
@@ -48,7 +50,9 @@ func (LibrarySearchStatus) EnumDescriptor() ([]byte, []int) {
 type LibraryLayout int32
 
 const (
+	// Library is in the 1.0 Arduino library format.
 	LibraryLayout_flat_layout LibraryLayout = 0
+	// Library is in the 1.5 Arduino library format.
 	LibraryLayout_recursive_layout LibraryLayout = 1
 )
 
@@ -73,9 +77,15 @@ func (LibraryLayout) EnumDescriptor() ([]byte, []int) {
 type LibraryLocation int32
 
 const (
+	// In the `libraries` subdirectory of the Arduino IDE installation.
 	LibraryLocation_ide_builtin LibraryLocation = 0
+	// In the `libraries` subdirectory of the user directory (sketchbook).
 	LibraryLocation_user LibraryLocation = 1
+	// In the `libraries` subdirectory of a platform.
 	LibraryLocation_platform_builtin LibraryLocation = 2
+	// When `LibraryLocation` is used in a context where a board is specified,
+	// this indicates the library is in the `libraries` subdirectory of a
+	// platform referenced by the board's platform.
 	LibraryLocation_referenced_platform_builtin LibraryLocation = 3
 )
 
@@ -102,8 +112,11 @@ func (LibraryLocation) EnumDescriptor() ([]byte, []int) {
 }
 
 type LibraryDownloadReq struct {
+	// Arduino Core Service instance from the `Init` response.
 	Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"`
+	// Name of the library.
 	Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
+	// The version of the library to download.
 	Version              string   `protobuf:"bytes,3,opt,name=version,proto3" json:"version,omitempty"`
 	XXX_NoUnkeyedLiteral struct{} `json:"-"`
 	XXX_unrecognized     []byte   `json:"-"`
@@ -157,6 +170,7 @@ func (m *LibraryDownloadReq) GetVersion() string {
 }
 
 type LibraryDownloadResp struct {
+	// Progress of the library download.
 	Progress             *DownloadProgress `protobuf:"bytes,1,opt,name=progress,proto3" json:"progress,omitempty"`
 	XXX_NoUnkeyedLiteral struct{}          `json:"-"`
 	XXX_unrecognized     []byte            `json:"-"`
@@ -196,8 +210,11 @@ func (m *LibraryDownloadResp) GetProgress() *DownloadProgress {
 }
 
 type LibraryInstallReq struct {
+	// Arduino Core Service instance from the `Init` response.
 	Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"`
+	// Name of the library.
 	Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
+	// The version of the library to install.
 	Version              string   `protobuf:"bytes,3,opt,name=version,proto3" json:"version,omitempty"`
 	XXX_NoUnkeyedLiteral struct{} `json:"-"`
 	XXX_unrecognized     []byte   `json:"-"`
@@ -251,7 +268,9 @@ func (m *LibraryInstallReq) GetVersion() string {
 }
 
 type LibraryInstallResp struct {
+	// Progress of the library download.
 	Progress *DownloadProgress `protobuf:"bytes,1,opt,name=progress,proto3" json:"progress,omitempty"`
+	// Description of the current stage of the installation.
 	TaskProgress         *TaskProgress `protobuf:"bytes,2,opt,name=task_progress,json=taskProgress,proto3" json:"task_progress,omitempty"`
 	XXX_NoUnkeyedLiteral struct{}      `json:"-"`
 	XXX_unrecognized     []byte        `json:"-"`
@@ -298,8 +317,11 @@ func (m *LibraryInstallResp) GetTaskProgress() *TaskProgress {
 }
 
 type LibraryUninstallReq struct {
+	// Arduino Core Service instance from the `Init` response.
 	Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"`
+	// Name of the library.
 	Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
+	// The version of the library to uninstall.
 	Version              string   `protobuf:"bytes,3,opt,name=version,proto3" json:"version,omitempty"`
 	XXX_NoUnkeyedLiteral struct{} `json:"-"`
 	XXX_unrecognized     []byte   `json:"-"`
@@ -353,6 +375,7 @@ func (m *LibraryUninstallReq) GetVersion() string {
 }
 
 type LibraryUninstallResp struct {
+	// Description of the current stage of the uninstallation.
 	TaskProgress         *TaskProgress `protobuf:"bytes,1,opt,name=task_progress,json=taskProgress,proto3" json:"task_progress,omitempty"`
 	XXX_NoUnkeyedLiteral struct{}      `json:"-"`
 	XXX_unrecognized     []byte        `json:"-"`
@@ -392,6 +415,7 @@ func (m *LibraryUninstallResp) GetTaskProgress() *TaskProgress {
 }
 
 type LibraryUpgradeAllReq 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:"-"`
@@ -431,7 +455,9 @@ func (m *LibraryUpgradeAllReq) GetInstance() *Instance {
 }
 
 type LibraryUpgradeAllResp struct {
+	// Progress of the downloads of files needed for the upgrades.
 	Progress *DownloadProgress `protobuf:"bytes,1,opt,name=progress,proto3" json:"progress,omitempty"`
+	// Description of the current stage of the upgrade.
 	TaskProgress         *TaskProgress `protobuf:"bytes,2,opt,name=task_progress,json=taskProgress,proto3" json:"task_progress,omitempty"`
 	XXX_NoUnkeyedLiteral struct{}      `json:"-"`
 	XXX_unrecognized     []byte        `json:"-"`
@@ -478,8 +504,12 @@ func (m *LibraryUpgradeAllResp) GetTaskProgress() *TaskProgress {
 }
 
 type LibraryResolveDependenciesReq struct {
+	// Arduino Core Service instance from the `Init` response.
 	Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"`
+	// Name of the library.
 	Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
+	// The version of the library to check dependencies of. If no version is
+	// specified, dependencies of the newest version will be listed.
 	Version              string   `protobuf:"bytes,3,opt,name=version,proto3" json:"version,omitempty"`
 	XXX_NoUnkeyedLiteral struct{} `json:"-"`
 	XXX_unrecognized     []byte   `json:"-"`
@@ -533,6 +563,7 @@ func (m *LibraryResolveDependenciesReq) GetVersion() string {
 }
 
 type LibraryResolveDependenciesResp struct {
+	// Dependencies of the library.
 	Dependencies         []*LibraryDependencyStatus `protobuf:"bytes,1,rep,name=dependencies,proto3" json:"dependencies,omitempty"`
 	XXX_NoUnkeyedLiteral struct{}                   `json:"-"`
 	XXX_unrecognized     []byte                     `json:"-"`
@@ -572,8 +603,11 @@ func (m *LibraryResolveDependenciesResp) GetDependencies() []*LibraryDependencyS
 }
 
 type LibraryDependencyStatus struct {
+	// The name of the library dependency.
 	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
+	// The required version of the library dependency.
 	VersionRequired string `protobuf:"bytes,2,opt,name=versionRequired,proto3" json:"versionRequired,omitempty"`
+	// Version of the library dependency currently installed.
 	VersionInstalled     string   `protobuf:"bytes,3,opt,name=versionInstalled,proto3" json:"versionInstalled,omitempty"`
 	XXX_NoUnkeyedLiteral struct{} `json:"-"`
 	XXX_unrecognized     []byte   `json:"-"`
@@ -627,7 +661,9 @@ func (m *LibraryDependencyStatus) GetVersionInstalled() string {
 }
 
 type LibrarySearchReq struct {
+	// Arduino Core Service instance from the `Init` response.
 	Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"`
+	// The search query.
 	Query                string   `protobuf:"bytes,2,opt,name=query,proto3" json:"query,omitempty"`
 	XXX_NoUnkeyedLiteral struct{} `json:"-"`
 	XXX_unrecognized     []byte   `json:"-"`
@@ -674,7 +710,9 @@ func (m *LibrarySearchReq) GetQuery() string {
 }
 
 type LibrarySearchResp struct {
+	// The results of the search.
 	Libraries []*SearchedLibrary `protobuf:"bytes,1,rep,name=libraries,proto3" json:"libraries,omitempty"`
+	// Whether the search yielded results.
 	Status               LibrarySearchStatus `protobuf:"varint,2,opt,name=status,proto3,enum=cc.arduino.cli.commands.LibrarySearchStatus" json:"status,omitempty"`
 	XXX_NoUnkeyedLiteral struct{}            `json:"-"`
 	XXX_unrecognized     []byte              `json:"-"`
@@ -721,8 +759,12 @@ func (m *LibrarySearchResp) GetStatus() LibrarySearchStatus {
 }
 
 type SearchedLibrary struct {
+	// Library name.
 	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
+	// The index data for the available versions of the library. The key of the
+	// map is the library version.
 	Releases map[string]*LibraryRelease `protobuf:"bytes,2,rep,name=releases,proto3" json:"releases,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// The index data for the latest version of the library.
 	Latest               *LibraryRelease `protobuf:"bytes,3,opt,name=latest,proto3" json:"latest,omitempty"`
 	XXX_NoUnkeyedLiteral struct{}        `json:"-"`
 	XXX_unrecognized     []byte          `json:"-"`
@@ -776,18 +818,34 @@ func (m *SearchedLibrary) GetLatest() *LibraryRelease {
 }
 
 type LibraryRelease struct {
+	// Value of the `author` field in library.properties.
 	Author string `protobuf:"bytes,1,opt,name=author,proto3" json:"author,omitempty"`
+	// Value of the `version` field in library.properties.
 	Version string `protobuf:"bytes,2,opt,name=version,proto3" json:"version,omitempty"`
+	// Value of the `maintainer` field in library.properties.
 	Maintainer string `protobuf:"bytes,3,opt,name=maintainer,proto3" json:"maintainer,omitempty"`
+	// Value of the `sentence` field in library.properties.
 	Sentence string `protobuf:"bytes,4,opt,name=sentence,proto3" json:"sentence,omitempty"`
+	// Value of the `paragraph` field in library.properties.
 	Paragraph string `protobuf:"bytes,5,opt,name=paragraph,proto3" json:"paragraph,omitempty"`
+	// Value of the `url` field in library.properties.
 	Website string `protobuf:"bytes,6,opt,name=website,proto3" json:"website,omitempty"`
+	// Value of the `category` field in library.properties.
 	Category string `protobuf:"bytes,7,opt,name=category,proto3" json:"category,omitempty"`
+	// Value of the `architectures` field in library.properties.
 	Architectures []string `protobuf:"bytes,8,rep,name=architectures,proto3" json:"architectures,omitempty"`
+	// The type categories of the library, as defined in the libraries index.
+	// Possible values: `Arduino`, `Partner`, `Recommended`, `Contributed`,
+	// `Retired`.
 	Types []string `protobuf:"bytes,9,rep,name=types,proto3" json:"types,omitempty"`
+	// Information about the library archive file.
 	Resources *DownloadResource `protobuf:"bytes,10,opt,name=resources,proto3" json:"resources,omitempty"`
+	// Value of the `license` field in library.properties.
 	License string `protobuf:"bytes,11,opt,name=license,proto3" json:"license,omitempty"`
+	// Value of the `includes` field in library.properties.
 	ProvidesIncludes []string `protobuf:"bytes,12,rep,name=provides_includes,json=providesIncludes,proto3" json:"provides_includes,omitempty"`
+	// The names of the library's dependencies, as defined by the 'depends'
+	// field of library.properties.
 	Dependencies         []*LibraryDependency `protobuf:"bytes,13,rep,name=dependencies,proto3" json:"dependencies,omitempty"`
 	XXX_NoUnkeyedLiteral struct{}             `json:"-"`
 	XXX_unrecognized     []byte               `json:"-"`
@@ -911,7 +969,9 @@ func (m *LibraryRelease) GetDependencies() []*LibraryDependency {
 }
 
 type LibraryDependency struct {
+	// Library name of the dependency.
 	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
+	// Version constraint of the dependency.
 	VersionConstraint    string   `protobuf:"bytes,2,opt,name=version_constraint,json=versionConstraint,proto3" json:"version_constraint,omitempty"`
 	XXX_NoUnkeyedLiteral struct{} `json:"-"`
 	XXX_unrecognized     []byte   `json:"-"`
@@ -958,10 +1018,16 @@ func (m *LibraryDependency) GetVersionConstraint() string {
 }
 
 type DownloadResource struct {
+	// Download URL of the library archive.
 	Url string `protobuf:"bytes,1,opt,name=url,proto3" json:"url,omitempty"`
+	// Filename of the library archive.
 	Archivefilename string `protobuf:"bytes,2,opt,name=archivefilename,proto3" json:"archivefilename,omitempty"`
+	// Checksum of the library archive.
 	Checksum string `protobuf:"bytes,3,opt,name=checksum,proto3" json:"checksum,omitempty"`
+	// File size of the library archive.
 	Size int64 `protobuf:"varint,4,opt,name=size,proto3" json:"size,omitempty"`
+	// The directory under the staging subdirectory of the data directory the
+	// library archive file will be downloaded to.
 	Cachepath            string   `protobuf:"bytes,5,opt,name=cachepath,proto3" json:"cachepath,omitempty"`
 	XXX_NoUnkeyedLiteral struct{} `json:"-"`
 	XXX_unrecognized     []byte   `json:"-"`
@@ -1029,8 +1095,13 @@ func (m *DownloadResource) GetCachepath() string {
 }
 
 type LibraryListReq struct {
+	// Arduino Core Service instance from the `Init` response.
 	Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"`
+	// Whether to include built-in libraries (from platforms and the Arduino
+	// IDE) in the listing.
 	All bool `protobuf:"varint,2,opt,name=all,proto3" json:"all,omitempty"`
+	// Whether to list only libraries for which there is a newer version than
+	// the installed version available in the libraries index.
 	Updatable            bool     `protobuf:"varint,3,opt,name=updatable,proto3" json:"updatable,omitempty"`
 	XXX_NoUnkeyedLiteral struct{} `json:"-"`
 	XXX_unrecognized     []byte   `json:"-"`
@@ -1084,6 +1155,7 @@ func (m *LibraryListReq) GetUpdatable() bool {
 }
 
 type LibraryListResp struct {
+	// List of installed libraries.
 	InstalledLibrary     []*InstalledLibrary `protobuf:"bytes,1,rep,name=installed_library,json=installedLibrary,proto3" json:"installed_library,omitempty"`
 	XXX_NoUnkeyedLiteral struct{}            `json:"-"`
 	XXX_unrecognized     []byte              `json:"-"`
@@ -1123,7 +1195,11 @@ func (m *LibraryListResp) GetInstalledLibrary() []*InstalledLibrary {
 }
 
 type InstalledLibrary struct {
+	// Information about the library.
 	Library *Library `protobuf:"bytes,1,opt,name=library,proto3" json:"library,omitempty"`
+	// When the `updatable` field of the `LibraryList` request is set to `true`,
+	// this will contain information on the latest version of the library in the
+	// libraries index.
 	Release              *LibraryRelease `protobuf:"bytes,2,opt,name=release,proto3" json:"release,omitempty"`
 	XXX_NoUnkeyedLiteral struct{}        `json:"-"`
 	XXX_unrecognized     []byte          `json:"-"`
@@ -1170,28 +1246,55 @@ func (m *InstalledLibrary) GetRelease() *LibraryRelease {
 }
 
 type Library struct {
+	// The library's directory name.
 	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
+	// Value of the `author` field in library.properties.
 	Author string `protobuf:"bytes,2,opt,name=author,proto3" json:"author,omitempty"`
+	// Value of the `maintainer` field in library.properties.
 	Maintainer string `protobuf:"bytes,3,opt,name=maintainer,proto3" json:"maintainer,omitempty"`
+	// Value of the `sentence` field in library.properties.
 	Sentence string `protobuf:"bytes,4,opt,name=sentence,proto3" json:"sentence,omitempty"`
+	// Value of the `paragraph` field in library.properties.
 	Paragraph string `protobuf:"bytes,5,opt,name=paragraph,proto3" json:"paragraph,omitempty"`
+	// Value of the `url` field in library.properties.
 	Website string `protobuf:"bytes,6,opt,name=website,proto3" json:"website,omitempty"`
+	// Value of the `category` field in library.properties.
 	Category string `protobuf:"bytes,7,opt,name=category,proto3" json:"category,omitempty"`
+	// Value of the `architectures` field in library.properties.
 	Architectures []string `protobuf:"bytes,8,rep,name=architectures,proto3" json:"architectures,omitempty"`
+	// The type categories of the library. Possible values: `Arduino`,
+	// `Partner`, `Recommended`, `Contributed`, `Retired`.
 	Types []string `protobuf:"bytes,9,rep,name=types,proto3" json:"types,omitempty"`
+	// The path of the library directory.
 	InstallDir string `protobuf:"bytes,10,opt,name=install_dir,json=installDir,proto3" json:"install_dir,omitempty"`
+	// The location of the library's source files.
 	SourceDir string `protobuf:"bytes,11,opt,name=source_dir,json=sourceDir,proto3" json:"source_dir,omitempty"`
+	// The location of the library's `utility` directory.
 	UtilityDir string `protobuf:"bytes,12,opt,name=utility_dir,json=utilityDir,proto3" json:"utility_dir,omitempty"`
+	// If `location` is `platform_builtin` or `referenced_platform_builtin`, the
+	// identifying string for the platform containing the library
+	// (e.g., `arduino:avr@1.8.2`).
 	ContainerPlatform string `protobuf:"bytes,14,opt,name=container_platform,json=containerPlatform,proto3" json:"container_platform,omitempty"`
+	// Value of the `name` field in library.properties.
 	RealName string `protobuf:"bytes,16,opt,name=real_name,json=realName,proto3" json:"real_name,omitempty"`
+	// Value of the `dot_a_linkage` field in library.properties.
 	DotALinkage bool `protobuf:"varint,17,opt,name=dot_a_linkage,json=dotALinkage,proto3" json:"dot_a_linkage,omitempty"`
+	// Value of the `precompiled` field in library.properties.
 	Precompiled bool `protobuf:"varint,18,opt,name=precompiled,proto3" json:"precompiled,omitempty"`
+	// Value of the `ldflags` field in library.properties.
 	LdFlags string `protobuf:"bytes,19,opt,name=ld_flags,json=ldFlags,proto3" json:"ld_flags,omitempty"`
+	// A library.properties file is not present in the library's root directory.
 	IsLegacy bool `protobuf:"varint,20,opt,name=is_legacy,json=isLegacy,proto3" json:"is_legacy,omitempty"`
+	// Value of the `version` field in library.properties.
 	Version string `protobuf:"bytes,21,opt,name=version,proto3" json:"version,omitempty"`
+	// Value of the `license` field in library.properties.
 	License string `protobuf:"bytes,22,opt,name=license,proto3" json:"license,omitempty"`
+	// The data from the library's library.properties file, including unused
+	// fields.
 	Properties map[string]string `protobuf:"bytes,23,rep,name=properties,proto3" json:"properties,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
+	// The location type of the library installation.
 	Location LibraryLocation `protobuf:"varint,24,opt,name=location,proto3,enum=cc.arduino.cli.commands.LibraryLocation" json:"location,omitempty"`
+	// The library format type.
 	Layout               LibraryLayout `protobuf:"varint,25,opt,name=layout,proto3,enum=cc.arduino.cli.commands.LibraryLayout" json:"layout,omitempty"`
 	XXX_NoUnkeyedLiteral struct{}      `json:"-"`
 	XXX_unrecognized     []byte        `json:"-"`

rpc/commands/lib.proto

@@ -22,160 +22,263 @@ option go_package = "github.com/arduino/arduino-cli/rpc/commands";
 import "commands/common.proto";
 
 message LibraryDownloadReq {
+    // Arduino Core Service instance from the `Init` response.
     Instance instance = 1;
+    // Name of the library.
     string name = 2;
+    // The version of the library to download.
     string version = 3;
 }
 
 message LibraryDownloadResp {
+    // Progress of the library download.
     DownloadProgress progress = 1;
 }
 
 message LibraryInstallReq {
+    // Arduino Core Service instance from the `Init` response.
     Instance instance = 1;
+    // Name of the library.
     string name = 2;
+    // The version of the library to install.
     string version = 3;
 }
 
 message LibraryInstallResp {
+    // Progress of the library download.
     DownloadProgress progress = 1;
+    // Description of the current stage of the installation.
     TaskProgress task_progress = 2;
 }
 
 message LibraryUninstallReq {
+    // Arduino Core Service instance from the `Init` response.
     Instance instance = 1;
+    // Name of the library.
     string name = 2;
+    // The version of the library to uninstall.
     string version = 3;
 }
 
 message LibraryUninstallResp {
+    // Description of the current stage of the uninstallation.
     TaskProgress task_progress = 1;
 }
 
 message LibraryUpgradeAllReq {
+    // Arduino Core Service instance from the `Init` response.
     Instance instance = 1;
 }
 
 message LibraryUpgradeAllResp {
+    // Progress of the downloads of files needed for the upgrades.
     DownloadProgress progress = 1;
+    // Description of the current stage of the upgrade.
     TaskProgress task_progress = 2;
 }
 
 message LibraryResolveDependenciesReq {
+    // Arduino Core Service instance from the `Init` response.
     Instance instance = 1;
+    // Name of the library.
     string name = 2;
+    // The version of the library to check dependencies of. If no version is
+    // specified, dependencies of the newest version will be listed.
     string version = 3;
 }
 
 message LibraryResolveDependenciesResp {
+    // Dependencies of the library.
     repeated LibraryDependencyStatus dependencies = 1;
 }
 
 message LibraryDependencyStatus {
+    // The name of the library dependency.
     string name = 1;
+    // The required version of the library dependency.
     string versionRequired = 2;
+    // Version of the library dependency currently installed.
     string versionInstalled = 3;
 }
 
 message LibrarySearchReq {
+    // Arduino Core Service instance from the `Init` response.
     Instance instance = 1;
+    // The search query.
     string query = 2;
 }
 
 enum LibrarySearchStatus {
+    // No search results were found.
     failed = 0;
+    // Search results were found.
     success = 1;
 }
 
 message LibrarySearchResp {
+    // The results of the search.
     repeated SearchedLibrary libraries = 1;
+    // Whether the search yielded results.
     LibrarySearchStatus status = 2;
 }
 
 message SearchedLibrary {
+    // Library name.
     string name = 1;
+    // The index data for the available versions of the library. The key of the
+    // map is the library version.
     map<string, LibraryRelease> releases = 2;
+    // The index data for the latest version of the library.
     LibraryRelease latest = 3;
 }
 
 message LibraryRelease {
+    // Value of the `author` field in library.properties.
     string author = 1;
+    // Value of the `version` field in library.properties.
     string version = 2;
+    // Value of the `maintainer` field in library.properties.
     string maintainer = 3;
+    // Value of the `sentence` field in library.properties.
     string sentence = 4;
+    // Value of the `paragraph` field in library.properties.
     string paragraph = 5;
+    // Value of the `url` field in library.properties.
     string website = 6;
+    // Value of the `category` field in library.properties.
     string category = 7;
+    // Value of the `architectures` field in library.properties.
     repeated string architectures = 8;
+    // The type categories of the library, as defined in the libraries index.
+    // Possible values: `Arduino`, `Partner`, `Recommended`, `Contributed`,
+    // `Retired`.
     repeated string types = 9;
+    // Information about the library archive file.
     DownloadResource resources = 10;
+    // Value of the `license` field in library.properties.
     string license = 11;
+    // Value of the `includes` field in library.properties.
     repeated string provides_includes = 12;
+    // The names of the library's dependencies, as defined by the 'depends'
+    // field of library.properties.
     repeated LibraryDependency dependencies = 13;
 }
 
 message LibraryDependency {
+    // Library name of the dependency.
     string name = 1;
+    // Version constraint of the dependency.
     string version_constraint = 2;
 }
 
 message DownloadResource {
+    // Download URL of the library archive.
     string url = 1;
+    // Filename of the library archive.
     string archivefilename = 2;
+    // Checksum of the library archive.
     string checksum = 3;
+    // File size of the library archive.
     int64  size = 4;
+    // The directory under the staging subdirectory of the data directory the
+    // library archive file will be downloaded to.
     string cachepath = 5;
 }
 
 message LibraryListReq {
+    // Arduino Core Service instance from the `Init` response.
     Instance instance = 1;
+    // Whether to include built-in libraries (from platforms and the Arduino
+    // IDE) in the listing.
     bool all = 2;
+    // Whether to list only libraries for which there is a newer version than
+    // the installed version available in the libraries index.
 	bool updatable = 3;
 }
 
 message LibraryListResp {
+    // List of installed libraries.
     repeated InstalledLibrary installed_library = 1;
 }
 
 message InstalledLibrary {
+    // Information about the library.
     Library library = 1;
+    // When the `updatable` field of the `LibraryList` request is set to `true`,
+    // this will contain information on the latest version of the library in the
+    // libraries index.
     LibraryRelease release = 2;
 }
 
 message Library {
+    // The library's directory name.
     string name = 1;
+    // Value of the `author` field in library.properties.
     string author = 2;
+    // Value of the `maintainer` field in library.properties.
     string maintainer = 3;
+    // Value of the `sentence` field in library.properties.
     string sentence = 4;
+    // Value of the `paragraph` field in library.properties.
     string paragraph = 5;
+    // Value of the `url` field in library.properties.
     string website = 6;
+    // Value of the `category` field in library.properties.
     string category = 7;
+    // Value of the `architectures` field in library.properties.
     repeated string architectures = 8;
+    // The type categories of the library. Possible values: `Arduino`,
+    // `Partner`, `Recommended`, `Contributed`, `Retired`.
     repeated string types = 9;
+    // The path of the library directory.
     string install_dir = 10;
+    // The location of the library's source files.
     string source_dir = 11;
+    // The location of the library's `utility` directory.
     string utility_dir = 12;
+    // If `location` is `platform_builtin` or `referenced_platform_builtin`, the
+    // identifying string for the platform containing the library
+    // (e.g., `arduino:avr@1.8.2`).
     string container_platform = 14;
+    // Value of the `name` field in library.properties.
     string real_name = 16;
+    // Value of the `dot_a_linkage` field in library.properties.
     bool dot_a_linkage = 17;
+    // Value of the `precompiled` field in library.properties.
     bool precompiled = 18;
+    // Value of the `ldflags` field in library.properties.
     string ld_flags = 19;
+    // A library.properties file is not present in the library's root directory.
     bool is_legacy = 20;
+    // Value of the `version` field in library.properties.
     string version = 21;
+    // Value of the `license` field in library.properties.
     string license = 22;
+    // The data from the library's library.properties file, including unused
+    // fields.
     map<string, string> properties = 23;
+    // The location type of the library installation.
     LibraryLocation location = 24;
+    // The library format type.
     LibraryLayout layout = 25;
 }
 
 enum LibraryLayout {
+    // Library is in the 1.0 Arduino library format.
     flat_layout = 0;
+    // Library is in the 1.5 Arduino library format.
     recursive_layout = 1;
 }
 
 enum LibraryLocation {
+    // In the `libraries` subdirectory of the Arduino IDE installation.
     ide_builtin = 0;
-    user = 1; // (sketchbook)
+    // In the `libraries` subdirectory of the user directory (sketchbook).
+    user = 1;
+    // In the `libraries` subdirectory of a platform.
     platform_builtin = 2;
+    // When `LibraryLocation` is used in a context where a board is specified, 
+    // this indicates the library is in the `libraries` subdirectory of a
+    // platform referenced by the board's platform.
     referenced_platform_builtin = 3;
 }