README | 8 +++++++-
 r.go   | 9 +++++++--

diff --git a/README b/README
index 4287715a274f86a4bd936265786d3f5fd4b34953bbfe5ca513b8273f1e610832..100bc548657b087725a943f931315c1785ad0e2e6e2658cb9ad044444a73f8d9 100644
--- a/README
+++ b/README
@@ -1 +1,7 @@
-GNU recutils'es recfile parser on pure Go.
+GNU recutils'es recfile parser on pure Go. recfiles are human-editable,
+plaintext databases. This library allows you to read records and their
+fields from it. Look for cmd/gorecsel as an example usage.
+
+* iterate through the records and their fields
+* ignore comments
+* support continuation lines (\$) and multilines (^+)
diff --git a/r.go b/r.go
index 903240dc14fe8e1faa0ce65c4b9b7557682aed32babd607111e366d93287edf3..019e68c0452cc2cf9300ef39a93d05a02237b11448a0e5ecb93c74e404fd847e 100644
--- a/r.go
+++ b/r.go
@@ -15,6 +15,7 @@ You should have received a copy of the GNU General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+// GNU recutils'es recfiles parser on pure Go
 package recfile
 
 import (
@@ -25,10 +26,14 @@ 	"regexp"
 	"strings"
 )
 
+var KeyValRe = regexp.MustCompile(`([a-zA-Z%][a-zA-Z0-9_]*):\s*(.*)$`)
+
 type Reader struct {
 	scanner *bufio.Scanner
 }
 
+// Create Reader for iterating through the records. It uses
+// bufio.Scanner, so can read more than currently parsed records take.
 func NewReader(r io.Reader) *Reader {
 	return &Reader{bufio.NewScanner(r)}
 }
@@ -38,8 +43,8 @@ 	Name  string
 	Value string
 }
 
-var KeyValRe = regexp.MustCompile(`([a-zA-Z%][a-zA-Z0-9_]*):\s*(.*)$`)
-
+// Get next record. Each record is just a collection of fields. io.EOF
+// is returned if there is nothing to read more.
 func (r *Reader) Next() ([]Field, error) {
 	fields := make([]Field, 0, 1)
 	var text string