Update go docs

append_handler.go

@@ -13,9 +13,16 @@ type AppendHandlerOptions struct {
 	// Comparison function to determine if two keys are equal
 	KeyCompare func(a, b string) int
 
-	// Function that will be called on all root level (not in a group) attribute keys.
-	// Returns the new key value to use, and true to keep the attribute or false to drop it.
-	// Can be used to drop, keep, or rename any attributes matching the builtin attributes.
+	// Function that will be called on each attribute and group, to determine
+	// the key to use. Returns the new key value to use, and true to keep the
+	// attribute or false to drop it. Can be used to drop, keep, or rename any
+	// attributes matching the builtin attributes.
+	//
+	// The first argument is a list of currently open groups that contain the
+	// Attr. It must not be retained or modified.
+	//
+	// ResolveKey will not be called for the built-in fields on slog.Record
+	// (ie: time, level, msg, and source).
 	ResolveKey func(groups []string, key string, _ int) (string, bool)
 }
 

helpers.go

@@ -8,42 +8,45 @@ import (
 	"modernc.org/b/v2"
 )
 
-// IncrementIfBuiltinKeyConflict will, if there is a conflict/duplication at the root level (not in a group) with one of
-// the built-in keys, add "#01" to the end of the key
+// IncrementIfBuiltinKeyConflict is a ResolveKey function that will, if there is
+// a conflict/duplication at the root level (not in a group) with one of the
+// built-in keys, add "#01" to the end of the key.
 func IncrementIfBuiltinKeyConflict(groups []string, key string, index int) (string, bool) {
-	if len(groups) == 0 && DoesBuiltinKeyConflict(key) {
-		return IncrementKeyName(key, index+1), true // Don't overwrite the built-in attribute keys
+	if len(groups) == 0 && doesBuiltinKeyConflict(key) {
+		return incrementKeyName(key, index+1), true // Don't overwrite the built-in attribute keys
 	}
-	return IncrementKeyName(key, index), true
+	return incrementKeyName(key, index), true
 }
 
-// DropIfBuiltinKeyConflict will, if there is a conflict/duplication at the root level (not in a group) with one of the
+// DropIfBuiltinKeyConflict is a ResolveKey function that will, if there is a
+// conflict/duplication at the root level (not in a group) with one of the
 // built-in keys, drop the whole attribute
 func DropIfBuiltinKeyConflict(groups []string, key string, index int) (string, bool) {
-	if len(groups) == 0 && DoesBuiltinKeyConflict(key) {
+	if len(groups) == 0 && doesBuiltinKeyConflict(key) {
 		return "", false // Drop the attribute
 	}
-	return IncrementKeyName(key, index), true
+	return incrementKeyName(key, index), true
 }
 
-// KeepIfBuiltinKeyConflict will keep all keys even if there would be a conflict/duplication at the root level (not in a
+// KeepIfBuiltinKeyConflict is a ResolveKey function that will keep all keys
+// even if there would be a conflict/duplication at the root level (not in a
 // group) with one of the built-in keys
 func KeepIfBuiltinKeyConflict(_ []string, key string, index int) (string, bool) {
-	return IncrementKeyName(key, index), true // Keep all
+	return incrementKeyName(key, index), true // Keep all
 }
 
-// DoesBuiltinKeyConflict returns true if the key conflicts with the builtin keys.
+// doesBuiltinKeyConflict returns true if the key conflicts with the builtin keys.
 // This will only be called on all root level (not in a group) attribute keys.
-func DoesBuiltinKeyConflict(key string) bool {
+func doesBuiltinKeyConflict(key string) bool {
 	if key == slog.TimeKey || key == slog.LevelKey || key == slog.MessageKey || key == slog.SourceKey {
 		return true
 	}
 	return false
 }
 
-// IncrementKeyName adds a count onto the key name after the first seen.
+// incrementKeyName adds a count onto the key name after the first seen.
 // Example: keyname, keyname#01, keyname#02, keyname#03
-func IncrementKeyName(key string, index int) string {
+func incrementKeyName(key string, index int) string {
 	if index == 0 {
 		return key
 	}

ignore_handler.go

@@ -13,9 +13,16 @@ type IgnoreHandlerOptions struct {
 	// Comparison function to determine if two keys are equal
 	KeyCompare func(a, b string) int
 
-	// Function that will be called on all root level (not in a group) attribute keys.
-	// Returns the new key value to use, and true to keep the attribute or false to drop it.
-	// Can be used to drop, keep, or rename any attributes matching the builtin attributes.
+	// Function that will be called on each attribute and group, to determine
+	// the key to use. Returns the new key value to use, and true to keep the
+	// attribute or false to drop it. Can be used to drop, keep, or rename any
+	// attributes matching the builtin attributes.
+	//
+	// The first argument is a list of currently open groups that contain the
+	// Attr. It must not be retained or modified.
+	//
+	// ResolveKey will not be called for the built-in fields on slog.Record
+	// (ie: time, level, msg, and source).
 	ResolveKey func(groups []string, key string, _ int) (string, bool)
 }
 

increment_handler.go

@@ -13,16 +13,22 @@ type IncrementHandlerOptions struct {
 	// Comparison function to determine if two keys are equal
 	KeyCompare func(a, b string) int
 
-	// Function that will only be called on all root level (not in a group) attribute keys.
-	// Returns true if the key conflicts with the builtin keys.
-	//DoesBuiltinKeyConflict func(key string) bool
-
-	// IncrementKeyName should return a modified key string based on the index (first, second, third instance seen, etc)
-	//IncrementKeyName func(key string, index int) string
-
-	// Function that will be called on all root level (not in a group) attribute keys.
-	// Returns the new key value to use, and true to keep the attribute or false to drop it.
-	// Can be used to drop, keep, or rename any attributes matching the builtin attributes.
+	// Function that will be called on each attribute and group, to determine
+	// the key to use. Returns the new key value to use, and true to keep the
+	// attribute or false to drop it. Can be used to drop, keep, or rename any
+	// attributes matching the builtin attributes.
+	//
+	// For the IncrementHandler, it should return a modified key string based on
+	// the index (first = 0, second = 1, third = 2, etc).
+	// If the key is at the root level (groups is empty) and conflicts with a
+	// builtin key on the slog.Record object (time, level, msg, source), the
+	// index should be incremented before calculating the modified key string.
+	//
+	// The first argument is a list of currently open groups that contain the
+	// Attr. It must not be retained or modified.
+	//
+	// ResolveKey will not be called for the built-in fields on slog.Record
+	// (ie: time, level, msg, and source).
 	ResolveKey func(groups []string, key string, index int) (string, bool)
 }
 

overwrite_handler.go

@@ -13,9 +13,16 @@ type OverwriteHandlerOptions struct {
 	// Comparison function to determine if two keys are equal
 	KeyCompare func(a, b string) int
 
-	// Function that will be called on all root level (not in a group) attribute keys.
-	// Returns the new key value to use, and true to keep the attribute or false to drop it.
-	// Can be used to drop, keep, or rename any attributes matching the builtin attributes.
+	// Function that will be called on each attribute and group, to determine
+	// the key to use. Returns the new key value to use, and true to keep the
+	// attribute or false to drop it. Can be used to drop, keep, or rename any
+	// attributes matching the builtin attributes.
+	//
+	// The first argument is a list of currently open groups that contain the
+	// Attr. It must not be retained or modified.
+	//
+	// ResolveKey will not be called for the built-in fields on slog.Record
+	// (ie: time, level, msg, and source).
 	ResolveKey func(groups []string, key string, _ int) (string, bool)
 }
 

resolve_keys_replace_attrs.go

@@ -7,7 +7,7 @@ import (
 )
 
 // JoinResolveKey can be used to join together many slogdedup middlewares
-// ...HandlerOptions.ResolveKey functions into a single one that applies all the
+// xHandlerOptions.ResolveKey functions into a single one that applies all the
 // rules in order.
 func JoinResolveKey(resolveKeyFunctions ...func(groups []string, key string, index int) (string, bool)) func(groups []string, key string, index int) (string, bool) {
 	if len(resolveKeyFunctions) == 0 {
@@ -26,7 +26,7 @@ func JoinResolveKey(resolveKeyFunctions ...func(groups []string, key string, ind
 		if key != originalKey {
 			return key, ok
 		}
-		return IncrementKeyName(key, index), ok
+		return incrementKeyName(key, index), ok
 	}
 }
 
@@ -75,7 +75,6 @@ var sinkGraylog = sink{
 	},
 }
 
-
 // ResolveKeyStackdriver returns a ResolveKey function works for Stackdriver
 // (aka Google Cloud Operations, aka GCP Log Explorer).
 func ResolveKeyStackdriver() func(groups []string, key string, index int) (string, bool) {
@@ -171,7 +170,7 @@ type attrReplacer struct {
 }
 
 // resolveKeys returns a closure that can be used with any slogdedup middlewares
-// ...HandlerOptions.ResolveKey. Its purpose is to replace the key on any
+// xHandlerOptions.ResolveKey. Its purpose is to replace the key on any
 // attributes or groups, except for the builtin attributes. Using replaceAttr on
 // the final handler/sink is still required, in order to replace the builtin
 // attribute keys.
@@ -202,7 +201,7 @@ func resolveKeys(dest sink) func(groups []string, key string, index int) (string
 		// Check builtins last
 		for _, builtin := range dest.builtins {
 			if key == builtin {
-				return IncrementKeyName(key, index+1), true
+				return incrementKeyName(key, index+1), true
 			}
 		}
 		return key, true