General minor improvements to docs

README.md

@@ -176,6 +176,8 @@ Please use our [issue tracker](https://github.com/caddyserver/caddy/issues) only
 
 ## About
 
+Matthew Holt began developing Caddy in 2014 while studying computer science at Brigham Young University. It soon became the first web server to use HTTPS automatically and by default, and now has hundreds of contributors and has served trillions of HTTPS requests.
+
 **The name "Caddy" is trademarked.** The name of the software is "Caddy", not "Caddy Server" or "CaddyServer". Please call it "Caddy" or, if you wish to clarify, "the Caddy web server". Caddy is a registered trademark of Stack Holdings GmbH.
 
 - _Project on Twitter: [@caddyserver](https://twitter.com/caddyserver)_

modules/caddyhttp/matchers.go

@@ -97,7 +97,8 @@ type (
 	// ```
 	MatchQuery url.Values
 
-	// MatchHeader matches requests by header fields. It performs fast,
+	// MatchHeader matches requests by header fields. The key is the field
+	// name and the array is the list of field values. It performs fast,
 	// exact string comparisons of the field values. Fast prefix, suffix,
 	// and substring matches can also be done by suffixing, prefixing, or
 	// surrounding the value with the wildcard `*` character, respectively.
@@ -114,7 +115,8 @@ type (
 	// (potentially leading to collisions).
 	MatchHeaderRE map[string]*MatchRegexp
 
-	// MatchProtocol matches requests by protocol.
+	// MatchProtocol matches requests by protocol. Recognized values are
+	// "http", "https", and "grpc".
 	MatchProtocol string
 
 	// MatchRemoteIP matches requests by client IP (or CIDR range).
@@ -139,9 +141,9 @@ type (
 	// matchers within a set work the same (i.e. different matchers in
 	// the same set are AND'ed).
 	//
-	// Note that the generated docs which describe the structure of
-	// this module are wrong because of how this type unmarshals JSON
-	// in a custom way. The correct structure is:
+	// NOTE: The generated docs which describe the structure of this
+	// module are wrong because of how this type unmarshals JSON in a
+	// custom way. The correct structure is:
 	//
 	// ```json
 	// [

modules/caddyhttp/responsematchers.go

@@ -32,7 +32,7 @@ type ResponseMatcher struct {
 
 	// If set, each header specified must be one of the
 	// specified values, with the same logic used by the
-	// request header matcher.
+	// [request header matcher](/docs/json/apps/http/servers/routes/match/header/).
 	Headers http.Header `json:"headers,omitempty"`
 }
 

modules/caddyhttp/templates/templates.go

@@ -237,7 +237,8 @@ type Templates struct {
 	// Default is text/plain, text/markdown, and text/html.
 	MIMETypes []string `json:"mime_types,omitempty"`
 
-	// The template action delimiters.
+	// The template action delimiters. If set, must be precisely two elements:
+	// the opening and closing delimiters. Default: `["{{", "}}"]`
 	Delimiters []string `json:"delimiters,omitempty"`
 }
 

modules/caddyhttp/vars.go

@@ -29,9 +29,14 @@ func init() {
 	caddy.RegisterModule(MatchVarsRE{})
 }
 
-// VarsMiddleware is an HTTP middleware which sets variables
-// in the context, mainly for use by placeholders. The
-// placeholders have the form: `{http.vars.variable_name}`
+// VarsMiddleware is an HTTP middleware which sets variables to
+// have values that can be used in the HTTP request handler
+// chain. The primary way to access variables is with placeholders,
+// which have the form: `{http.vars.variable_name}`, or with
+// the `vars` and `vars_regexp` request matchers.
+//
+// The key is the variable name, and the value is the value of the
+// variable. Both the name and value may use or contain placeholders.
 type VarsMiddleware map[string]string
 
 // CaddyModule returns the Caddy module information.

modules/caddypki/pki.go

@@ -26,10 +26,15 @@ func init() {
 }
 
 // PKI provides Public Key Infrastructure facilities for Caddy.
+//
+// This app can define certificate authorities (CAs) which are capable
+// of signing certificates. Other modules can be configured to use
+// the CAs defined by this app for issuing certificates or getting
+// key information needed for establishing trust.
 type PKI struct {
-	// The CAs to manage. Each CA is keyed by an ID that is used
-	// to uniquely identify it from other CAs. The default CA ID
-	// is "local".
+	// The certificate authorities to manage. Each CA is keyed by an
+	// ID that is used to uniquely identify it from other CAs.
+	// The default CA ID is "local".
 	CAs map[string]*CA `json:"certificate_authorities,omitempty"`
 
 	ctx caddy.Context

modules/caddytls/acmeissuer.go

@@ -36,20 +36,16 @@ func init() {
 	caddy.RegisterModule(ACMEIssuer{})
 }
 
-// ACMEIssuer makes an ACME manager
-// for managing certificates using ACME.
-//
-// TODO: support multiple ACME endpoints (probably
-// requires an array of these structs) - caddy would
-// also have to load certs from the backup CAs if the
-// first one is expired...
+// ACMEIssuer manages certificates using the ACME protocol (RFC 8555).
 type ACMEIssuer struct {
-	// The URL to the CA's ACME directory endpoint.
+	// The URL to the CA's ACME directory endpoint. Default:
+	// https://acme-v02.api.letsencrypt.org/directory
 	CA string `json:"ca,omitempty"`
 
 	// The URL to the test CA's ACME directory endpoint.
 	// This endpoint is only used during retries if there
-	// is a failure using the primary CA.
+	// is a failure using the primary CA. Default:
+	// https://acme-staging-v02.api.letsencrypt.org/directory
 	TestCA string `json:"test_ca,omitempty"`
 
 	// Your email address, so the CA can contact you if necessary.
@@ -71,6 +67,7 @@ type ACMEIssuer struct {
 	ExternalAccount *acme.EAB `json:"external_account,omitempty"`
 
 	// Time to wait before timing out an ACME operation.
+	// Default: 0 (no timeout)
 	ACMETimeout caddy.Duration `json:"acme_timeout,omitempty"`
 
 	// Configures the various ACME challenge types.

modules/caddytls/automation.go

@@ -27,8 +27,8 @@ import (
 
 // AutomationConfig governs the automated management of TLS certificates.
 type AutomationConfig struct {
-	// The list of automation policies. The first matching
-	// policy will be applied for a given certificate/name.
+	// The list of automation policies. The first policy matching
+	// a certificate or subject name will be applied.
 	Policies []*AutomationPolicy `json:"policies,omitempty"`
 
 	// On-Demand TLS defers certificate operations to the
@@ -39,7 +39,7 @@ type AutomationConfig struct {
 	// In 2015, Caddy became the first web server to
 	// implement this experimental technology.
 	//
-	// Note that this field does not enable on-demand TLS,
+	// Note that this field does not enable on-demand TLS;
 	// it only configures it for when it is used. To enable
 	// it, create an automation policy with `on_demand`.
 	OnDemand *OnDemandConfig `json:"on_demand,omitempty"`

modules/caddytls/tls.go

@@ -47,7 +47,7 @@ type TLS struct {
 	// have to be refreshed manually before they expire.
 	CertificatesRaw caddy.ModuleMap `json:"certificates,omitempty" caddy:"namespace=tls.certificates"`
 
-	// Configures the automation of certificate management.
+	// Configures certificate automation.
 	Automation *AutomationConfig `json:"automation,omitempty"`
 
 	// Configures session ticket ephemeral keys (STEKs).
@@ -527,14 +527,14 @@ type Certificate struct {
 	Tags []string
 }
 
-// AutomateLoader will automatically manage certificates for the names
-// in the list, including obtaining and renewing certificates. Automated
-// certificates are managed according to their matching automation policy,
-// configured elsewhere in this app.
+// AutomateLoader will automatically manage certificates for the names in the
+// list, including obtaining and renewing certificates. Automated certificates
+// are managed according to their matching automation policy, configured
+// elsewhere in this app.
 //
-// This is a no-op certificate loader module that is treated as a special
-// case: it uses this app's automation features to load certificates for the
-// list of hostnames, rather than loading certificates manually.
+// Technically, this is a no-op certificate loader module that is treated as
+// a special case: it uses this app's automation features to load certificates
+// for the list of hostnames, rather than loading certificates manually.
 type AutomateLoader []string
 
 // CaddyModule returns the Caddy module information.
@@ -549,8 +549,7 @@ func (AutomateLoader) CaddyModule() caddy.ModuleInfo {
 type CertCacheOptions struct {
 	// Maximum number of certificates to allow in the
 	// cache. If reached, certificates will be randomly
-	// evicted to make room for new ones. Default: 0
-	// (no limit).
+	// evicted to make room for new ones. Default: 10,000
 	Capacity int `json:"capacity,omitempty"`
 }