Improve documentation for insert-only clients (#375)

Try to address #371 in that it's currently too hard to discover that an
insert-only client is possible, and how to initialize one. There is some
documentation on the `Queues` variable, but it's not that easy to find.

Here, add docs in a few other places under the principle that some docs
repetition isn't the worse thing in that it helps make these concepts
more obvious to find. We put docs in the README and package docs (which
mirror each other), along with some on the `river.Config` struct.

Fixes #371.

client.go

@@ -48,6 +48,12 @@ const (
 )
 
 // Config is the configuration for a Client.
+//
+// Both Queues and Workers are required for a client to work jobs, but an
+// insert-only client can be initialized by omitting Queues, and not calling
+// Start for the client. Workers can also be omitted, but it's better to include
+// it so River can check that inserted job kinds have a worker that can run
+// them.
 type Config struct {
 	// AdvisoryLockPrefix is a configurable 32-bit prefix that River will use
 	// when generating any key to acquire a Postgres advisory lock. All advisory

doc.go

@@ -64,7 +64,6 @@ goroutines at a time:
 	    },
 	    Workers: workers,
 	})
-
 	if err != nil {
 	    panic(err)
 	}
@@ -74,6 +73,22 @@ goroutines at a time:
 	    panic(err)
 	}
 
+## Insert-only clients
+
+It's often desirable to have a client that'll be used for inserting jobs, but
+not working them. This is possible by omitting the `Queues` configuration, and
+skipping the call to `Start`:
+
+	riverClient, err := river.NewClient(riverpgxv5.New(dbPool), &river.Config{
+	    Workers: workers,
+	})
+	if err != nil {
+	    panic(err)
+	}
+
+`Workers` can also be omitted, but it's better to include it so River can check
+that inserted job kinds have a worker that can run them.
+
 ## Stopping
 
 The client should also be stopped on program shutdown:
@@ -112,6 +127,9 @@ See the [`InsertAndWork` example] for complete code.
 
   - [Error and panic handling].
 
+  - [Multiple queues] to better guarantee job throughput, worker availability,
+    and isolation between components.
+
   - [Periodic and cron jobs].
 
   - [Scheduled jobs] that run automatically at their scheduled time in the
@@ -122,6 +140,8 @@ See the [`InsertAndWork` example] for complete code.
   - [Subscriptions] to queue activity and statistics, providing easy hooks for
     telemetry like logging and metrics.
 
+  - [Test helpers] to verify that jobs are inserted as expected.
+
   - [Transactional job completion] to guarantee job completion commits with
     other changes in a transaction.
 

docs/README.md

@@ -71,7 +71,6 @@ riverClient, err := river.NewClient(riverpgxv5.New(dbPool), &river.Config{
     },
     Workers: workers,
 })
-
 if err != nil {
     panic(err)
 }
@@ -82,6 +81,22 @@ if err := riverClient.Start(ctx); err != nil {
 }
 ```
 
+## Insert-only clients
+
+It's often desirable to have a client that'll be used for inserting jobs, but
+not working them. This is possible by omitting the `Queues` configuration, and
+skipping the call to `Start`:
+
+	riverClient, err := river.NewClient(riverpgxv5.New(dbPool), &river.Config{
+	    Workers: workers,
+	})
+	if err != nil {
+	    panic(err)
+	}
+
+`Workers` can also be omitted, but it's better to include it so River can check
+that inserted job kinds have a worker that can run them.
+
 ### Stopping
 
 The client should also be stopped on program shutdown: