Merge pull request #79 from jason-pollock/issue/78_documentation_form…

…atting_and_typos

Issue #78: Cleanup documentation

docs/01-monolog-primer.md

@@ -7,7 +7,6 @@
 - [Log Processors](#log-processors)
 - [Monolog Record Processing Workflow](#monolog-record-processing-workflow)
 
-
 ## Monolog Concepts
 
 Wonolog is a sort of "bridge" between WordPress and Monolog.
@@ -16,10 +15,9 @@ To get the best out of Wonolog, the understanding of some Monolog basics are req
 
 It is strongly suggested to read the [Monolog documentation about its core concepts](https://github.com/Seldaek/monolog/blob/master/doc/01-usage.md#core-concepts) to get a better understanding of the library.
 
-
 ## Loggers and Handlers
 
-The main objects in Monolog are *loggers*. 
+The main objects in Monolog are *loggers*.
 
 Every logger has a *channel* and one or more *handlers*.
 
@@ -39,10 +37,9 @@ And refer to [Wonolog Customization](05-wonolog-customization.md) to explore the
 
 Every Monolog handler comes with:
 
-- one or more *log processors*;
-- a minimum *log level*;
-- a *bubble* property.
-
+- One or more *log processors*;
+- A minimum *log level*;
+- A *bubble* property.
 
 ## Log Processors
 
@@ -62,15 +59,14 @@ Please refer to the [Monolog documentation](https://github.com/Seldaek/monolog/b
 
 **Wonolog ships with a default log processor that is applied by default to all log records.**
 
-This processor adds to each record the context regarding the WordPress status at the time the record was created. 
+This processor adds to each record the context regarding the WordPress status at the time the record was created.
 
 It will, in fact, add information about the kind of request (i.e., admin, AJAX, REST or XML-RPC), whether or not this is a multisite installation (and, when multisite, other multisite-specific information such as the current site ID) and the ID of the current user, if logged in.
 
 Just like any other Wonolog feature, this default processor can be customized, or even disabled.
 
 Please refer to [Wonolog Customization](05-wonolog-customization.md).
 
-
 ## Log Levels
 
 In WordPress, there is a "binary" setting for logging: `WP_DEBUG_LOG`.
@@ -94,7 +90,6 @@ They are (in descending order of severity):
 - `Logger::INFO`
 - `Logger::DEBUG`
 
-
 ## Monolog Record Processing Workflow
 
 This is the workflow Monolog uses to process a log record:
@@ -106,8 +101,7 @@ This is the workflow Monolog uses to process a log record:
 If the handler determines it has to handle the record, all processors assigned to the handler will process the record before the handler actually handles it.
 1. After a log has been handled by a handler with the "bubble" property set to `true`, the record is passed on to the next handler. This is repeated until there are no more handlers assigned to the logger, or until a handler with the "bubble" property set to `false` was encountered.
 
-
--------
+---
 
 Read next:
 
@@ -117,6 +111,6 @@ Read next:
 - [05 - Wonolog Customization](05-wonolog-customization.md) for a deep travel through all the possible configurations available for any aspect of the package.
 - [06 - Custom Hook Listeners](06-custom-hook-listeners.md) to see a complete example of a custom hook listener, its integration in Wonolog, and all the things that you need to know in order to write reusable Wonolog extensions.
 
--------
+---
 
 [< Back to Index](https://github.com/inpsyde/Wonolog/)

docs/02-basic-wonolog-concepts.md

@@ -9,7 +9,6 @@
 - [Log Record Data from Exceptions](#log-record-data-from-exceptions)
 - [Level-rich Log Hooks](#level-rich-log-hooks)
 
-
 ## Wonolog Main Logging Hook
 
 One of the goals of Wonolog is to allow for plugins and themes to be compatible with it, without requiring it as a dependency.
@@ -28,7 +27,6 @@ This is nice and easy, however, there are a few thing missing, the most importan
 
 It still works because Wonolog will _kindly_ set them according to defaults, but in general it is better to take control over this.
 
-
 ## Log Record Data
 
 In Monolog (and Wonolog), every log record comes with the following information:
@@ -60,7 +58,6 @@ If code like the above is executed without Wonolog being available, nothing (bad
 
 Moreover, at any point it would be possible to hook the log event with some other logging package, being able to log data in a different way without changing any code.
 
-
 ## Log Record Data as Wonolog Objects
 
 Even if arrays are a good way to make code to be logged not dependent on Wonolog, there are cases when it is desirable to write code that is dependent on Wonolog _on purpose_ (e.g., when you are developing a Wonolog extension).
@@ -96,7 +93,6 @@ For example, the same result of the example above could be obtained with this:
 do_action( 'wonolog.log', new Data\Critical( 'Something happened.' ) );
 ```
 
-
 ## Log Record Data from `WP_Error` Objects
 
 When dealing with WordPress code, it's easy to encounter functions that return `WP_Error` instances when something goes wrong.
@@ -137,7 +133,6 @@ Also, the channel can be set explicitly, providing a third argument:
 do_action( 'wonolog.log', $wp_error, Logger::WARNING, Channels::DEBUG );
 ```
 
-
 ## Log Record Data from Exceptions
 
 Another common use case is to log an exception thrown during execution of code.
@@ -171,7 +166,6 @@ However, it is possible to explicitly pass error level and error channel, like t
 do_action( 'wonolog.log', $exception, Logger::CRITICAL, Channels::DB );
 ```
 
-
 ## Level-rich Log Hooks
 
 So far, we only used a single Wonolog action: **`'wonolog.log'`**.
@@ -204,7 +198,7 @@ There is one hook for each of the PSR-3 log levels, so we have:
 - `'wonolog.log.notice'`
 - `'wonolog.log.info'`
 - `'wonolog.log.debug'`
-
+In case one of the above hook is used passing some data that *also* contains hook level information, the **level with higher severity _wins_**.
 In case one of the above hook is used passing some data that *also* contains hook level information, the **level with higher severity _wins_**.
 
 Let's have some examples:
@@ -227,8 +221,7 @@ do_action( 'wonolog.log.error', new Data\Debug( 'Please log me!' ) );
 do_action( 'wonolog.log.critical', new Data\Error( 'Please log me!' ) );
 ```
 
-
-----
+---
 
 Read next:
 
@@ -237,10 +230,10 @@ Read next:
 - [05 - Wonolog Customization](05-wonolog-customization.md) for a deep travel through all the possible configurations available for any aspect of the package.
 - [06 - Custom Hook Listeners](06-custom-hook-listeners.md) to see a complete example of a custom hook listener, its integration in Wonolog, and all the things that you need to know in order to write reusable Wonolog extensions.
 
-Read previous: 
+Read previous:
 
 - [01 - Monolog Primer](01-monolog-primer.md) to learn a bit more about Monolog core concepts.
 
--------
+---
 
 [< Back to Index](https://github.com/inpsyde/Wonolog/)

docs/03-a-deeper-look-at-wonolog.md

@@ -7,7 +7,6 @@
 - [Default Handler Minimum Log Level](#default-handler-minimum-log-level)
 - [The "Logging Dilemma"](#the-logging-dilemma)
 
-
 ## Wonolog Channels
 
 When installed, Wonolog comes with five default channels, mainly intended to log things that happen within WordPress core.
@@ -44,7 +43,6 @@ add_filter( 'wonolog.channels', function( array $channels ) {
 
 Please keep in mind that such customization **must be done in an MU plugin**, because Wonolog's bootstrapping assumes any configuration is done before the `'muplugins_loaded'` action, thus any customization that happens afterwards is not assured to work.
 
-
 ## Wonolog PHP Error Handler
 
 As mentioned before, by default, Wonolog logs all kinds of PHP errors. It does not log silenced PHP errors.
@@ -77,7 +75,8 @@ The **log channel** used for these events is `Channels::PHP_ERROR`, and the **lo
 Refer to [Wonolog Customization](05-wonolog-customization.md) to learn how to customize or even disable this PHP error handler.
 
 If you want to log also silenced PHP errors you can do so with a filter:
-```
+
+```php
 add_filter('wonolog.report-silenced-errors', '__return_true');
 ```
 
@@ -111,7 +110,6 @@ Refer to [Wonolog Customization](05-wonolog-customization.md), to see how Wonolo
 
 When a custom handler is in use, its minimum level is out of control for Wonolog, and so the `WP_DEBUG_LOG` or the `'WONOLOG_DEFAULT_MIN_LEVEL'` environment variable will have no effect on it.
 
-
 ## The "Logging Dilemma"
 
 A general concern with logging is that the simplest way to log any data is to put logging code side by side with code that does the business logic.
@@ -146,20 +144,19 @@ Leveraging hooks for logging is exactly what Wonolog does and suggests to do.
 
 As pretty much anything in Wonolog, this is done by specialized objects, called [**Hook Listeners**](04-hook-listeners.md).
 
-
-----
+---
 
 Read next:
 
 - [04 - Hook Listeners](04-hook-listeners.md) to read about hook listeners, the powerful feature of Wonolog that allows for logging any WordPress code.
 - [05 - Wonolog Customization](05-wonolog-customization.md) for a deep travel through all the possible configurations available for any aspect of the package.
 - [06 - Custom Hook Listeners](06-custom-hook-listeners.md) to see a complete example of a custom hook listener, its integration in Wonolog, and all the things that you need to know in order to write reusable Wonolog extensions.
 
-Read previous: 
+Read previous:
 
 - [02 - Basic Wonolog Concepts](02-basic-wonolog-concepts.md) to learn the basics of logging with Wonolog.
 - [01 - Monolog Primer](01-monolog-primer.md) to learn a bit more about Monolog core concepts.
 
--------
+---
 
 [< Back to Index](https://github.com/inpsyde/Wonolog/)

docs/04-hook-listeners.md

@@ -5,7 +5,6 @@
 - [Introducing Hook Listeners](#introducing-hook-listeners)
 - [Wonolog Hook Listeners](#wonolog-hook-listeners)
 
-
 ## Introducing Hook Listeners
 
 When Wonolog is bootstrapped **without any further configuration, it starts logging some *events* that happen in the WordPress website**.
@@ -22,7 +21,6 @@ Conceptually, a hook listener is an object that "listens to" one or more hooks t
 
 When this happens, the returned object gets logged.
 
-
 ## Wonolog Hook Listeners
 
 Wonolog ships with a few hook listeners used to log events that happen in WordPress.
@@ -43,20 +41,19 @@ Of course, it is possible to write custom hook listeners, and actually that's th
 
 Refer to [Wonolog Customization](05-wonolog-customization.md) to learn how to disable some or all of the shipped listeners, and to [Custom Hook Listeners](06-custom-hook-listeners.md) to have a look at a complete implementation of a custom hook listener and its integration with Wonolog.
 
-
--------
+---
 
 Read next:
 
 - [05 - Wonolog Customization](05-wonolog-customization.md) for a deep travel through all the possible configurations available for any aspect of the package.
 - [06 - Custom Hook Listeners](06-custom-hook-listeners.md) to see a complete example of a custom hook listener, its integration in Wonolog, and all the things that you need to know in order to write reusable Wonolog extensions.
 
-Read previous: 
+Read previous:
 
 - [03 - A Deeper Look at Wonolog](03-a-deeper-look-at-wonolog.md) to learn more advanced concepts and features of Wonolog.
 - [02 - Basic Wonolog Concepts](02-basic-wonolog-concepts.md) to learn the basics of logging with Wonolog.
 - [01 - Monolog Primer](01-monolog-primer.md) to learn a bit more about Monolog core concepts.
 
--------
+---
 
 [< Back to Index](https://github.com/inpsyde/Wonolog/)