documentation update and re-organization

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!")

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.
 

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``

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``

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``
+

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(_:)``

Sources/Logging/Docs.docc/Reference/Logger-MetadataValue.md

@@ -0,0 +1,11 @@
+# ``Logging/Logger/MetadataValue``
+
+## Topics
+
+### Types of metadata values
+
+- ``string(_:)``
+- ``stringConvertible(_:)``
+- ``array(_:)``
+- ``dictionary(_:)``
+

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``

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``
+

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``

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``

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``

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-uuid"] = "\(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.