v2: Module documentation; refactor LoadModule(); new caddy struct tags (#2924)

This commit goes a long way toward making automated documentation of
Caddy config and Caddy modules possible. It's a broad, sweeping change,
but mostly internal. It allows us to automatically generate docs for all
Caddy modules (including future third-party ones) and make them viewable
on a web page; it also doubles as godoc comments.

As such, this commit makes significant progress in migrating the docs
from our temporary wiki page toward our new website which is still under
construction.

With this change, all host modules will use ctx.LoadModule() and pass in
both the struct pointer and the field name as a string. This allows the
reflect package to read the struct tag from that field so that it can
get the necessary information like the module namespace and the inline
key.

This has the nice side-effect of unifying the code and documentation. It
also simplifies module loading, and handles several variations on field
types for raw module fields (i.e. variations on json.RawMessage, such as
arrays and maps).

I also renamed ModuleInfo.Name -> ModuleInfo.ID, to make it clear that
the ID is the "full name" which includes both the module namespace and
the name. This clarity is helpful when describing module hierarchy.

As of this change, Caddy modules are no longer an experimental design.
I think the architecture is good enough to go forward.

1 files changed, 26 insertions, 9 deletions

diff --git a/modules/caddyhttp/caddyhttp.go b/modules/caddyhttp/caddyhttp.go
index 064a963..756a6c3 100644
--- a/modules/caddyhttp/caddyhttp.go
+++ b/modules/caddyhttp/caddyhttp.go
@@ -44,12 +44,27 @@ func init() {
 	}
 }
 
-// App is the HTTP app for Caddy.
+// App is a robust, flexible HTTP server for Caddy.
 type App struct {
-	HTTPPort    int                `json:"http_port,omitempty"`
-	HTTPSPort   int                `json:"https_port,omitempty"`
-	GracePeriod caddy.Duration     `json:"grace_period,omitempty"`
-	Servers     map[string]*Server `json:"servers,omitempty"`
+	// HTTPPort specifies the port to use for HTTP (as opposed to HTTPS),
+	// which is used when setting up HTTP->HTTPS redirects or ACME HTTP
+	// challenge solvers. Default: 80.
+	HTTPPort int `json:"http_port,omitempty"`
+
+	// HTTPSPort specifies the port to use for HTTPS, which is used when
+	// solving the ACME TLS-ALPN challenges, or whenever HTTPS is needed
+	// but no specific port number is given. Default: 443.
+	HTTPSPort int `json:"https_port,omitempty"`
+
+	// GracePeriod is how long to wait for active connections when shutting
+	// down the server. Once the grace period is over, connections will
+	// be forcefully closed.
+	GracePeriod caddy.Duration `json:"grace_period,omitempty"`
+
+	// Servers is the list of servers, keyed by arbitrary names chosen
+	// at your discretion for your own convenience; the keys do not
+	// affect functionality.
+	Servers map[string]*Server `json:"servers,omitempty"`
 
 	servers     []*http.Server
 	h3servers   []*http3.Server
@@ -62,8 +77,8 @@ type App struct {
 // CaddyModule returns the Caddy module information.
 func (App) CaddyModule() caddy.ModuleInfo {
 	return caddy.ModuleInfo{
-		Name: "http",
-		New:  func() caddy.Module { return new(App) },
+		ID:  "http",
+		New: func() caddy.Module { return new(App) },
 	}
 }
 
@@ -561,8 +576,10 @@ var emptyHandler HandlerFunc = func(http.ResponseWriter, *http.Request) error {
 
 // WeakString is a type that unmarshals any JSON value
 // as a string literal, with the following exceptions:
-// 1) actual string values are decoded as strings; and
-// 2) null is decoded as empty string;
+//
+// 1. actual string values are decoded as strings; and
+// 2. null is decoded as empty string;
+//
 // and provides methods for getting the value as various
 // primitive types. However, using this type removes any
 // type safety as far as deserializing JSON is concerned.