Update docs [ci skip]

README.md

@@ -1,17 +1,15 @@
 # Standard paths
 
-D library for getting standard paths (e.g. Pictures, Music, Documents). Inspired by QStandardPaths from Qt.
+D library for getting standard paths (e.g. Pictures, Music, Documents and also generic configuration and data paths). 
+Inspired by QStandardPaths from Qt.
 
 [![Build Status](https://travis-ci.org/MyLittleRobo/standardpaths.svg?branch=master)](https://travis-ci.org/MyLittleRobo/standardpaths)
 
 [Online documentation](http://mylittlerobo.github.io/standardpaths/standardpaths.html)
 
-Note: recently this library had functions for finding executables in directories defined by PATH environment variable. 
-This functionality was moved to the separate library. See [findexecutable](http://code.dlang.org/packages/findexecutable).
-
 ## Platform support
 
-Works on Windows, Linux, FreeBSD and Mac OS X.
+Works on Freedesktop (GNU/Linux, FreeBSD, etc.), Windows and OS X.
 
 ## Running examples
 
@@ -21,7 +19,7 @@ Prints some standard paths to stdout.
 
     dub run :printdirs --build=release
 
-On OSX it also can be built to use Cocoa instead of Carbon (tested with ldc 1.0.0):
+On OSX it also can be built to use Cocoa instead of Carbon (compiler must have proper Objective-C support. Tested with ldc 1.0.0):
 
     dub run :printdirs --config=cocoa --compiler=ldc2
 
@@ -134,11 +132,11 @@ Config readSettings()
 
 ### Freedesktop
 
-On freedesktop systems (GNU/Linux, FreeBSD, etc.) library uses [XDG Base Directory Specification](http://standards.freedesktop.org/basedir-spec/latest/index.html#introduction) and also provides behavior similiar to [xdg-user-dirs](http://www.freedesktop.org/wiki/Software/xdg-user-dirs/).
+On freedesktop systems (GNU/Linux, FreeBSD, etc.) library follows [XDG Base Directory Specification](http://standards.freedesktop.org/basedir-spec/latest/index.html#introduction) and also provides behavior similiar to [xdg-user-dirs](http://www.freedesktop.org/wiki/Software/xdg-user-dirs/).
 
 ### Windows
 
-On Windows it utilizes [SHGetSpecialFolderPath](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762204(v=vs.85).aspx).
+On Windows it utilizes [SHGetKnownFolderPath](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762188(v=vs.85).aspx) or  [SHGetSpecialFolderPath](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762204(v=vs.85).aspx) as fallback.
 
 ### Mac OS X
 

source/standardpaths.d

@@ -103,12 +103,12 @@ version(Windows) {
 enum StandardPath {
     /**
      * General location of persisted application data. Every application should have its own subdirectory here.
-     * Note: on Windows it's the same as $(B config) path.
+     * Note: on Windows it's the same as $(D config) path.
      */
     data,
     /**
      * General location of configuration files. Every application should have its own subdirectory here.
-     * Note: on Windows it's the same as $(B data) path.
+     * Note: on Windows it's the same as $(D data) path.
      */
     config,
     /**
@@ -174,10 +174,14 @@ enum FolderFlag
     none = 0,   /// Don't verify that folder exist.
     /** 
      * Create if folder does not exist. 
-     * On Windows created directory will have appropriate icon and other settings specific for this kind of folder.
+     * On Windows and OS X directory will be created using platform specific API, so it will have appropriate icon and other settings special for this kind of folder.
      */
-    create = 1, 
-    verify = 2  /// Verify that folder exists.
+    create = 1,
+    /**
+     * Verify that folder exists.
+     * On Windows directory is verified using platform specific API.
+     */
+    verify = 2
 }
 
 /**
@@ -217,7 +221,7 @@ string homeDir() nothrow @safe
 }
 
 /**
- * Getting writable path for specific locations.
+ * Get writable path for specific location.
  * Returns: Path where files of $(U type) should be written to by current user, or an empty string if could not determine path.
  * Params:
  *  type = Location to lookup.
@@ -238,23 +242,25 @@ if (downloadsDir.length) {
 string writablePath(StandardPath type, FolderFlag params = FolderFlag.none) nothrow @safe;
 
 /**
- * Getting paths for various locations.
+ * Get paths for various locations.
  * Returns: Array of paths where files of $(U type) belong including one returned by $(D writablePath), or an empty array if no paths are defined for $(U type).
  * This function does not ensure if all returned paths exist and appear to be accessible directories. Returned strings are not required to be unique.
  * Note: This function does cache its results. 
  * It may cause performance impact to call this function often since retrieving some paths can be relatively expensive operation.
  * Example:
 --------------------
 string[] templateDirs = standardPaths(StandardPath.templates);
-//List all available file templates including system defined and user specific ones.
+//List all available file templates including system defined and user created ones.
 --------------------
  * See_Also: $(D StandardPath), $(D writablePath)
  */
 string[] standardPaths(StandardPath type) nothrow @safe;
 
 /**
- * Getting writable path for specific locations appending subfolder of interest.
- * This can be useful with $(D StandardPath.config) and $(D StandardPath.data) to retrieve folder specific for application instead of generic path.
+ * Evaluate writable path for specific location and append subfolder.
+ * This can be used with $(D StandardPath.config) and $(D StandardPath.data) to retrieve folder specific for this application instead of generic path.
+ * Returns: Path where files of $(U type) should be written to by current user concatenated with subfolder, 
+ *  or an empty string if could not determine path.
  * Params:
  *  type = Location to lookup.
  *  subfolder = Subfolder that will be appended to base writable path. 
@@ -288,14 +294,14 @@ string writablePath(StandardPath type, string subfolder, FolderFlag params = Fol
 }
 
 /**
- * Getting paths for various locations appending subfolder of interest.
+ * Evaluate paths for various locations and append subfolder.
  * Example:
 --------------------
 enum organizationName = "MyLittleCompany";
 enum applicationName = "MyLittleApplication";
 
-string[] dataDirs = standardPaths(StandardPath.data, buildPath(organizationName, applicationName));
-//Gather data files from each found directory.
+string[] appDataDirs = standardPaths(StandardPath.data, buildPath(organizationName, applicationName));
+//Gather data files for this application from each found directory.
 --------------------
  */
 string[] standardPaths(StandardPath type, string subfolder) nothrow @safe