Improve docs

README.md

@@ -1,5 +1,7 @@
 
-![][icon]
+<div align="center">
+    <img src="./Icon.png" alt="AwGo Logo" title="AwGo Logo">
+</div>
 
 AwGo — A Go library for Alfred workflows
 ========================================
@@ -10,13 +12,13 @@ Features
 --------
 
 - Easy access to [Alfred context][context], such as data and cache directories.
-- Straightforward generation of [Alfred JSON feedback][feedback].
+- Fluent API for generating [Alfred JSON feedback][feedback] for Script Filters.
 - Support for all applicable Alfred features up to v3.5.
-- [Fuzzy sorting/filtering][fuzzy].
-- [Simple API][cache-api] for [caching/saving workflow data][cache].
+- [Fuzzy sorting/filtering][fuzzy] of results.
+- [Simple, but powerful, API][cache-api] for [caching/saving workflow data][cache].
 - [Catches panics, logs stack trace and shows user an error message][run].
 - Workflow [updates API][update] with built-in support for [GitHub releases][update-github].
-- [Built-in logging][logging] for easier debugging.
+- [Pre-configured logging][logging] for easier debugging, with a rotated log file.
 - ["Magic" queries/actions][magic] for simplified development and user support.
 - macOS [system icons][icons].
 
@@ -42,13 +44,17 @@ package main
 // Package is called aw
 import "github.com/deanishe/awgo"
 
