documentation update and re-organization (#381)

heckj · czechboy0 · FranzBusch · web-flow · commit 4121d24dbd71 · 2025-11-03T11:26:54.000-08:00
Provide organization (aka curation) and abstracts for all of the public
types in the library.

### Motivation:

Updates to the documentation to fill in the missing abstracts for the
provided types, updating the language to follow Apple developer content
guidelines, and fixing smaller typos and grammar issues.

### Modifications:

Curation files added to provide organization for public types, ordering
the content to align with the narrative content provided earlier.
Updating API comments, adding abstracts and parameters where missing,
and moving some of the getting started content that was previously in
the main index into a separate article.

### Result:

starting point

```
   --- Experimental coverage output enabled. ---
                | Abstract        | Curated         | Code Listing
Types           | 69% (11/16)     | 38% (6/16)      | 25% (4/16)
Members         | 57% (54/94)     | 3.2% (3/94)     | 0.0% (0/94)
Globals         | 7.1% (1/14)     | 7.1% (1/14)     | 7.1% (1/14)
```

Updated:

```
                | Abstract        | Curated         | Code Listing
Types           | 94% (15/16)     | 94% (15/16)     | 38% (6/16)
Members         | 85% (80/94)     | 97% (91/94)     | 0.0% (0/94)
Globals         | 14% (2/14)      | 100% (14/14)    | 7.1% (1/14)
```

---------

Co-authored-by: Honza Dvorsky &lt;honza@apple.com&gt;
Co-authored-by: Franz Busch &lt;privat@franz-busch.de&gt;
diff --git a/Snippets/basic-usage.swift b/Snippets/basic-usage.swift
@@ -0,0 +1,8 @@
+// Import the logging API
+import Logging
+
+// Create a logger with a label
+let logger = Logger(label: "MyLogger")
+
+// Use it to log messages
+logger.info("Hello World!")
diff --git a/Sources/Logging/Docs.docc/ImplementingALogHandler.md b/Sources/Logging/Docs.docc/ImplementingALogHandler.md
@@ -1,11 +1,10 @@
 # Implementing a log handler
 
-Create a custom logging backend that provides logging services for your apps
-and libraries.
+Create a custom logging backend that provides logging services for your apps and libraries.
 
 ## Overview
 
-To become a compatible logging backend that any `SwiftLog` consumer can use,
+To become a compatible logging backend that any SwiftLog consumer can use,
 you need to fulfill a few requirements, primarily conforming to the
 ``LogHandler`` protocol.
 
diff --git a/Sources/Logging/Docs.docc/Reference/LogHandler.md b/Sources/Logging/Docs.docc/Reference/LogHandler.md
@@ -0,0 +1,20 @@
+# ``Logging/LogHandler``
+
+## Topics
+
+### Sending log messages
+
+- ``log(level:message:metadata:source:file:function:line:)-8kgt7``
+- ``log(level:message:metadata:source:file:function:line:)-69pez``
+- ``log(level:message:metadata:file:function:line:)-89rya``
+- ``log(level:message:metadata:file:function:line:)-1xdau``
+
+### Updating metadata
+
+- ``subscript(metadataKey:)``
+
+### Inspecting a log handler
+
+- ``logLevel``
+- ``metadata``
+- ``metadataProvider``
diff --git a/Sources/Logging/Docs.docc/Reference/Logger-Level.md b/Sources/Logging/Docs.docc/Reference/Logger-Level.md
@@ -0,0 +1,13 @@
+# ``Logging/Logger/Level``
+
+## Topics
+
+### Log Levels
+
+- ``trace``
+- ``debug``
+- ``info``
+- ``notice``
+- ``warning``
+- ``error``
+- ``critical``
diff --git a/Sources/Logging/Docs.docc/Reference/Logger-Message.md b/Sources/Logging/Docs.docc/Reference/Logger-Message.md
@@ -0,0 +1,12 @@
+# ``Logging/Logger/Message``
+
+## Topics
+
+### Creating a log message
+
+- ``init(stringLiteral:)``
+
+### Inspecting a log message
+
+- ``description``
+
diff --git a/Sources/Logging/Docs.docc/Reference/Logger-MetadataProvider.md b/Sources/Logging/Docs.docc/Reference/Logger-MetadataProvider.md
@@ -0,0 +1,15 @@
+# ``Logging/Logger/MetadataProvider``
+
+## Topics
+
+### Creating a metadata provider
+
+- ``init(_:)``
+
+### Invoking the provider
+
+- ``get()``
+
+### Merging metadata
+
+- ``multiplex(_:)``
diff --git a/Sources/Logging/Docs.docc/Reference/Logger-MetadataValue.md b/Sources/Logging/Docs.docc/Reference/Logger-MetadataValue.md
@@ -0,0 +1,11 @@
+# ``Logging/Logger/MetadataValue``
+
+## Topics
+
+### Types of metadata values
+
+- ``string(_:)``
+- ``stringConvertible(_:)``
+- ``array(_:)``
+- ``dictionary(_:)``
+
diff --git a/Sources/Logging/Docs.docc/Reference/Logger.md b/Sources/Logging/Docs.docc/Reference/Logger.md
@@ -0,0 +1,60 @@
+# ``Logging/Logger``
+
+## Topics
+
+### Creating Loggers
+
+- ``init(label:)``
+- ``init(label:metadataProvider:)``
+- ``init(label:factory:)-9uiy2``
+- ``init(label:factory:)-6iktu``
+- ``MetadataProvider``
+
+### Sending trace log messages
+
+- ``trace(_:metadata:file:function:line:)``
+- ``trace(_:metadata:source:file:function:line:)``
+
+### Sending debug log messages
+- ``debug(_:metadata:file:function:line:)``
+- ``debug(_:metadata:source:file:function:line:)``
+
+### Sending info log messages
+- ``info(_:metadata:file:function:line:)``
+- ``info(_:metadata:source:file:function:line:)``
+
+### Sending notice log messages
+- ``notice(_:metadata:file:function:line:)``
+- ``notice(_:metadata:source:file:function:line:)``
+
+### Sending warning log messages
+- ``warning(_:metadata:file:function:line:)``
+- ``warning(_:metadata:source:file:function:line:)``
+
+### Sending error log messages
+- ``error(_:metadata:file:function:line:)``
+- ``error(_:metadata:source:file:function:line:)``
+
+### Sending critical log messages
+- ``critical(_:metadata:file:function:line:)``
+- ``critical(_:metadata:source:file:function:line:)``
+
+### Sending general log messages
+
+- ``log(level:_:metadata:file:function:line:)``
+- ``log(level:_:metadata:source:file:function:line:)``
+- ``Level``
+- ``Message``
+- ``Metadata``
+
+### Adjusting logger metadata
+
+- ``subscript(metadataKey:)``
+- ``MetadataValue``
+
+### Inspecting a logger
+
+- ``label``
+- ``logLevel``
+- ``handler``
+- ``metadataProvider``
diff --git a/Sources/Logging/Docs.docc/Reference/LoggingSystem.md b/Sources/Logging/Docs.docc/Reference/LoggingSystem.md
@@ -0,0 +1,13 @@
+# ``Logging/LoggingSystem``
+
+## Topics
+
+### Initializing the logging system
+
+- ``bootstrap(_:)``
+- ``bootstrap(_:metadataProvider:)``
+
+### Inspecting the logging system
+
+- ``metadataProvider``
+
diff --git a/Sources/Logging/Docs.docc/Reference/MultiplexLogHandler.md b/Sources/Logging/Docs.docc/Reference/MultiplexLogHandler.md
@@ -0,0 +1,22 @@
+# ``Logging/MultiplexLogHandler``
+
+## Topics
+
+### Creating a multiplex log handler
+
+- ``init(_:)``
+- ``init(_:metadataProvider:)``
+
+### Sending log messages
+
+- ``log(level:message:metadata:source:file:function:line:)``
+
+### Updating metadata
+
+- ``subscript(metadataKey:)``
+
+### Inspecting a log handler
+
+- ``logLevel``
+- ``metadata``
+- ``metadataProvider``
diff --git a/Sources/Logging/Docs.docc/Reference/StreamLogHandler.md b/Sources/Logging/Docs.docc/Reference/StreamLogHandler.md
@@ -0,0 +1,24 @@
+# ``Logging/StreamLogHandler``
+
+## Topics
+
+### Creating a stream log handler
+
+- ``standardOutput(label:)``
+- ``standardOutput(label:metadataProvider:)``
+- ``standardError(label:)``
+- ``standardError(label:metadataProvider:)``
+
+### Sending log messages
+
+- ``log(level:message:metadata:source:file:function:line:)``
+
+### Updating metadata
+
+- ``subscript(metadataKey:)``
+
+### Inspecting a log handler
+
+- ``logLevel``
+- ``metadata``
+- ``metadataProvider``
diff --git a/Sources/Logging/Docs.docc/Reference/SwiftLogNoOpLogHandler.md b/Sources/Logging/Docs.docc/Reference/SwiftLogNoOpLogHandler.md
@@ -0,0 +1,22 @@
+# ``Logging/SwiftLogNoOpLogHandler``
+
+## Topics
+
+### Creating a Swift Log no-op log handler
+
+- ``init()``
+- ``init(_:)``
+
+### Sending log messages
+
+- ``log(level:message:metadata:source:file:function:line:)``
+
+### Updating metadata
+
+- ``subscript(metadataKey:)``
+
+### Inspecting a log handler
+
+- ``logLevel``
+- ``metadata``
+- ``metadataProvider``
diff --git a/Sources/Logging/Docs.docc/UnderstandingLoggers.md b/Sources/Logging/Docs.docc/UnderstandingLoggers.md
@@ -0,0 +1,86 @@
+# Understanding Loggers and Log Handlers
+
+Learn how to create and configure loggers, set log levels, and use metadata to add context to your log messages.
+
+## Overview
+
+Create or retrieve a logger to get an instance for logging messages.
+Log messages have a level that you use to indicate the message's importance.
+
+SwiftLog defines seven log levels, represented by ``Logger/Level``, ordered from least to
+most severe:
+
+- ``Logger/Level/trace``
+- ``Logger/Level/debug``
+- ``Logger/Level/info``
+- ``Logger/Level/notice``
+- ``Logger/Level/warning``
+- ``Logger/Level/error``
+- ``Logger/Level/critical``
+
+Once a message is sent to a logger, a log handler processes it.
+The app using the logger configures the handler, usually for the environment in which that app runs, processing messages appropriate to that environment.
+If the app doesn't provide its own log handler, SwiftLog defaults to using a ``StreamLogHandler`` that outputs log messages to `STDOUT`.
+
+### Loggers
+
+Loggers are used to emit log messages at different severity levels:
+
+```swift
+// Informational message
+logger.info("Processing request")
+
+// Something went wrong
+logger.error("Houston, we have a problem")
+```
+
+``Logger`` is a value type with value semantics, meaning that when you modify a
+logger's configuration (like its log level or metadata), it only affects that
+specific logger instance:
+
+```swift
+let baseLogger = Logger(label: "MyApp")
+
+// Create a new logger with different configuration.
+var requestLogger = baseLogger
+requestLogger.logLevel = .debug
+requestLogger[metadataKey: "request-id"] = "\(UUID())"
+
+// baseLogger is unchanged. It still has default log level and no metadata
+// requestLogger has debug level and request-id metadata.
+```
+
+This value type behavior makes loggers safe to pass between functions and modify
+without unexpected side effects.
+
+### Log Levels
+
+Log levels can be changed per logger without affecting others:
+
+```swift
+var logger = Logger(label: "MyLogger")
+logger.logLevel = .debug
+```
+
+For guidance on what level to use for a message, see <doc:001-ChoosingLogLevels>.
+
+### Logging Metadata
+
+Metadata provides contextual information crucial for debugging:
+
+```swift
+var logger = Logger(label: "com.example.server")
+logger[metadataKey: "request.id"] = "\(UUID())"
+logger.info("Processing request")
+```
+
+Output:
+```
+2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED Processing request
+```
+
+### Source vs Label
+
+A ``Logger`` has an immutable `label` that identifies its creator, while each log
+message carries a `source` parameter that identifies where the message originated.
+Use `source` for filtering messages from specific subsystems.
diff --git a/Sources/Logging/Docs.docc/index.md b/Sources/Logging/Docs.docc/index.md
diff --git a/Sources/Logging/LogHandler.swift b/Sources/Logging/LogHandler.swift
diff --git a/Sources/Logging/Logging.swift b/Sources/Logging/Logging.swift
diff --git a/Sources/Logging/MetadataProvider.swift b/Sources/Logging/MetadataProvider.swift
