Improve clarity of yaml loading function for maintenance

-Reorganize the yaml loading function to make it more clear what is
happening.
-Comment more to to make explicitly clear what is happening.
-Remove unnecessary 'pass'
-Make a note that 'finally' should be removed when the root of the issue
is cleared up.
-Update release notes with info on change.

docs/about/release-notes.md

@@ -15,6 +15,7 @@ You can determine your currently installed version using `mkdocs --version`:
 
 ## Version 0.14.0 (2015-??-??)
 
+* Improve Unicode handling by ensuring that all YAML strings are loaded as Unicode.
 * Remove dependancy on the six library. (#583)
 * Add `--quiet` and `--verbose` options to all subcommands.
 * Add short options (`-a`) to most command line options.
@@ -252,4 +253,3 @@ documentation.
 * Bugfix: Fix the mkdocs command creation under Windows. (#122)
 * Bugfix: Correctly handle external `extra_javascript` and `extra_css`. (#92)
 * Bugfix: Fixed favicon support. (#87)
-

mkdocs/utils.py

@@ -38,28 +38,26 @@ else:                           # pragma: no cover
 
 def yaml_load(source, loader=yaml.Loader):
     """
-    Custom yaml loader.
+    Wrap PyYaml's loader so we can extend it to suit our needs.
 
     Load all strings as unicode.
     http://stackoverflow.com/a/2967461/3609487
     """
 
-    class Loader(loader):
-
-        """Custom Loader."""
-
-        pass
-
     def construct_yaml_str(self, node):
         """Override the default string handling function to always return unicode objects."""
-
         return self.construct_scalar(node)
 
+    class Loader(loader):
+        """Define a custom loader derived from the global loader to leave the global loader unaltered."""
+
+    # Attach our unicode constructor to our custom loader ensuring all strings will be unicode on translation.
     Loader.add_constructor('tag:yaml.org,2002:str', construct_yaml_str)
 
     try:
         return yaml.load(source, Loader)
     finally:
+        # TODO: Remove this when external calls are properly cleaning up file objects.
         # Some mkdocs internal calls, sometimes in test lib, will load configs
         # with a file object but never close it.  On some systems, if a delete
         # action is performed on that file without Python closing that object,