doc: add detail on ShutdownStopTimeout

Also move the ShutdownStopTimeout stanza next to timeout, and make the comment
the same across the multiple components. In the future we may want to factor out
some of the common config fields into a struct that can be embedded.

cmd/boulder-wfe2/main.go

@@ -42,16 +42,19 @@ type Config struct {
 		TLSListenAddress string `validate:"omitempty,hostname_port"`
 
 		// Timeout is the per-request overall timeout. This should be slightly
-		// lower than the upstream's timeout when making requests to the WFE.
+		// lower than the upstream's timeout when making requests to this service.
 		Timeout config.Duration `validate:"-"`
 
+		// ShutdownStopTimeout determines the maximum amount of time to wait
+		// for extant request handlers to complete before exiting. It should be
+		// greater than Timeout.
+		ShutdownStopTimeout config.Duration
+
 		ServerCertificatePath string `validate:"required_with=TLSListenAddress"`
 		ServerKeyPath         string `validate:"required_with=TLSListenAddress"`
 
 		AllowOrigins []string
 
-		ShutdownStopTimeout config.Duration
-
 		SubscriberAgreementURL string
 
 		TLS cmd.TLSConfig

cmd/ocsp-responder/main.go

@@ -51,10 +51,15 @@ type Config struct {
 		// OCSP requests. This has a default value of ":80".
 		ListenAddress string `validate:"omitempty,hostname_port"`
 
-		// When to timeout a request. This should be slightly lower than the
-		// upstream's timeout when making request to ocsp-responder.
+		// Timeout is the per-request overall timeout. This should be slightly
+		// lower than the upstream's timeout when making requests to this service.
 		Timeout config.Duration `validate:"-"`
 
+		// ShutdownStopTimeout determines the maximum amount of time to wait
+		// for extant request handlers to complete before exiting. It should be
+		// greater than Timeout.
+		ShutdownStopTimeout config.Duration
+
 		// How often a response should be signed when using Redis/live-signing
 		// path. This has a default value of 60h.
 		LiveSigningPeriod config.Duration `validate:"-"`
@@ -80,8 +85,6 @@ type Config struct {
 		// 40 * 5 / 0.02 = 10,000 requests before the oldest request times out.
 		MaxSigningWaiters int `validate:"min=0"`
 
-		ShutdownStopTimeout config.Duration
-
 		RequiredSerialPrefixes []string `validate:"omitempty,dive,hexadecimal"`
 
 		Features features.Config

cmd/sfe/main.go

@@ -25,11 +25,12 @@ type Config struct {
 		ListenAddress string `validate:"omitempty,hostname_port"`
 
 		// Timeout is the per-request overall timeout. This should be slightly
-		// lower than the upstream's timeout when making requests to the SFE.
+		// lower than the upstream's timeout when making requests to this service.
 		Timeout config.Duration `validate:"-"`
 
-		// ShutdownStopTimeout is the duration that the SFE will wait before
-		// shutting down any listening servers.
+		// ShutdownStopTimeout determines the maximum amount of time to wait
+		// for extant request handlers to complete before exiting. It should be
+		// greater than Timeout.
 		ShutdownStopTimeout config.Duration
 
 		TLS cmd.TLSConfig