add docs

internal/buildengine/engine.go

@@ -498,7 +498,7 @@ func (e *Engine) watchForModuleChanges(ctx context.Context, period time.Duration
 					continue
 				}
 
-				updatedConfig, err := moduleconfig.LoadModuleConfig(event.Config.Dir)
+				updatedConfig, err := moduleconfig.LoadConfig(event.Config.Dir)
 				if err != nil {
 					logger.Errorf(err, "Could not load updated toml for %s", event.Config.Module)
 					continue

internal/buildengine/languageplugin/go_plugin_test.go

@@ -27,7 +27,7 @@ func TestExtractModuleDepsGo(t *testing.T) {
 	ctx := context.Background()
 	dir, err := filepath.Abs("../testdata/alpha")
 	assert.NoError(t, err)
-	uncheckedConfig, err := moduleconfig.LoadModuleConfig(dir)
+	uncheckedConfig, err := moduleconfig.LoadConfig(dir)
 	assert.NoError(t, err)
 
 	plugin, err := New(ctx, uncheckedConfig.Language)

internal/buildengine/languageplugin/plugin.go

@@ -58,11 +58,17 @@ func (e AutoRebuildEndedEvent) ModuleName() string { return e.Module }
 
 // LanguagePlugin handles building and scaffolding modules in a specific language.
 type LanguagePlugin interface {
-	// Topic for all update events from the plugin
+	// Updates topic for all update events from the plugin
 	// The same topic must be returned each time this method is called
 	Updates() *pubsub.Topic[PluginEvent]
 
-	// TODO: docs
+	// GetModuleConfigDefaults provides custom defaults for the module config.
+	//
+	// 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 defaults will not be recalculated.
 	ModuleConfigDefaults(ctx context.Context, dir string) (moduleconfig.CustomDefaults, error)
 
 	// GetCreateModuleFlags returns the flags that can be used to create a module for this language.

internal/moduleconfig/moduleconfig.go

@@ -48,8 +48,10 @@ func (c *ModuleConfig) UnmarshalTOML(data []byte) error {
 // This is a type alias to prevent accidental use of the wrong type.
 type AbsModuleConfig ModuleConfig
 
-// UnvalidatedModuleConfig is a ModuleConfig that has been loaded from disk
-// but has not had it's defaults set or been validated.
+// UnvalidatedModuleConfig is a ModuleConfig that holds only the values read from the toml file.
+//
+// It has not had it's defaults set or been validated, so values may be empty or invalid.
+// Use FillDefaultsAndValidate() to get a ModuleConfig.
 type UnvalidatedModuleConfig ModuleConfig
 
 type CustomDefaults struct {
@@ -64,8 +66,9 @@ type CustomDefaults struct {
 	LanguageConfig map[string]any `toml:"-"`
 }
 
-// LoadModuleConfig from a directory.
-func LoadModuleConfig(dir string) (UnvalidatedModuleConfig, error) {
+// LoadConfig from a directory.
+// This returns only the values found in the toml file. To get the full config with defaults and validation, use FillDefaultsAndValidate.
+func LoadConfig(dir string) (UnvalidatedModuleConfig, error) {
 	path := filepath.Join(dir, "ftl.toml")
 
 	// Parse toml into generic map so that we can capture language config with a dynamic key

internal/watch/discover.go

@@ -45,7 +45,7 @@ func discoverModules(dirs ...string) ([]moduleconfig.UnvalidatedModuleConfig, er
 				return nil
 			}
 			moduleDir := filepath.Dir(path)
-			config, err := moduleconfig.LoadModuleConfig(moduleDir)
+			config, err := moduleconfig.LoadConfig(moduleDir)
 			if err != nil {
 				return err
 			}

internal/watch/watch_integration_test.go

@@ -134,7 +134,7 @@ func TestWatchWithBuildAndUserModifyingFiles(t *testing.T) {
 
 func loadModule(t *testing.T, dir, name string) moduleconfig.UnvalidatedModuleConfig {
 	t.Helper()
-	config, err := moduleconfig.LoadModuleConfig(filepath.Join(dir, name))
+	config, err := moduleconfig.LoadConfig(filepath.Join(dir, name))
 	assert.NoError(t, err)
 	return config
 }