Improve package:build API docs. (#4211)

Author: davidmorgan

build/lib/src/logging.dart

@@ -10,7 +10,24 @@ const Symbol logKey = #buildLog;
 
 final _default = Logger('build.fallback');
 
-/// The log instance for the currently running BuildStep.
+/// `Logger` for use by a builder to log to the main `build_runner` output.
 ///
-/// Will be `null` when not running within a build.
+/// `build_runner` distinguishes three categories of log record:
+///
+/// Below [Level.WARNING] is called "info".
+///
+/// Info is only shown if `--verbose` was explicitly requested on the command
+/// line.
+///
+/// At [Level.WARNING] but below [Level.SEVERE] is called a "warning".
+///
+/// Warnings are aways shown, and the final build status will indicate that
+/// the build completed with warnings.
+///
+/// At or above [Level.SEVERE] is an "error".
+///
+/// Errors signal that the build step has failed: build steps that depend on the
+/// outputs will not run, and the build status will say the build failed.
+///
+/// If a builder throws an exception then it is logged as an error.
 Logger get log => Zone.current[logKey] as Logger? ?? _default;