[skip changelog] Add documentation for compilation components of the gRPC interface (#695)

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

rpc/commands/commands.pb.go

@@ -650,6 +650,7 @@ type ArduinoCoreClient interface {
 	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 an Arduino sketch.
 	Compile(ctx context.Context, in *CompileReq, opts ...grpc.CallOption) (ArduinoCore_CompileClient, error)
 	// Download and install a platform and its tool dependencies.
 	PlatformInstall(ctx context.Context, in *PlatformInstallReq, opts ...grpc.CallOption) (ArduinoCore_PlatformInstallClient, error)
@@ -1253,6 +1254,7 @@ type ArduinoCoreServer interface {
 	BoardList(context.Context, *BoardListReq) (*BoardListResp, error)
 	// List all the boards provided by installed platforms.
 	BoardListAll(context.Context, *BoardListAllReq) (*BoardListAllResp, error)
+	// Compile an Arduino sketch.
 	Compile(*CompileReq, ArduinoCore_CompileServer) error
 	// Download and install a platform and its tool dependencies.
 	PlatformInstall(*PlatformInstallReq, ArduinoCore_PlatformInstallServer) error

rpc/commands/commands.proto

@@ -65,6 +65,7 @@ service ArduinoCore {
   // List all the boards provided by installed platforms.
   rpc BoardListAll(BoardListAllReq) returns (BoardListAllResp);
 
+  // Compile an Arduino sketch.
   rpc Compile(CompileReq) returns (stream CompileResp);
 
   // Download and install a platform and its tool dependencies.

rpc/commands/compile.proto

@@ -22,27 +22,27 @@ option go_package = "github.com/arduino/arduino-cli/rpc/commands";
 import "commands/common.proto";
 
 message CompileReq {
-  Instance instance = 1;
-  string fqbn = 2;   // Fully Qualified Board Name, e.g.: arduino:avr:uno.
-  string sketchPath = 3;
+  Instance instance = 1;  // Arduino Core Service instance from the `Init` response.
+  string fqbn = 2;   // Fully Qualified Board Name, e.g.: `arduino:avr:uno`. If this field is not defined, the FQBN of the board attached to the sketch via the `BoardAttach` method is used.
+  string sketchPath = 3;  // The path where the sketch is stored.
   bool showProperties = 4;  // Show all build preferences used instead of compiling.
-  bool preprocess = 5;      // Print preprocessed code to stdout.
+  bool preprocess = 5;      // Print preprocessed code to stdout instead of compiling.
   string buildCachePath = 6;    // Builds of 'core.a' are saved into this path to be cached and reused.
-  string buildPath = 7;         // Path where to save compiled files.
-  repeated string buildProperties = 8; // List of custom build properties separated by commas. Or can be used multiple times for multiple properties.
-  string warnings = 9;   // Used to tell gcc which warning level to use.
+  string buildPath = 7;         // Path to use to store the files used for the compilation. If omitted, a directory will be created in the operating system's default temporary path.
+  repeated string buildProperties = 8; // List of custom build properties separated by commas.
+  string warnings = 9;   // Used to tell gcc which warning level to use. The level names are: "none", "default", "more" and "all".
   bool verbose = 10;     // Turns on verbose mode.
   bool quiet = 11;             // Suppresses almost every output.
   string vidPid = 12;   // VID/PID specific build properties.
   string exportFile = 13 [deprecated = true]; // DEPRECATED: use exportDir instead
-  int32 jobs = 14;   // The max number of concurrent compiler instances to run (as make -jx)
-  repeated string libraries = 15; // List of custom libraries paths separated by commas. Or can be used multiple times for multiple libraries paths.
-  bool optimizeForDebug = 16; // Optimize compile output for debug, not for release
-  bool dryRun = 17; // When set to true the compiled binary will not be copied to the export directory
-  string export_dir = 18; // Optional: save the build artifacts in this directory, the directory must exist
+  int32 jobs = 14;   // The max number of concurrent compiler instances to run (as `make -jx`). If jobs is set to 0, it will use the number of available CPUs as the maximum.
+  repeated string libraries = 15; // List of custom libraries paths separated by commas.
+  bool optimizeForDebug = 16; // Optimize compile output for debug, not for release.
+  bool dryRun = 17; // When set to `true` the compiled binary will not be copied to the export directory.
+  string export_dir = 18; // Optional: save the build artifacts in this directory, the directory must exist.
 }
 
 message CompileResp {
-  bytes out_stream = 1;
-  bytes err_stream = 2;
+  bytes out_stream = 1; // The output of the compilation process.
+  bytes err_stream = 2; // The error output of the compilation process.
 }