docs: Describe usage via swift-log (#74)

Kitura · Jul 22, 2019 · 146a36c · 146a36c
1 parent 58fdc83
commit 146a36c
Show file tree

Hide file tree

Showing 37 changed files with 2,423 additions and 403 deletions.
diff --git a/README.md b/README.md
@@ -23,13 +23,14 @@
 
 # HeliumLogger
 
-Provides a lightweight Swift logging framework which supports logging to standard output.
+Provides a lightweight logging implementation for Swift which logs to standard output.
 
 ## Features
 
 - Logs output to stdout by default. You can change the output stream, see example usage for [`HeliumStreamLogger.use(_:outputStream:)`](http://ibm-swift.github.io/HeliumLogger/Classes/HeliumStreamLogger.html#use).
 - Different logging levels such as Warning, Verbose, and Error
-  Enable/disable color output to terminal 
+- Enable/disable color output to terminal 
+- Support for the [IBM-Swift `LoggerAPI`](https://github.com/IBM-Swift/LoggerAPI) and [Swift-log `Logging`](https://github.com/apple/swift-log) logging APIs.
 
 ## Usage
 
@@ -48,14 +49,22 @@ Add `HeliumLogger` to your target's dependencies:
 ```
 #### Import packages
 
+To use with LoggerAPI:
+
 ```swift
 import HeliumLogger
 import LoggerAPI
 ```
 
+To use with swift-log:
+```swift
+import HeliumLogger
+import Logging
+```
+
 #### Initialize HeliumLogger
 
-Initialize an instance of `HeliumLogger`. Set it as the logger used by `LoggerAPI`.
+To use HeliumLogger as a logging backend for LoggerAPI:
 
 ```swift
 let logger = HeliumLogger()
@@ -67,6 +76,19 @@ or, if you don't need to customize `HeliumLogger`:
 HeliumLogger.use()
 ```
 
+To use HeliumLogger as a logging backend for swift-log:
+
+```swift
+let logger = HeliumLogger()
+LoggingSystem.bootstrap(logger.makeLogHandler)
+```
+
+Or, as a convenience:
+```swift
+HeliumLogger.bootstrapSwiftLog()
+```
+
+
 #### Logging levels
 
 You can specify the level of output on initialization. You will see output of that level, and all levels below that.
@@ -91,15 +113,17 @@ In this example, the logger will only show messages of type `warning` and `error
 HeliumLogger.use(.warning)
 ```
 
-#### Adjust logging levels at runtime
+Note that when HeliumLogger is used in conjunction with swift-log, the logging level is determined by the `Logger`, and HeliumLogger's own logging level is unused.
+
+#### Adjust logging levels at runtime (LoggerAPI)
 
 Calling `HeliumLogger.use(LoggerMessageType)` will set the `LoggerAPI` to use this new HeliumLogger instance. If in a route you detect an error with your application, you could use this to dynamically increase the log level.
 
 This new instance will not have any customization which you applied to other instances (see list item 7).
 
-#### Logging messages
+#### Logging messages (LoggerAPI)
 
-How to use HeliumLogger to log messages in your application:
+How to use HeliumLogger to log messages in your application with LoggerAPI:
 ```swift
 Log.verbose("This is a verbose log message.")
 
@@ -145,4 +169,4 @@ We love to talk server-side Swift, and Kitura. Join our [Slack](http://swift-at-
 
 ## License
 
-This library is licensed under Apache 2.0. Full license text is available in [LICENSE](https://github.com/IBM-Swift/HeliumLogger/blob/master/LICENSE.txt).
+This library is licensed under Apache 2.0. Full license text is available in [LICENSE](https://github.com/IBM-Swift/HeliumLogger/blob/master/LICENSE.txt).
diff --git a/docs/Classes.html b/docs/Classes.html
@@ -14,6 +14,7 @@
   </head>
   <body>
 
+    <a name="//apple_ref/swift/Section/Classes" class="dashAnchor"></a>
 
     <a title="Classes  Reference"></a>
 
@@ -66,11 +67,22 @@
               <li class="nav-group-task">
                 <a class="nav-group-task-link" href="Enums/HeliumLoggerFormatValues.html">HeliumLoggerFormatValues</a>
               </li>
+              <li class="nav-group-task">
+                <a class="nav-group-task-link" href="Enums/HeliumLoggerSwiftLogFormatValues.html">HeliumLoggerSwiftLogFormatValues</a>
+              </li>
               <li class="nav-group-task">
                 <a class="nav-group-task-link" href="Enums/TerminalColor.html">TerminalColor</a>
               </li>
             </ul>
           </li>
+          <li class="nav-group-name">
+            <a class="nav-group-name-link" href="Structs.html">Structures</a>
+            <ul class="nav-group-tasks">
+              <li class="nav-group-task">
+                <a class="nav-group-task-link" href="Structs/HeliumLogHandler.html">HeliumLogHandler</a>
+              </li>
+            </ul>
+          </li>
         </ul>
       </nav>
       <article class="main-content">
@@ -140,7 +152,7 @@ <h4>Declaration</h4>
                         <h4>Declaration</h4>
                         <div class="language">
                           <p class="aside-title">Swift</p>
-                          <pre class="highlight swift"><code><span class="kd">public</span> <span class="kd">class</span> <span class="kt">HeliumStreamLogger</span><span class="o">&lt;</span><span class="kt">OutputStream</span><span class="p">:</span> <span class="kt">TextOutputStream</span><span class="o">&gt;</span> <span class="p">:</span> <span class="kt"><a href="Classes/HeliumLogger.html">HeliumLogger</a></span></code></pre>
+                          <pre class="highlight swift"><code><span class="kd">public</span> <span class="kd">class</span> <span class="kt">HeliumStreamLogger</span><span class="o">&lt;</span><span class="kt">OutputStream</span><span class="o">&gt;</span> <span class="p">:</span> <span class="kt"><a href="Classes/HeliumLogger.html">HeliumLogger</a></span> <span class="k">where</span> <span class="kt">OutputStream</span> <span class="p">:</span> <span class="kt">TextOutputStream</span></code></pre>
 
                         </div>
                       </div>
@@ -155,8 +167,8 @@ <h4>Declaration</h4>
       </article>
     </div>
     <section class="footer">
-      <p>&copy; 2018 <a class="link" href="" target="_blank" rel="external">IBM</a>. All rights reserved. (Last updated: 2018-06-08)</p>
-      <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.9.1</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
+      <p>&copy; 2019 <a class="link" href="" target="_blank" rel="external">IBM</a>. All rights reserved. (Last updated: 2019-07-22)</p>
+      <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.9.6</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external">Realm</a> project.</p>
     </section>
   </body>
 </div>