improve godocs

Author: gi8lino

env.go

@@ -5,8 +5,13 @@ import (
 	"os"
 )
 
-// EnvResolver resolves values using environment variables.
-// Usage: "env:MY_VAR" -> returns value of MY_VAR
+// Resolves a value from environment variables.
+// The value after the prefix should be the name of the environment variable.
+// Example:
+// "env:MY_ENV_VAR"
+// would return the value of the MY_ENV_VAR environment variable.
+//
+// If the variable is not set, an error is returned.
 type EnvResolver struct{}
 
 func (r *EnvResolver) Resolve(value string) (string, error) {

file.go

@@ -8,9 +8,15 @@ import (
 	"strings"
 )
 
-// Resolves values from key = values files. The format can be:
-// "file:/config/app.txt//Key"
-// If no key is provided, returns the whole file.
+// Resolves a value by reading a key from a plain key=value text file.
+// The value after the prefix should be in the format "path/to/file.txt//Key"
+// If no key is provided, returns the entire file as a string.
+// Example:
+// "file:/config/app.txt//USERNAME"
+// would search for a line like "USERNAME = alice" and return "alice".
+//
+// Lines are matched by exact key name before the equals sign.
+// If no key is provided (no "//" present), returns the entire file as string.
 type KeyValueFileResolver struct{}
 
 func (f *KeyValueFileResolver) Resolve(value string) (string, error) {

ini.go

@@ -8,6 +8,16 @@ import (
 	"gopkg.in/ini.v1"
 )
 
+// Resolves a value by loading an INI file and extracting a section.key pair.
+// The value after the prefix should be in the format "path/to/file.ini//Section.Key"
+// If no section is provided, the default section is used.
+// If no key is provided, returns the entire INI file as a string.
+// Example:
+// "ini:/config/app.ini//Database.User"
+// would load app.ini, locate the [Database] section, and return the value of User.
+//
+// Keys are navigated via "Section.Key" notation.
+// If no key is provided (no "//" present), returns the entire INI file as string.
 type INIResolver struct{}
 
 func (r *INIResolver) Resolve(value string) (string, error) {

json.go

@@ -32,7 +32,7 @@ func (r *JSONResolver) Resolve(value string) (string, error) {
 		return strings.TrimSpace(string(data)), nil
 	}
 
-	var content map[string]interface{}
+	var content map[string]any
 	if err := json.Unmarshal(data, &content); err != nil {
 		return "", fmt.Errorf("failed to parse JSON in '%s': %w", filePath, err)
 	}

utils.go

@@ -28,19 +28,19 @@ func splitFileAndKey(value string) (string, string) {
 //   - Take the 0th element of that slice
 //   - Expect that element to be a map with a "host" key
 //   - Return the value at "host"
-func navigateData(data interface{}, keys []string) (interface{}, error) {
+func navigateData(data any, keys []string) (any, error) {
 	current := data
 	for _, k := range keys {
 		switch curr := current.(type) {
-		case map[string]interface{}:
+		case map[string]any:
 			// Current data is a map, so k is a field name
 			val, ok := curr[k]
 			if !ok {
 				return nil, fmt.Errorf("key '%s' not found", k)
 			}
 			current = val
 
-		case []interface{}:
+		case []any:
 			// Current data is a slice, so k should be a numeric index
 			idx, err := strconv.Atoi(k)
 			if err != nil {
@@ -59,11 +59,11 @@ func navigateData(data interface{}, keys []string) (interface{}, error) {
 	return current, nil
 }
 
-// convertToMapStringInterface attempts to convert arbitrary YAML-parsed data into a map[string]interface{} for uniform handling.
+// convertToMapStringInterface attempts to convert arbitrary YAML-parsed data into a map[string]any for uniform handling.
 // It recursively ensures arrays and maps are properly converted.
-func convertToMapStringInterface(val interface{}) (map[string]interface{}, error) {
+func convertToMapStringInterface(val any) (map[string]any, error) {
 	switch v := val.(type) {
-	case map[string]interface{}:
+	case map[string]any:
 		// Recursively convert values
 		for key, val2 := range v {
 			converted, err := convertValue(val2)
@@ -75,14 +75,14 @@ func convertToMapStringInterface(val interface{}) (map[string]interface{}, error
 		return v, nil
 	default:
 		// If it's not a map at the root level, return an empty map
-		return map[string]interface{}{}, nil
+		return map[string]any{}, nil
 	}
 }
 
-func convertValue(val interface{}) (interface{}, error) {
+func convertValue(val any) (any, error) {
 	// Recursively convert slices and maps
 	switch vv := val.(type) {
-	case map[string]interface{}:
+	case map[string]any:
 		for k, v := range vv {
 			converted, err := convertValue(v)
 			if err != nil {
@@ -91,7 +91,7 @@ func convertValue(val interface{}) (interface{}, error) {
 			vv[k] = converted
 		}
 		return vv, nil
-	case []interface{}:
+	case []any:
 		for i, elem := range vv {
 			converted, err := convertValue(elem)
 			if err != nil {

utils_test.go

@@ -51,16 +51,16 @@ func TestUtils(t *testing.T) {
 	t.Run("navigateData", func(t *testing.T) {
 		t.Parallel()
 
-		data := map[string]interface{}{
-			"server": map[string]interface{}{
+		data := map[string]any{
+			"server": map[string]any{
 				"host":  "localhost",
-				"ports": []interface{}{80, 443},
-				"nested": map[string]interface{}{
+				"ports": []any{80, 443},
+				"nested": map[string]any{
 					"key": "value",
 				},
 			},
-			"array": []interface{}{
-				"zero", "one", map[string]interface{}{"nested": "val"},
+			"array": []any{
+				"zero", "one", map[string]any{"nested": "val"},
 			},
 		}
 
@@ -122,16 +122,16 @@ func TestUtils(t *testing.T) {
 
 		t.Run("TopLevelMap", func(t *testing.T) {
 			t.Parallel()
-			input := map[string]interface{}{
+			input := map[string]any{
 				"key": "value",
-				"nested": map[string]interface{}{
-					"subKey": []interface{}{"val1", "val2"},
+				"nested": map[string]any{
+					"subKey": []any{"val1", "val2"},
 				},
 			}
-			want := map[string]interface{}{
+			want := map[string]any{
 				"key": "value",
-				"nested": map[string]interface{}{
-					"subKey": []interface{}{"val1", "val2"},
+				"nested": map[string]any{
+					"subKey": []any{"val1", "val2"},
 				},
 			}
 			got, err := convertToMapStringInterface(input)
@@ -141,36 +141,36 @@ func TestUtils(t *testing.T) {
 
 		t.Run("NonMapTopLevel", func(t *testing.T) {
 			t.Parallel()
-			input := []interface{}{"val1", "val2"}
-			want := map[string]interface{}{}
+			input := []any{"val1", "val2"}
+			want := map[string]any{}
 			got, err := convertToMapStringInterface(input)
 			assert.NoError(t, err)
 			assert.Equal(t, want, got)
 		})
 
 		t.Run("AlreadyClean", func(t *testing.T) {
 			t.Parallel()
-			input := map[string]interface{}{"simple": "val"}
-			want := map[string]interface{}{"simple": "val"}
+			input := map[string]any{"simple": "val"}
+			want := map[string]any{"simple": "val"}
 			got, err := convertToMapStringInterface(input)
 			assert.NoError(t, err)
 			assert.Equal(t, want, got)
 		})
 
 		t.Run("ComplexNestedStructures", func(t *testing.T) {
 			t.Parallel()
-			input := map[string]interface{}{
-				"level1": map[string]interface{}{
-					"level2": []interface{}{
-						map[string]interface{}{"key": "val"},
+			input := map[string]any{
+				"level1": map[string]any{
+					"level2": []any{
+						map[string]any{"key": "val"},
 						"stringVal",
 					},
 				},
 			}
-			want := map[string]interface{}{
-				"level1": map[string]interface{}{
-					"level2": []interface{}{
-						map[string]interface{}{"key": "val"},
+			want := map[string]any{
+				"level1": map[string]any{
+					"level2": []any{
+						map[string]any{"key": "val"},
 						"stringVal",
 					},
 				},

yaml.go

@@ -22,12 +22,12 @@ func (r *YAMLResolver) Resolve(value string) (string, error) {
 		return "", fmt.Errorf("failed to read YAML file '%s': %w", filePath, err)
 	}
 
-	var content interface{}
+	var content any
 	if err := yaml.Unmarshal(data, &content); err != nil {
 		return "", fmt.Errorf("failed to parse YAML in '%s': %w", filePath, err)
 	}
 
-	// Convert YAML to map[string]interface{} if needed
+	// Convert YAML to map[string]any if needed
 	contentMap, err := convertToMapStringInterface(content)
 	if err != nil {
 		return "", fmt.Errorf("failed to process YAML '%s': %w", filePath, err)