Document that setting attributes on a collection value is a programmer error (#504)

### Motivation:

`Logger.MetadataValue.attributes` documents the setter as a no-op for
`.dictionary` and `.array`, but it calls `assertionFailure` there. Debug
builds trap, release builds do the documented no-op.

### Modifications:

Doc comment only. The assertion stays; the comment now says setting
attributes on a collection value is a programmer error, that debug
builds assert and release builds leave the value unchanged, and to set
attributes on the leaf values instead.

### Result:

The documentation matches the code. No behaviour change.

Found by an automated audit loop (Claude); patch and description
reviewed by me.
This commit is contained in:
Jeff Lenamon authored and GitHub committed 2026-09-04 09:08:57 +00:00
1 parent 172948a4b5
commit c5ece24786
1 file changed
+3 -1
+3 -1
View File
@@ -262,7 +262,9 @@ extension Logger.MetadataValue {
///
/// **Setting:** Replaces the value with `.stringConvertible(AttributedStringCarrier(...))`
/// carrying the given attributes. For `.string` and `.stringConvertible` cases the string
/// representation is preserved. For `.dictionary` and `.array` cases the setter is a no-op.
/// representation is preserved. Setting attributes on a `.dictionary` or `.array` value is a
/// programmer error: it triggers an assertion in debug builds and leaves the value unchanged in
/// release builds. Set attributes on the leaf values instead.
///
/// Only handlers that inspect attributes pay the cost of the getter check.
@inlinable