revise documentation for clarity

3 files changed, 24 insertions, 23 deletions

diff --git a/README.md b/README.md
index a72a85b..056a003 100644
--- a/README.md
+++ b/README.md
@@ -12,9 +12,9 @@ for those kinds of files. If you've ever seen a program that stores its
 configurations in the `.config` directory, that program is, at least in part,
 following this specification.
 
-This crystal interface to the specification provides methods for simply listing
-the base directories, as well as a helper method for easily building file paths
-relative to them.
+This crystal interface to the specification provides two low-level methods,
+which simply list the base directories of a certain type, as well as a helper
+method for easily building file paths relative to them.
 
 
 installation
@@ -36,7 +36,7 @@ usage
 
 Suppose you're writing a program called `program_name`, and you want to read
 one of its configuration files, `file_name.conf`. After reading, you want to
-perform some operation on the contents of the file, and then write the new
+first perform some operation on the contents of the file and then write the new
 contents back to `file_name.conf`. Using this module, that might look something
 like the following:
 
@@ -46,27 +46,28 @@ require "xdg_basedir"
 # Note: for simplicity's sake, exception handling has been ignored for the
 # calls to File.read and File.write
 
-# typically, files in the XDG Base Directories will be first sorted into
-# directories, based on the program that uses them. This isn't always the case
-# however, and so it is not enforced
+# files within the XDG Base Directories will typically be further sorted into
+# subdirectories, with those directories named for the program or application
+# which `owns` them. This is not always the case however, and so isn't enforced
 read_path = XDGBasedir.full_path("program_name/file_name.conf", :config, :read)
 
-# the specification dictates that base directory locations be determined using
-# both the state of the filesystem and the state of certain environment
-# variables. it's thus possible that an appropriate base directory won't be
-# found, so a nil check is required
+# the specification dictates that the locations of base directories should be
+# determined using both the state of the filesystem and the state of certain
+# environment variables. it's thus possible that an appropriate base directory
+# won't be found, and so a nil check is required
 if read_path
   contents = File.read(read_path)
 
   # ...do something with the contents here...
 
-  # write_path here is not necessarily the same as read_path above. full_path
-  # above will check through the hierarchy of fallback base directories and, if
-  # it finds the target, return the path into the directory where it was found.
-  # there is only one base directory for writing, however, and so it is always
-  # returned here. this means that the first time program_name is run, it might
-  # read in some system-wide config, write back a user-specific config, and
-  # then read the user-specific version thereafter
+  # write_path here is not necessarily the same as read_path above. the above
+  # call to full_path will check through a hierarchy of fallback base
+  # directories and, if it finds the target file in one of them, will return a
+  # path into the directory where it was found. there is only one base
+  # directory for writing config files, however, and so it is always returned
+  # here. in practice, this means that the first time program_name is run, it
+  # might read in some system-wide config file and then write back a
+  # user-specific one
   write_path = XDGBasedir.full_path("program_name/file_name.conf", :config,
                                     :write)
 
@@ -77,9 +78,9 @@ if read_path
 end
 ```
 
-The `full_path` method takes an argument *type*, which was set above to
-`:config`. This argument indicates the type of files that are stored in the
-base directory that should be selected. There are four possible types:
+The `full_path` method takes an argument *type* (set to `:config` in the
+example above). This argument indicates that only base directories containing
+files of that *type* should be selected. There are four possible types:
 
 - `:data` directories are used for storing and retrieving persistent files
    across multiple runs of a program.
diff --git a/shard.yml b/shard.yml
index a184eab..cd8bb0a 100644
--- a/shard.yml
+++ b/shard.yml
@@ -1,5 +1,5 @@
 name: xdg_basedir
-version: 1.0.1
+version: 1.0.2
 
 authors:
   - katherine <shmibs@airen_no_jikken.icu>
diff --git a/src/xdg_basedir.cr b/src/xdg_basedir.cr
index e6e7b89..942ad36 100644
--- a/src/xdg_basedir.cr
+++ b/src/xdg_basedir.cr
@@ -20,7 +20,7 @@
 # For more details, please refer to the specification, which is available
 # online [here](https://specifications.freedesktop.org/basedir-spec/0.7/).
 module XDGBasedir
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 
   # get the base directory into which files of a given *type* should be written
   #