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

per1234 · web-flow · commit 685dfaafa3bc · 2020-05-19T05:51:32.000-07:00
Comments added to the .proto files are included in the generated gRPC interface documentation.
diff --git a/rpc/commands/commands.pb.go b/rpc/commands/commands.pb.go
diff --git a/rpc/commands/commands.proto b/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.
diff --git a/rpc/commands/compile.proto b/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.
 }
