Another fix for Caddy's documentation generator

Also improved module documentation.

Author: liujed

app.go

@@ -16,17 +16,21 @@ func init() {
 	caddy.RegisterModule(App{})
 }
 
-// A Caddy application module that implements the dns01proxy server.
+// A proxy server for ACME DNS-01 challenges. Designed to work with acme.sh's
+// `acmeproxy`, lego's `httpreq`, and Caddy's `acmeproxy` DNS providers.
+//
+// This is a Caddy application module.
 type App struct {
 	Handler
 
 	// The server's hostnames. Used for obtaining TLS certificates.
 	Hostnames []string `json:"hostnames"`
 
-	// The sockets on which to listen.
+	// The sockets on which to listen. For example, "127.0.0.1:9095" or ":443".
 	Listen []string `json:"listen"`
 
-	// Configures the set of trusted proxies.
+	// Configures the set of trusted proxies, for accurate logging of client IP
+	// addresses.
 	TrustedProxiesRaw json.RawMessage `json:"trusted_proxies,omitempty" caddy:"namespace=http.ip_sources inline_key=source"`
 
 	// The http module instance that implements this app.

client_policy.go

@@ -14,6 +14,12 @@ type ClientPolicy struct {
 	// Identifies the client to which this policy applies.
 	UserID string `json:"user_id"`
 
+	// Determines the domains for which the user can get TLS certificates. This
+	// largely follows Smallstep's domain name rules:
+	// https://smallstep.com/docs/step-ca/policies/#domain-names
+	//
+	// Due to a limitation in ACME and DNS-01, allowing a domain alsow allows
+	// wildcard certificates for that domain.
 	AllowDomainsRaw []string `json:"allow_domains,omitempty"`
 	DenyDomainsRaw  []string `json:"deny_domains,omitempty"`
 

dns_config.go

@@ -9,19 +9,17 @@ import (
 )
 
 type DNSConfig struct {
+	// The DNS provider for publishing DNS-01 responses.
 	ProviderRaw json.RawMessage `json:"provider" caddy:"namespace=dns.providers inline_key=name"`
 
 	Provider certmagic.DNSProvider `json:"-"`
 
-	// The TTL to use for the DNS TXT records when answering challenges.
-	//
-	// XXX This should be an Optional[caddy.Duration], but Caddy's documentation
-	// generator can handle neither generics nor types with custom JSON
-	// representations.
+	// The TTL to use in DNS TXT records when answering challenges. Optional. Not
+	// usually needed.
 	TTL *caddy.Duration `json:"ttl,omitempty"`
 
-	// Custom DNS resolvers to prefer over system/built-in defaults. Often
-	// necessary to configure when using split-horizon DNS.
+	// Custom DNS resolvers to prefer over system or built-in defaults. Set this
+	// to a public resolver if you are using split-horizon DNS.
 	Resolvers []string `json:"resolvers,omitempty"`
 }
 

handler.go

@@ -28,12 +28,17 @@ func init() {
 	)
 }
 
-// A Caddy `http.handlers` module that implements the dns01proxy API.
+// Implements an API for proxying ACME DNS-01 challenges.
+//
+// This is a Caddy `http.handlers` module.
 type Handler struct {
 	DNS DNSConfig `json:"dns"`
 
-	// During provisioning, this is used to fill in [Authentication] and
-	// [ClientRegistry].
+	// Configures HTTP basic authentication and the domains for which each user
+	// can get TLS certificates.
+	//
+	// (During provisioning, this is used to fill in [Authentication] and
+	// [ClientRegistry].)
 	AccountsRaw []RawAccount `json:"accounts"`
 
 	// Specifies how clients should be authenticated. If absent, then clients must
@@ -55,7 +60,11 @@ var _ caddyfile.Unmarshaler = (*Handler)(nil)
 
 type RawAccount struct {
 	ClientPolicy
-	Password optionals.Optional[string] `json:"password"`
+
+	// The user's password, hashed using `caddy hash-password`. Optional. If
+	// omitted, then clients must be authenticated by an
+	// `http.handlers.authentication` instance earlier in the handler chain.
+	Password *string `json:"password,omitempty"`
 }
 
 func (Handler) CaddyModule() caddy.ModuleInfo {
@@ -79,10 +88,10 @@ func (h *Handler) Provision(ctx caddy.Context) error {
 	// Provision Authentication from AccountsRaw.
 	accountList := []caddyauth.Account{}
 	for _, rawAccount := range h.AccountsRaw {
-		if password, exists := rawAccount.Password.Get(); exists {
+		if rawAccount.Password != nil {
 			accountList = append(accountList, caddyauth.Account{
 				Username: rawAccount.UserID,
-				Password: password,
+				Password: *rawAccount.Password,
 			})
 		}
 	}
@@ -329,10 +338,10 @@ func (h *Handler) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
 					if !d.AllArgs((&password)) {
 						return d.ArgErr()
 					}
-					if account.Password.IsSome() {
+					if account.Password != nil {
 						return fmt.Errorf("cannot specify more than one password per user")
 					}
-					account.Password = optionals.Some(password)
+					account.Password = &password
 					continue
 
 				case "allow_domains":