From 95ed603de79c66ff76bfe7e42986a2fc8c7a1fa4 Mon Sep 17 00:00:00 2001
From: Matthew Holt <mholt@users.noreply.github.com>
Date: Mon, 23 Dec 2019 12:45:35 -0700
Subject: Improve godocs all around

These will be used in the new automated documentation system
---
 modules/caddyhttp/headers/headers.go | 54 +++++++++++++++++++++++++++---------
 1 file changed, 41 insertions(+), 13 deletions(-)

(limited to 'modules/caddyhttp/headers')

diff --git a/modules/caddyhttp/headers/headers.go b/modules/caddyhttp/headers/headers.go
index f53e859..ad6c08b 100644
--- a/modules/caddyhttp/headers/headers.go
+++ b/modules/caddyhttp/headers/headers.go
@@ -28,7 +28,18 @@ func init() {
 	caddy.RegisterModule(Handler{})
 }
 
-// Handler is a middleware which can mutate HTTP headers.
+// Handler is a middleware which modifies request and response headers.
+//
+// Changes to headers are applied immediately, except for the response
+// headers when Deferred is true or when Required is set. In those cases,
+// the changes are applied when the headers are written to the response.
+// Note that deferred changes do not take effect if an error occurs later
+// in the middleware chain.
+//
+// Properties in this module accept placeholders.
+//
+// Response header operations can be conditioned upon response status code
+// and/or other header values.
 type Handler struct {
 	Request  *HeaderOps     `json:"request,omitempty"`
 	Response *RespHeaderOps `json:"response,omitempty"`
@@ -99,12 +110,18 @@ func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhtt
 	return next.ServeHTTP(w, r)
 }
 
-// HeaderOps defines some operations to
-// perform on HTTP headers.
+// HeaderOps defines manipulations for HTTP headers.
 type HeaderOps struct {
-	Add     http.Header              `json:"add,omitempty"`
-	Set     http.Header              `json:"set,omitempty"`
-	Delete  []string                 `json:"delete,omitempty"`
+	// Adds HTTP headers; does not replace any existing header fields.
+	Add http.Header `json:"add,omitempty"`
+
+	// Sets HTTP headers; replaces existing header fields.
+	Set http.Header `json:"set,omitempty"`
+
+	// Names of HTTP header fields to delete.
+	Delete []string `json:"delete,omitempty"`
+
+	// Performs substring replacements of HTTP headers in-situ.
 	Replace map[string][]Replacement `json:"replace,omitempty"`
 }
 
@@ -135,22 +152,33 @@ func (ops HeaderOps) validate() error {
 }
 
 // Replacement describes a string replacement,
-// either a simple and fast sugbstring search
+// either a simple and fast substring search
 // or a slower but more powerful regex search.
 type Replacement struct {
-	Search       string `json:"search,omitempty"`
+	// The substring to search for.
+	Search string `json:"search,omitempty"`
+
+	// The regular expression to search with.
 	SearchRegexp string `json:"search_regexp,omitempty"`
-	Replace      string `json:"replace,omitempty"`
+
+	// The string with which to replace matches.
+	Replace string `json:"replace,omitempty"`
 
 	re *regexp.Regexp
 }
 
-// RespHeaderOps is like HeaderOps, but
-// optionally deferred until response time.
+// RespHeaderOps defines manipulations for response headers.
 type RespHeaderOps struct {
 	*HeaderOps
-	Require  *caddyhttp.ResponseMatcher `json:"require,omitempty"`
-	Deferred bool                       `json:"deferred,omitempty"`
+
+	// If set, header operations will be deferred until
+	// they are written out and only performed if the
+	// response matches these criteria.
+	Require *caddyhttp.ResponseMatcher `json:"require,omitempty"`
+
+	// If true, header operations will be deferred until
+	// they are written out. Superceded if Require is set.
+	Deferred bool `json:"deferred,omitempty"`
 }
 
 // ApplyTo applies ops to hdr using repl.
-- 
cgit v1.2.3