From a93c63124fec9814bd8f124089149442d3b3f4cb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Mart=C3=AD?= <mvdan@mvdan.cc>
Date: Thu, 21 Mar 2019 15:21:52 +0000
Subject: [PATCH] add some missing godocs on allocators and Run

---
 allocate.go | 23 ++++++++++++++++++-----
 context.go  |  9 +++++----
 2 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/allocate.go b/allocate.go
index 0d5c05d..30b8332 100644
--- a/allocate.go
+++ b/allocate.go
@@ -11,17 +11,24 @@ import (
 	"sync"
 )
 
+// An Allocator is responsible for creating and managing a number of browsers.
+//
+// This interface abstracts away how the browser process is actually run. For
+// example, an Allocator implementation may reuse browser processes, or connect
+// to already-running browsers on remote machines.
 type Allocator interface {
-	// Allocate creates a new browser from the pool. It can be cancelled via
-	// the provided context, at which point all the resources used by the
-	// browser (such as temporary directories) will be cleaned up.
+	// Allocate creates a new browser. It can be cancelled via the provided
+	// context, at which point all the resources used by the browser (such
+	// as temporary directories) will be freed.
 	Allocate(context.Context) (*Browser, error)
 
-	// Wait can be called after cancelling a pool's context, to block until
-	// all the pool's resources have been cleaned up.
+	// Wait can be called after cancelling an allocator's context, to block
+	// until all of its resources have been freed.
 	Wait()
 }
 
+// NewAllocator creates a new allocator context, suitable for use with
+// NewContext or Run.
 func NewAllocator(parent context.Context, opts ...AllocatorOption) (context.Context, context.CancelFunc) {
 	ctx, cancel := context.WithCancel(parent)
 	c := &Context{}
@@ -36,6 +43,7 @@ func NewAllocator(parent context.Context, opts ...AllocatorOption) (context.Cont
 
 type AllocatorOption func(*Allocator)
 
+// WithExecAllocator returns an AllocatorOption which sets up an ExecAllocator.
 func WithExecAllocator(opts ...ExecAllocatorOption) func(*Allocator) {
 	return func(p *Allocator) {
 		ep := &ExecAllocator{
@@ -53,6 +61,8 @@ func WithExecAllocator(opts ...ExecAllocatorOption) func(*Allocator) {
 
 type ExecAllocatorOption func(*ExecAllocator)
 
+// ExecAllocator is an Allocator which starts new browser processes on the host
+// machine.
 type ExecAllocator struct {
 	execPath  string
 	initFlags map[string]interface{}
@@ -141,6 +151,9 @@ func (p *ExecAllocator) Wait() {
 	p.wg.Wait()
 }
 
+// ExecPath returns an ExecAllocatorOption which uses the given path to execute
+// browser processes. The given path can be an absolute path to a binary, or
+// just the name of the program to find via exec.LookPath.
 func ExecPath(path string) ExecAllocatorOption {
 	return func(p *ExecAllocator) {
 		if fullPath, _ := exec.LookPath(path); fullPath != "" {
diff --git a/context.go b/context.go
index 703b1fb..8ea07e9 100644
--- a/context.go
+++ b/context.go
@@ -19,7 +19,7 @@ type Executor interface {
 	Execute(context.Context, string, json.Marshaler, json.Unmarshaler) error
 }
 
-// Context
+// Context is attached to any context.Context which is valid for use with Run.
 type Context struct {
 	Allocator Allocator
 
@@ -54,13 +54,15 @@ func NewContext(parent context.Context, opts ...ContextOption) (context.Context,
 
 type contextKey struct{}
 
-// FromContext creates a new browser context from the provided context.
+// FromContext extracts the Context data stored inside a context.Context.
 func FromContext(ctx context.Context) *Context {
 	c, _ := ctx.Value(contextKey{}).(*Context)
 	return c
 }
 
-// Run runs the action against the provided browser context.
+// Run runs an action against the provided context. The provided context must
+// contain a valid Allocator; typically, that will be created via NewContext or
+// NewAllocator.
 func Run(ctx context.Context, action Action) error {
 	c := FromContext(ctx)
 	if c == nil || c.Allocator == nil {
@@ -115,5 +117,4 @@ func (c *Context) newSession(ctx context.Context) error {
 	return nil
 }
 
-// ContextOption
 type ContextOption func(*Context)