Rename SensibleDuration to ReadableDuration

Author: deanishe

background.go

@@ -18,8 +18,8 @@ import (
 	"syscall"
 )
 
-// AlreadyRunning is the error returned if a job of the given name
-// is already running.
+// AlreadyRunning is the error returned by RunInBackground if a job with
+// the given name is already running.
 type AlreadyRunning struct {
 	Name string
 	Pid  int
@@ -30,7 +30,8 @@ func (a AlreadyRunning) Error() string {
 	return fmt.Sprintf("Job '%s' already running with PID %d", a.Name, a.Pid)
 }
 
-// RunInBackground executes cmd in the background.
+// RunInBackground executes cmd in the background. It returns an
+// AlreadyRunning error if a job of the same name is already running.
 func RunInBackground(jobName string, cmd *exec.Cmd) error {
 	if IsRunning(jobName) {
 		pid, _ := getPid(jobName)
@@ -82,6 +83,7 @@ func IsRunning(jobName string) bool {
 	return true
 }
 
+// Save PID a job-specific file.
 func savePid(jobName string, pid int) error {
 	p := pidFile(jobName)
 	if err := ioutil.WriteFile(p, []byte(fmt.Sprintf("%d", pid)), 0600); err != nil {
@@ -90,6 +92,7 @@ func savePid(jobName string, pid int) error {
 	return nil
 }
 
+// Return PID for job.
 func getPid(jobName string) (int, error) {
 	p := pidFile(jobName)
 	data, err := ioutil.ReadFile(p)
@@ -103,7 +106,7 @@ func getPid(jobName string) (int, error) {
 	return pid, nil
 }
 
-// Path to PID file for jobName
+// Path to PID file for job.
 func pidFile(jobName string) string {
 	dir := EnsureExists(filepath.Join(awCacheDir(), "jobs"))
 	return filepath.Join(dir, jobName+".pid")

doc.go

@@ -36,9 +36,6 @@ Upcoming features
 
 These features are planned:
 
-	TODO: Add support for Alfred v3.2 feedback-level variables
-	TODO: Add support for Alfred v3.2 re-run feature
-	TODO: Starting and managing background processes
 	TODO: Caching and storing data
 	TODO: Alfred/AppleScript helpers?
 	TODO: Implement standard-compliant pre-release comparison in SemVer?
@@ -161,6 +158,19 @@ You can use your own backend by implementing the Releaser interface.
 The only hard requirement is support for (mostly) semantic version numbers.
 See http://semver.org for details.
 
+See examples/update for one possible way to use this API.
+
+
+Background jobs
+
+AwGo provides a simple API to start/stop background processes via the
+RunInBackground(), IsRunning() and Kill() functions. This is useful
+for running checks for updates and other jobs that hit the network or
+take a significant amount of time to complete, allowing you to keep
+your Script Filters extremely responsive.
+
+See examples/update for one possible way to use this API.
+
 
 Performance
 

update.go

@@ -150,7 +150,7 @@ func (u *Updater) CheckDue() bool {
 		return true
 	}
 	elapsed := time.Now().Sub(u.LastCheck)
-	log.Printf("%s since last check for update.", SensibleDuration(elapsed))
+	log.Printf("%s since last check for update", ReadableDuration(elapsed))
 	return elapsed.Nanoseconds() > u.UpdateInterval.Nanoseconds()
 }
 

util.go

@@ -126,9 +126,9 @@ func Pad(str, pad string, n int) string {
 	}
 }
 
-// SensibleDuration returns a sensibly-formatted string for
+// ReadableDuration returns a sensibly-formatted string for
 // non-benchmarking purposes.
-func SensibleDuration(d time.Duration) string {
+func ReadableDuration(d time.Duration) string {
 	if d.Hours() >= 72 { // 3 days
 		return fmt.Sprintf("%dd", int(d.Hours()/24))
 	}

util_test.go

@@ -95,17 +95,17 @@ func ExamplePad() {
 	// Output: ---wow----
 }
 
-func ExampleSensibleDuration() {
-	fmt.Println(SensibleDuration(time.Hour * 96))
-	fmt.Println(SensibleDuration(time.Hour * 48))
-	fmt.Println(SensibleDuration(time.Hour * 12))
-	fmt.Println(SensibleDuration(time.Minute * 130))
-	fmt.Println(SensibleDuration(time.Minute * 90))
-	fmt.Println(SensibleDuration(time.Second * 315))
-	fmt.Println(SensibleDuration(time.Second * 70))
-	fmt.Println(SensibleDuration(time.Second * 5))
-	fmt.Println(SensibleDuration(time.Millisecond * 320))
-	fmt.Println(SensibleDuration(time.Millisecond * 50))
+func ExampleReadableDuration() {
+	fmt.Println(ReadableDuration(time.Hour * 96))
+	fmt.Println(ReadableDuration(time.Hour * 48))
+	fmt.Println(ReadableDuration(time.Hour * 12))
+	fmt.Println(ReadableDuration(time.Minute * 130))
+	fmt.Println(ReadableDuration(time.Minute * 90))
+	fmt.Println(ReadableDuration(time.Second * 315))
+	fmt.Println(ReadableDuration(time.Second * 70))
+	fmt.Println(ReadableDuration(time.Second * 5))
+	fmt.Println(ReadableDuration(time.Millisecond * 320))
+	fmt.Println(ReadableDuration(time.Millisecond * 50))
 	// Output: 4d
 	// 48h
 	// 12h0m

workflow.go

@@ -903,7 +903,7 @@ func (wf *Workflow) awCacheDir() string {
 // finishLog outputs the workflow duration
 func finishLog(fatal bool) {
 	elapsed := time.Now().Sub(startTime)
-	s := Pad(fmt.Sprintf(" %s ", SensibleDuration(elapsed)), "-", 50)
+	s := Pad(fmt.Sprintf(" %s ", ReadableDuration(elapsed)), "-", 50)
 	if fatal {
 		log.Fatalln(s)
 	} else {