[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.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;
 }