diff --git a/README.md b/README.md
index 17f5e9f..5ac27df 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,13 @@
 It supports reading from multiple files and Spring style recursive property
 expansion of expressions like '${key}' to their corresponding value.
 
-The current version supports both ISO-8859-1 and UTF-8 encoded data.
+Value expressions can refer to other keys like in '${key}' or to
+environment variables like in '${USER}'.
+
+Filenames can also contain environment variables like in
+'/home/${USER}/myapp.properties'.
+
+The properties library supports both ISO-8859-1 and UTF-8 encoded data.
 
 Install
 -------
@@ -26,6 +32,8 @@
 * Renamed from goproperties to properties
 * Added support for expansion of environment vars in
   filenames and value expressions
+* Fixed bug where value expressions were not at the
+  start of the string
 
 v1.0.0, 7 Jan 2014
 ------------------
diff --git a/doc.go b/doc.go
index 7a403ea..88261ee 100644
--- a/doc.go
+++ b/doc.go
@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// goproperties provides functions for reading and writing
+// properties provides functions for reading and writing
 // ISO-8859-1 and UTF-8 encoded .properties files and has
 // support for recursive property expansion.
 //
@@ -11,6 +11,22 @@
 // literals can be used in UTF-8 encoded properties files but
 // aren't necessary.
 //
+// To load a single properties file use MustLoadFile():
+//
+//   p := properties.MustLoadFile(filename, properties.UTF8)
+//
+// To load multiple properties files use MustLoadFiles()
+// which loads the files in the given order and merges the
+// result. Missing properties files can be ignored if the
+// 'ignoreMissing' flag is set to true.
+//
+// Filenames can contain environment variables which are expanded
+// before loading.
+//
+//   f1 := "/etc/myapp/myapp.conf"
+//   f2 := "/home/${USER}/myapp.conf"
+//   p := MustLoadFiles([]string{f1, f2}, properties.UTF8, true)
+//
 // All of the different key/value delimiters ' ', ':' and '=' are
 // supported as well as the comment characters '!' and '#' and
 // multi-line values.
@@ -29,7 +45,7 @@
 //
 // Property expansion is recursive and circular references
 // and malformed expressions are not allowed and cause an
-// error.
+// error. Expansion of environment variables is supported.
 //
 //   # standard property
 //   key = value
@@ -46,11 +62,18 @@
 //   # malformed expression (error)
 //   key = ${ke
 //
+//   # refers to the users' home dir
+//   home = ${HOME}
+//
+//   # local key takes precendence over env var: u = foo
+//   USER = foo
+//   u = ${USER}
+//
 // The default property expansion format is ${key} but can be
 // changed by setting different pre- and postfix values on the
 // Properties object.
 //
-//   p := goproperties.NewProperties()
+//   p := properties.NewProperties()
 //   p.Prefix = "#["
 //   p.Postfix = "]#"
 //