+// Your workflow starts here
 func run() {
-    // Your workflow starts here
+    // Add a "Script Filter" result
     aw.NewItem("First result!")
+    // Send results to Alfred
     aw.SendFeedback()
 }
 
 func main() {
+    // Wrap your entry point with Run() to catch and log panics and
+    // show an error in Alfred instead of silently dying
     aw.Run(run)
 }
 ```
@@ -103,4 +109,3 @@ The icon is based on the [Go Gopher][gopher] by [Renee French][renee].
 [icons]: https://godoc.org/github.com/deanishe/awgo#Icon
 [examples-code]: https://github.com/deanishe/awgo/tree/master/examples
 [examples-docs]: https://godoc.org/github.com/deanishe/awgo/examples
-[icon]: https://raw.githubusercontent.com/deanishe/awgo/master/Icon.png "AwGo icon"

context_test.go

@@ -16,13 +16,13 @@ import (
 // TestContext tests Context
 func TestContext(t *testing.T) {
 	var (
-		version                  = "0.2.2"
+		version                  = "0.13"
 		name                     = "AwGo"
 		bundleID                 = "net.deanishe.awgo"
 		uid                      = "user.workflow.4B0E9731-E139-4179-BC50-D7FFF82B269A"
 		debug                    = true
-		alfredVersion            = "3.4.1"
-		alfredBuild              = "860"
+		alfredVersion            = "3.5.1"
+		alfredBuild              = "883"
 		theme                    = "alfred.theme.custom.DE3D17CA-64A2-4B42-A3F6-C71DB1201F88"
 		themeBackground          = "rgba(255,255,255,1.00)"
 		themeSelectionBackground = "rgba(255,255,255,1.00)"

doc.go

@@ -1,33 +1,36 @@
 /*
-Package aw provides utilities for building workflows for Alfred 3.
+Package aw is a utility library/framework for building workflows for Alfred.
 https://www.alfredapp.com/
 
-Alfred 2 is not supported.
+It provides APIs for interacting with Alfred (e.g. generating Script Filter
+feedback and setting workflow variables) with a host of convenience functions,
+plus support for common workflow idioms, such as caching data from
+applications/web services and running background processes to update cached
+data while keeping your workflow responsive.
 
-NOTE: This library is currently in development. The API will likely change
-as I learn to write idiomatic Go.
+NOTE: AwGo is currently in development. The API *will* change as I learn to
+write idiomatic Go, and should not be considered stable until v1.0.
 
 This library is released under the MIT licence, which you can read
 online at https://opensource.org/licenses/MIT
 
-To read this documentation on godoc.org, see
-http://godoc.org/github.com/deanishe/awgo
+Read this documentation online at http://godoc.org/github.com/deanishe/awgo
 
 
 Features
 
 The main features are:
 
 	- Easy access to Alfred context, such as data and cache directories.
-	- Straightforward generation of Alfred JSON feedback.
+	- Fluent API for generating Alfred JSON feedback for Script Filters.
 	- Support for all applicable Alfred features up to v3.5.
 	- Fuzzy sorting/filtering.
-	- Simple API for caching/saving workflow data.
+	- Simple, but powerful, API for caching/saving workflow data.
 	- Catches panics, logs stack trace and shows user an error message.
 	- Workflow updates API with built-in support for GitHub releases.
-	- (Rotated) Log file for easier debugging.
+	- Pre-configured logging for easier debugging, with a rotated log file.
 	- "Magic" queries/actions for simplified development and user support.
-	- OS X system icons.
+	- macOS system icons.
 
 
 Usage
@@ -43,14 +46,18 @@ program.go:
 	// Package is called aw
 	import "github.com/deanishe/awgo"
 
+	// Your workflow starts here
 	func run() {
-	    // Your workflow starts here
-	    aw.NewItem("First result!")
-	    aw.SendFeedback()
+		// Add a "Script Filter" result
+		aw.NewItem("First result!")
+		// Send results to Alfred
+		aw.SendFeedback()
 	}
 
 	func main() {
-	    aw.Run(run)
+		// Wrap your entry point with Run() to catch and log panics and
+		// show an error in Alfred instead of silently dying
+		aw.Run(run)
 	}
 
 In the Script Filter's Script box (Language = /bin/bash with input as
@@ -61,12 +68,15 @@ argv):
 
 The Item struct isn't intended to be used as the workflow's data model,
 just as a way to encapsulate search results for Alfred. In particular,
-its variables are only settable, not gettable.
+its variables are only settable, not gettable. However, the Feedback struct,
+to which Items belong, supports fuzzy.Interface, so in most situations, it's
+not necessary to implement fuzzy.Interface yourself in order to use fuzzy
+filtering.
 
 Most package-level functions call the methods of the same name on the default
 Workflow struct. If you want to use custom options, you can create a new
-Workflow with New(), or get the default Workflow with DefaultWorkflow()
-and configure it with Workflow.Configure().
+Workflow with New(), or reconfigure the default Workflow via the package-level
+Configure() function.
 
 Check out the examples/ subdirectory for some simple, but complete,
 workflows which you can copy to get started.
@@ -75,18 +85,18 @@ workflows which you can copy to get started.
 Fuzzy filtering
 
 Subpackage fuzzy provides a fuzzy search algorithm modelled on Sublime
-Text's search. Implement fuzzy.Interface to make a struct fuzzy-sortable.
+Text's search. Implement fuzzy.Interface to make a slice fuzzy-sortable.
 
 The Feedback struct implements this interface.
 
-Feedback and Workflow structs provide an additional Filter() method,
+Feedback and Workflow provide an additional Filter() method,
 which fuzzy-sorts the contained Items and removes any that do not match
 the query.
 
 See examples/fuzzy for a basic demonstration.
 
 See examples/bookmarks for a demonstration of implementing fuzzy.Interface
-on your own structs and customising the sort settings.
+on your own structs and customising the fuzzy sort settings.
 
 
 Sending results to Alfred
@@ -146,8 +156,10 @@ Saving and caching data
 
 Alfred provides data and cache directories for each workflow. The data
 directory is for permanent data and the cache directory for temporary data.
+You should use the CacheDir() and DataDir() methods to get the paths to
+these directories, as the methods will ensure that the directories exist.
 
-AwGo's Workflow struct has a simple API for caching data to these
+AwGo's Workflow struct has a simple API for saving data to these
 directories. There are basic load/store methods for saving bytes or
 (un)marshalling structs to/from JSON, plus LoadOrStore methods that return
 cached data if they exist and are new enough, or refresh the cache via a

env.sh

@@ -1,4 +1,5 @@
 # Workflow environment variables
+# These variables create an Alfred-like environment
 
 export alfred_debug="1"
 export alfred_preferences="$HOME/Dropbox/Config/Alfred 3/Alfred.alfredpreferences"
@@ -7,11 +8,11 @@ export alfred_theme="alfred.theme.custom.DE3D17CA-64A2-4B42-A3F6-C71DB1201F88"
 export alfred_theme_background="rgba(255,255,255,1.00)"
 export alfred_theme_selection_background="rgba(255,255,255,1.00)"
 export alfred_theme_subtext="0"
-export alfred_version="3.4.1"
-export alfred_version_build="860"
+export alfred_version="3.5.1"
+export alfred_version_build="883"
 export alfred_workflow_bundleid="net.deanishe.awgo"
 export alfred_workflow_cache="$HOME/Library/Caches/com.runningwithcrayons.Alfred-3/Workflow Data/net.deanishe.awgo"
 export alfred_workflow_data="$HOME/Library/Application Support/Alfred 3/Workflow Data/net.deanishe.awgo"
 export alfred_workflow_name="AwGo"
 export alfred_workflow_uid="user.workflow.4B0E9731-E139-4179-BC50-D7FFF82B269A"
-export alfred_workflow_version="0.2.2"
+export alfred_workflow_version="0.13"

info.plist

@@ -23,7 +23,7 @@
 	<key>webaddress</key>
 	<string>https://github.com/deanishe/awgo</string>
     <key>version</key>
-    <string>0.2.2</string>
+    <string>0.13</string>
 	<key>variables</key>
 	<dict>
 		<key>exported_var</key>

magic.go

@@ -93,32 +93,47 @@ func (ma MagicActions) Args(args []string, prefix string) []string {
 	return args
 }
 
-// MagicAction is a command that can be called directly by AwGo if its
-// keyword is passed in a user query. These are mainly aimed at making
-// debugging and supporting users easier: the built-in actions open the
-// log file and data/cache directories, and can also clear them.
-// This saves users (and developers) from having to mess around in Finder
-// to dig out files buried somewhere deep in ~/Library.
+// MagicAction is a command that is called directly by AwGo (i.e. your workflow
+// code is not run) if its keyword is passed in a user query. Magic Actions are
+// mainly aimed at making debugging and supporting users easier (via the
+// built-in actions), but it also provides a simple way to integrate your own
+// commands that don't need a "real" UI (via Item.Autocomplete("<prefix>:XYZ")
+// + Item.Valid(false)).
 //
-// If you call Args() or Workflow.Args(), they return os.Args[1:], but
-// first check if any argument starts with the "magic" prefix ("workflow:")
-// by default.
+// The "update" sub-package registers a Magic Action to check for and install
+// an update, for example.
+//
+// The built-in Magic Actions provide useful functions for debugging problems
+// with workflows, so you, the developer, don't have to implement them yourself
+// and don't have to hand-hold users through the process of digging out files
+// buried somewhere deep in ~/Library. For example, you can simply request that
+// a user enter "workflow:log" to open the log file or "workflow:delcache" to
+// delete any cached data, instead of asking them to root around somewhere in
+// ~/Library.
+//
+// To use Magic Actions, it's imperative that your workflow retrieves
+// command-line arguments via Args()/Workflow.Args() instead of accessing
+// os.Args directly (or at least calls Args()/Workflow.Args()).
+//
+// These functions return os.Args[1:], but first check if any argument starts
+// with the "magic" prefix ("workflow:" by default).
 //
 // If so, AwGo will take control of the workflow (i.e. your code will no
 // longer be run) and run its own "magic" mode. In this mode, it checks
 // if the rest of the user query matches the keyword for a registered
 // MagicAction, and if so, it runs that action, displaying RunText() in
-// Alfred (if it's a Script Filter) and the log & debugger.
+// Alfred (if it's a Script Filter) and the log file & debugger.
 //
 // If no keyword matches, AwGo sends a list of available magic actions
 // to Alfred, filtered by the user's query. Hitting TAB or RETURN on
 // an item will run it.
 //
+//
 // The built-in magic actions are:
 //
 //    Keyword           | Action
 //    --------------------------------------------------------------------------------------
-//    <prefix>log       | Open workflow's log file in the default app (usually Console.log).
+//    <prefix>log       | Open workflow's log file in the default app (usually Console).
 //    <prefix>data      | Open workflow's data directory in the default app (usually Finder).
 //    <prefix>cache     | Open workflow's data directory in the default app (usually Finder).
 //    <prefix>deldata   | Delete everything in the workflow's data directory.
@@ -132,15 +147,17 @@ func (ma MagicActions) Args(args []string, prefix string) []string {
 //
 type MagicAction interface {
 	// Keyword is what the user must enter to run the action after
-	// AwGo has recognised the magic prefix.
+	// AwGo has recognised the magic prefix. So if the prefix is "workflow:"
+	// (the default), a user must enter the query "workflow:<keyword>" to
+	// execute this action.
 	Keyword() string
 	// Description is shown when a user has entered "magic" mode, but
 	// the query does not yet match a keyword.
 	Description() string
-	// RunText is sent to Alfred and written to the log & debugger when
+	// RunText is sent to Alfred and written to the log file & debugger when
 	// the action is run.
 	RunText() string
-	// Run executes the magic action.
+	// Run is called when the Magic Action is triggered.
 	Run() error
 }
 

workflow_test.go

@@ -68,7 +68,7 @@ func ExampleNew() {
 	fmt.Println(wf.Version())
 	// Output:
 	// net.deanishe.awgo
-	// 0.2.2
+	// 0.13
 }
 
 // Pass one or more Options to New() to configure the created Workflow.