Improve documentation

README.md

@@ -3,8 +3,6 @@
 [![builds.sr.ht status](https://builds.sr.ht/~tslocum/desktop.svg)](https://builds.sr.ht/~tslocum/desktop)
 [![Donate](https://img.shields.io/liberapay/receives/rocketnine.space.svg?logo=liberapay)](https://liberapay.com/rocketnine.space)
 
-Desktop application library
+Desktop entry scanner and parser
 
-## Warning: Experimental
-
-Linux is the only supported platform.  Windows support is planned.
+Linux is currently the only supported operating system.  Windows support is planned.

dirs.go

@@ -7,6 +7,7 @@ import (
 	"strings"
 )
 
+// DataDirs returns a slice of directories where desktop entries are stored.
 func DataDirs() []string {
 	var dataDirs []string
 

entry.go

@@ -10,6 +10,7 @@ import (
 	"github.com/pkg/errors"
 )
 
+// EntryType may be Application, Link or Directory.
 type EntryType int
 
 const (
@@ -60,18 +61,37 @@ var quotes = map[string]string{
 	`\\\\\\\\`:   `\\\\`,
 }
 
+// Entry represents a parsed desktop entry.
 type Entry struct {
-	Type        EntryType
-	Name        string
+	// Type is the type of the entry. It may be Application, Link or Directory.
+	Type EntryType
+
+	// Name is the name of the entry.
+	Name string
+
+	// GenericName is a generic description of the entry.
 	GenericName string
-	Comment     string
-	Icon        string
-	Path        string
-	Exec        string
-	URL         string
-	Terminal    bool
+
+	// Comment is extra information about the entry.
+	Comment string
+
+	// Icon is the path to an icon file or name of a themed icon.
+	Icon string
+
+	// Path is the directory to start in.
+	Path string
+
+	// Exec is the command(s) to be executed when launched.
+	Exec string
+
+	// URL is the URL to be visited when launched.
+	URL string
+
+	// Terminal controls whether to run in a terminal.
+	Terminal bool
 }
 
+// ExpandExec fills keywords in the provided entry's Exec with user arguments.
 func (e *Entry) ExpandExec(args string) string {
 	ex := e.Exec
 
@@ -91,6 +111,7 @@ func unquoteExec(ex string) string {
 	return ex
 }
 
+// Parse reads and parses a .desktop file into an *Entry.
 func Parse(content io.Reader, buf []byte) (*Entry, error) {
 	var (
 		scanner         = bufio.NewScanner(content)

scan.go

@@ -11,7 +11,7 @@ import (
 const bufferSize = 32 * 1024
 
 type scan struct {
-	e    map[int][]*Entry
+	e    [][]*Entry
 	errs chan error
 	in   chan *scanEntry
 	sync.Mutex
@@ -23,8 +23,10 @@ type scanEntry struct {
 	f *os.File
 }
 
-func Scan(dirs []string) (map[int][]*Entry, error) {
-	s := &scan{e: make(map[int][]*Entry), errs: make(chan error), in: make(chan *scanEntry)}
+// Scan non-recursively scans provided directories for desktop entry files and
+// parses them. A slice of parsed entries is returned for each directory.
+func Scan(dirs []string) ([][]*Entry, error) {
+	s := &scan{e: make([][]*Entry, len(dirs)), errs: make(chan error), in: make(chan *scanEntry)}
 
 	for i := 0; i < runtime.GOMAXPROCS(-1); i++ {
 		go scanner(s)