update proto to add more comments

backend/protos/xyz/block/ftl/v1/language/language.proto

@@ -23,6 +23,7 @@ message ModuleConfig {
   repeated string watch = 6;
 
   // LanguageConfig contains any metadata specific to a specific language.
+  // These are stored in the ftl.toml file under the same key as the language (eg: "go", "java")
   google.protobuf.Struct language_config = 7;
 }
 
@@ -54,8 +55,11 @@ message GetCreateModuleFlagsResponse {
 // Request to create a new module.
 message CreateModuleRequest {
   string name = 1;
+  // The root path for the module, which does not yet exist.
+  // The plugin should create the directory.
   string path = 2;
 
+  // The project configuration
   ProjectConfig project_config = 3;
 
   // Flags contains any values set for those configured in the GetCreateModuleFlags call
@@ -69,46 +73,50 @@ message ModuleConfigDefaultsRequest {
   string path = 1;
 }
 
-// ModuleConfigDefaultsResponse provides defaults for ModuleConfig
+// ModuleConfigDefaultsResponse provides defaults for ModuleConfig.
+//
+// The result may be cached by FTL, so defaulting logic should not be changing due to normal module changes.
+// For example, it is valid to return defaults based on which build tool is configured within the module directory,
+// as that is not expected to change during normal operation.
+// It is not recommended to read the module's toml file to determine defaults, as when the toml file is updated,
+// the module defaults will not be recalculated.
 message ModuleConfigDefaultsResponse {
-  // default relative path to the directory containing all build artifacts for deployments
+  // Default relative path to the directory containing all build artifacts for deployments
   string deployDir = 1;
 
-  // default build command
+  // Default build command
   optional string build = 2;
 
-  // default relative path to the directory containing generated schema files
+  // Default relative path to the directory containing generated schema files
   optional string generated_schema_dir = 3;
 
-  // default patterns to watch for file changes
+  // Default patterns to watch for file changes
   repeated string watch = 4;
 
-  // TODO: doc
+  // Default language specific configuration.
+  // These defaults are filled in by looking at each root key only. If the key is not present, the default is used.
   google.protobuf.Struct language_config = 5;
 }
 
 message DependenciesRequest {
-  string path = 1;
-  ModuleConfig module_config = 2;
+  ModuleConfig module_config = 1;
 }
 
 message DependenciesResponse {
   repeated string modules = 1;
 }
 
-// Response to a dependency extraction request.
-message DependencyUpdate {
-  repeated string modules = 1;
-}
-
 // BuildContext contains contextual information needed to build.
 //
 // Plugins must include the build context's id when a build succeeds or fails.
 // For automatic rebuilds, plugins must use the most recent build context they have received.
 message BuildContext {
   string id = 1;
+  // The configuration for the module
   ModuleConfig module_config = 2;
+  // The FTL schema including all dependencies
   schema.Schema schema = 3;
+  // The dependencies for the module
   repeated string dependencies = 4;
 }
 
@@ -118,6 +126,8 @@ message BuildContextUpdatedRequest {
 
 message BuildContextUpdatedResponse {}
 
+// Error contains information about an error that occurred during a build.
+// Errors do not always cause a build failure. Use lesser levels to help guide the user.
 message Error {
   enum ErrorLevel {
     INFO = 0;
@@ -126,9 +136,15 @@ message Error {
   }
 
   string msg = 1;
-  schema.Position pos = 2;
-  int64 endColumn = 3;
   ErrorLevel level = 4;
+  Position pos = 5;
+}
+
+message Position {
+  string filename = 1;
+  int64 line = 2;
+  int64 startColumn = 3;
+  int64 endColumn = 4;
 }
 
 message ErrorList {
@@ -137,20 +153,20 @@ message ErrorList {
 
 // Request to build a module.
 message BuildRequest {
-  // The root path for the module
-  string path = 1;
   // The root path for the FTL project
-  string project_path = 2;
+  string project_path = 1;
   // Indicates whether to watch for file changes and automatically rebuild
-  bool rebuild_automatically = 3;
+  bool rebuild_automatically = 2;
 
-  BuildContext build_context = 4;
+  BuildContext build_context = 3;
 }
 
 // AutoRebuildStarted should be sent when the plugin decides to start rebuilding automatically.
 //
 // It is not required to send this event, though it helps inform the user that their changes are not yet built.
 // FTL may ignore this event if it does not match FTL's current build context and state.
+// If the plugin decides to cancel the build because another build started, no failure or cancellation event needs
+// to be sent.
 message AutoRebuildStarted {
   string context_id = 1;
 }
@@ -176,7 +192,7 @@ message BuildSuccess {
   ErrorList errors = 6;
 }
 
-// BuildFailure should be sent when a build failed.
+// BuildFailure should be sent when a build fails.
 //
 // FTL may ignore this event if it does not match FTL's current build context and state.
 message BuildFailure {
@@ -189,7 +205,8 @@ message BuildFailure {
   ErrorList errors = 3;
 
   // Indicates the plugin determined that the dependencies in the BuildContext are out of date.
-  // If a Build stream is being kept open for automatic rebuilds, FTL will call GetDependencies, followed by BuildContextUpdated.
+  // If a Build stream is being kept open for automatic rebuilds, FTL will call GetDependencies, followed by
+  // BuildContextUpdated.
   bool invalidate_dependencies = 4;
 }
 
@@ -206,7 +223,7 @@ message LogMessage {
   LogLevel level = 2;
 }
 
-// Every type of message that can be streamed from the language service for a build.
+// Every type of message that can be streamed from the language plugin for a build.
 message BuildEvent {
   oneof event {
     AutoRebuildStarted auto_rebuild_started = 2;
@@ -223,40 +240,34 @@ service LanguageService {
     option idempotency_level = NO_SIDE_EFFECTS;
   }
 
-  // TODO: docs
+  // Get language specific flags that can be used to create a new module.
   rpc GetCreateModuleFlags(GetCreateModuleFlagsRequest) returns (GetCreateModuleFlagsResponse);
 
-  // Generates files for a new empty module with the requested name
+  // Generates files for a new module with the requested name
   rpc CreateModule(CreateModuleRequest) returns (CreateModuleResponse);
 
+  // Provide default values for ModuleConfig for values that are not configured in the ftl.toml file.
   rpc ModuleConfigDefaults(ModuleConfigDefaultsRequest) returns (ModuleConfigDefaultsResponse);
 
   // Extract dependencies for a module
+  // FTL will ensure that these dependencies are built before requesting a build for this module.
   rpc GetDependencies(DependenciesRequest) returns (DependenciesResponse);
 
-  // MetadataUpdated is called whenever the metadata for a module is updated.
-  // TODO: explain this only happens while watching?
-  // TODO: merge with schema updated... to avoid double builds if both change
-  // rpc MetadataUpdated(MetadataUpdatedRequest) returns (MetadataUpdatedResponse);
-
-  // SchemaUpdated is called whenever the relevant part of a schema is updated.
-  //
-  // The schema is not the full schema, rather it only modules in this module's dependency graph.
-  // It does not contain the schema for this plugin's module.
-  //
-  // Language plugins should hold on to the latest schema they have seen.
-  // SchemaUpdated is called:
-  // - after ExtractDependencies and before Build (if there are any dependencies)
-  // - when a dependant module is updated
-  // - when the module's dependancies change
+  // Build the module and stream back build events.
+  // 
+  // A BuildSuccess or BuildFailure event must be streamed back with the request's context id to indicate the
+  // end of the build.
   //
-  // TODO: explain this only happens while watching?
-  // rpc SchemaUpdated(SchemaUpdatedRequest) returns (SchemaUpdatedResponse);
+  // The request can include the option to "rebuild_automatically". In this case the plugin should watch for
+  // file changes and automatically rebuild as needed as long as this build request is alive. Each automactic
+  // rebuild must include the latest build context id provided by the request or subsequent BuildContextUpdated
+  // calls.
+  rpc Build(BuildRequest) returns (stream BuildEvent);
 
+  // While a Build call with "rebuild_automatically" set is active, BuildContextUpdated is called whenever the
+  // build context is updated.
+  //
+  // Each time this call is made, the Build call must send back a corresponding BuildSuccess or BuildFailure
+  // event with the updated build context id with "is_automatic_rebuild" as false.
   rpc BuildContextUpdated(BuildContextUpdatedRequest) returns (BuildContextUpdatedResponse);
-
-  // Build the module
-  // The request can also indicate whether the plugin should watch for changes to the module and automatically rebuild
-  // The response stream can send LogMessages and BuildResults, and ends with a BuildResponse
-  rpc Build(BuildRequest) returns (stream BuildEvent);
 }