[skip changelog] Add documentation for board components of the gRPC interface (#694)

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

rpc/commands/board.proto

@@ -22,122 +22,189 @@ option go_package = "github.com/arduino/arduino-cli/rpc/commands";
 import "commands/common.proto";
 
 message BoardDetailsReq {
+    // Arduino Core Service instance from the `Init` response.
     Instance instance = 1;
+    // The fully qualified board name of the board you want information about
+    // (e.g., `arduino:avr:uno`).
     string fqbn = 2;
 }
 
 message BoardDetailsResp {
+    // The fully qualified board name of the board.
     string fqbn = 1;
+    // Name used to identify the board to humans (e.g., Arduino/Genuino Uno).
     string name = 2;
+    // Installed version of the board's platform.
     string version = 3;
+    // The board ID component of the FQBN (e.g., `uno`).
     string propertiesId = 4;
+    // Board alias that can be used as a more user friendly alternative to the
+    // FQBN.
     string alias = 5;
+    // Whether this is an official or 3rd party board.
     bool official = 6;
+    // URL of the board's pinout documentation.
     string pinout = 7;
+    // Data about the package that contains the board's platform.
     Package package = 8;
+    // Data about the board's platform.
     BoardPlatform platform = 9;
+    // Tool dependencies of the board.
     repeated ToolsDependencies toolsDependencies = 10;
+    // The board's custom configuration options.
     repeated ConfigOption config_options = 11;
+    // Identifying information for the board (e.g., USB VID/PID).
     repeated IdentificationPref identification_pref = 12;
 }
 
 message IdentificationPref {
+    // Identifying information for USB-connected boards.
     USBID usbID = 1;
 }
 
 message USBID {
+    // USB vendor ID.
     string VID = 1;
+    // USB product ID.
     string PID = 2;
 }
 
 message Package {
+    // Maintainer of the package.
     string maintainer = 1;
+    // The URL of the platforms index file
+    // (e.g., https://downloads.arduino.cc/packages/package_index.json).
     string url = 2;
+    // A URL provided by the package author, intended to point to their website.
     string websiteURL = 3;
+    // Email address of the package maintainer.
     string email = 4;
+    // Package vendor name.
     string name = 5;
+    // Resources for getting help about using the package.
     Help help = 6;
 }
 
 message Help {
+    // URL for getting online help.
     string online = 1;
 }
 
 message BoardPlatform {
+    // Architecture of the platform (e.g., `avr`).
     string architecture = 1;
+    // Category of the platform. Set to `Contributed` for 3rd party platforms.
     string category = 2;
+    // Download URL of the platform archive file.
     string url = 3;
+    // File name of the platform archive.
     string archiveFileName = 4;
+    // Checksum of the platform archive.
     string checksum = 5;
+    // File size of the platform archive.
     int64 size = 6;
+    // Name used to identify the platform to humans.
     string name = 7;
 }
 
 
 message ToolsDependencies {
+    // Vendor name of the package containing the tool definition.
     string packager = 1;
+    // Tool name.
     string name = 2;
+    // Tool version.
     string version = 3;
+    // Data for the operating system-specific builds of the tool.
     repeated Systems systems = 4;
 }
 
 message Systems {
+    // Checksum of the tool archive.
     string checksum = 1;
+    // Operating system identifier.
     string host = 2;
+    // File name of the tool archive.
     string archiveFileName = 3;
+    // Download URL of the tool archive.
     string url = 4;
+    // File size of the tool archive.
     int64 size = 5;
 }
 
 
 message ConfigOption {
+    // ID of the configuration option. For identifying the option to machines.
     string option = 1;
+    // Name of the configuration option for identifying the option to humans.
     string option_label = 2;
+    // Possible values of the configuration option.
     repeated ConfigValue values = 3;
 }
 
 message ConfigValue {
+    // The configuration option value.
     string value = 1;
+    // Label to identify the configuration option to humans.
     string value_label = 2;
+    // Whether the configuration option is selected.
     bool selected = 3;
 }
 
 message BoardAttachReq {
+    // Arduino Core Service instance from the `Init` response.
     Instance instance = 1;
+    // The board's URI (e.g., /dev/ttyACM0).
     string board_uri = 2;
+    // Path of the sketch to attach the board to. The board attachment
+    // metadata will be saved to `{sketch_path}/sketch.json`.
     string sketch_path = 3;
+    // Duration in seconds to search the given URI for a connected board before
+    // timing out. The default value is 5 seconds.
     string search_timeout = 4;
 }
 
 message BoardAttachResp {
+    // Description of the current stage of the board attachment.
     TaskProgress task_progress = 1;
 }
 
 message BoardListReq {
+    // Arduino Core Service instance from the `Init` response.
     Instance instance = 1;
 }
 
 message BoardListResp {
+    // List of ports and the boards detected on those ports.
     repeated DetectedPort ports = 1;
 }
 
 message DetectedPort {
+    // Address of the port (e.g., `serial:///dev/ttyACM0`).
     string address = 1;
+    // Protocol of the port (e.g., `serial`).
     string protocol = 2;
+    // A human friendly description of the protocol (e.g., "Serial Port (USB)").
     string protocol_label = 3;
+    // The boards attached to the port.
     repeated BoardListItem boards = 4;
 }
 
 message BoardListAllReq {
+    // Arduino Core Service instance from the `Init` response.
     Instance instance = 1;
+    // The search query to filter the board list by.
     repeated string search_args = 2;
 }
 
 message BoardListAllResp {
+    // List of installed boards.
     repeated BoardListItem boards = 1;
 }
 
 message BoardListItem {
+    // The name for use when identifying the board to a human.
     string name = 1;
+    // The fully qualified board name. Used to identify the board to a machine.
     string FQBN = 2;
 }

rpc/commands/commands.pb.go

@@ -641,8 +641,12 @@ type ArduinoCoreClient interface {
 	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)
+	// Attach a board to a sketch. When the `fqbn` field of a request is not
+	// provided, the FQBN of the attached board will be used.
 	BoardAttach(ctx context.Context, in *BoardAttachReq, opts ...grpc.CallOption) (ArduinoCore_BoardAttachClient, error)
+	// List the boards currently connected to the computer.
 	BoardList(ctx context.Context, in *BoardListReq, opts ...grpc.CallOption) (*BoardListResp, error)
+	// List all the boards provided by installed platforms.
 	BoardListAll(ctx context.Context, in *BoardListAllReq, opts ...grpc.CallOption) (*BoardListAllResp, error)
 	Compile(ctx context.Context, in *CompileReq, opts ...grpc.CallOption) (ArduinoCore_CompileClient, error)
 	// Download and install a platform and its tool dependencies.
@@ -1240,8 +1244,12 @@ type ArduinoCoreServer interface {
 	Version(context.Context, *VersionReq) (*VersionResp, error)
 	// Requests details about a board
 	BoardDetails(context.Context, *BoardDetailsReq) (*BoardDetailsResp, error)
+	// Attach a board to a sketch. When the `fqbn` field of a request is not
+	// provided, the FQBN of the attached board will be used.
 	BoardAttach(*BoardAttachReq, ArduinoCore_BoardAttachServer) error
+	// List the boards currently connected to the computer.
 	BoardList(context.Context, *BoardListReq) (*BoardListResp, error)
+	// List all the boards provided by installed platforms.
 	BoardListAll(context.Context, *BoardListAllReq) (*BoardListAllResp, error)
 	Compile(*CompileReq, ArduinoCore_CompileServer) error
 	// Download and install a platform and its tool dependencies.

rpc/commands/commands.proto

@@ -55,10 +55,14 @@ service ArduinoCore {
   // Requests details about a board
   rpc BoardDetails(BoardDetailsReq) returns (BoardDetailsResp);
 
+  // Attach a board to a sketch. When the `fqbn` field of a request is not 
+  // provided, the FQBN of the attached board will be used.
   rpc BoardAttach(BoardAttachReq) returns (stream BoardAttachResp);
 
+  // List the boards currently connected to the computer.
   rpc BoardList(BoardListReq) returns (BoardListResp);
 
+  // List all the boards provided by installed platforms.
   rpc BoardListAll(BoardListAllReq) returns (BoardListAllResp);
 
   rpc Compile(CompileReq) returns (stream CompileResp);