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/fileserver/browse.go      |  1 +
 modules/caddyhttp/fileserver/matcher.go     | 22 ++++++++++++++--------
 modules/caddyhttp/fileserver/staticfiles.go | 29 +++++++++++++++++++++++------
 3 files changed, 38 insertions(+), 14 deletions(-)

(limited to 'modules/caddyhttp/fileserver')

diff --git a/modules/caddyhttp/fileserver/browse.go b/modules/caddyhttp/fileserver/browse.go
index 48f2cc7..aa8372e 100644
--- a/modules/caddyhttp/fileserver/browse.go
+++ b/modules/caddyhttp/fileserver/browse.go
@@ -29,6 +29,7 @@ import (
 
 // Browse configures directory browsing.
 type Browse struct {
+	// Use this template file instead of the default browse template.
 	TemplateFile string `json:"template_file,omitempty"`
 
 	template *template.Template
diff --git a/modules/caddyhttp/fileserver/matcher.go b/modules/caddyhttp/fileserver/matcher.go
index 13cb60a..5ca97f2 100644
--- a/modules/caddyhttp/fileserver/matcher.go
+++ b/modules/caddyhttp/fileserver/matcher.go
@@ -46,7 +46,13 @@ type MatchFile struct {
 	// placeholders.
 	TryFiles []string `json:"try_files,omitempty"`
 
-	// How to choose a file in TryFiles.
+	// How to choose a file in TryFiles. Can be:
+	//
+	// - first_exist
+	// - smallest_size
+	// - largest_size
+	// - most_recently_modified
+	//
 	// Default is first_exist.
 	TryPolicy string `json:"try_policy,omitempty"`
 }
@@ -64,7 +70,7 @@ func (MatchFile) CaddyModule() caddy.ModuleInfo {
 //     file {
 //         root <path>
 //         try_files <files...>
-//         try_policy first_exist|smallest_size|largest_size|most_recent_modified
+//         try_policy first_exist|smallest_size|largest_size|most_recently_modified
 //     }
 //
 func (m *MatchFile) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
@@ -107,7 +113,7 @@ func (m MatchFile) Validate() error {
 		tryPolicyFirstExist,
 		tryPolicyLargestSize,
 		tryPolicySmallestSize,
-		tryPolicyMostRecentMod:
+		tryPolicyMostRecentlyMod:
 	default:
 		return fmt.Errorf("unknown try policy %s", m.TryPolicy)
 	}
@@ -187,7 +193,7 @@ func (m MatchFile) selectFile(r *http.Request) (rel, abs string, matched bool) {
 		}
 		return smallestSuffix, smallestFilename, true
 
-	case tryPolicyMostRecentMod:
+	case tryPolicyMostRecentlyMod:
 		var recentDate time.Time
 		var recentFilename string
 		var recentSuffix string
@@ -238,10 +244,10 @@ func strictFileExists(file string) bool {
 }
 
 const (
-	tryPolicyFirstExist    = "first_exist"
-	tryPolicyLargestSize   = "largest_size"
-	tryPolicySmallestSize  = "smallest_size"
-	tryPolicyMostRecentMod = "most_recent_modified"
+	tryPolicyFirstExist      = "first_exist"
+	tryPolicyLargestSize     = "largest_size"
+	tryPolicySmallestSize    = "smallest_size"
+	tryPolicyMostRecentlyMod = "most_recently_modified"
 )
 
 // Interface guards
diff --git a/modules/caddyhttp/fileserver/staticfiles.go b/modules/caddyhttp/fileserver/staticfiles.go
index a9e6e1c..f2722ba 100644
--- a/modules/caddyhttp/fileserver/staticfiles.go
+++ b/modules/caddyhttp/fileserver/staticfiles.go
@@ -42,12 +42,29 @@ func init() {
 
 // FileServer implements a static file server responder for Caddy.
 type FileServer struct {
-	Root          string   `json:"root,omitempty"` // default is current directory
-	Hide          []string `json:"hide,omitempty"`
-	IndexNames    []string `json:"index_names,omitempty"`
-	Browse        *Browse  `json:"browse,omitempty"`
-	CanonicalURIs *bool    `json:"canonical_uris,omitempty"`
-	PassThru      bool     `json:"pass_thru,omitempty"` // if 404, call next handler instead
+	// The path to the root of the site. Default is `{http.vars.root}` if set,
+	// or current working directory otherwise.
+	Root string `json:"root,omitempty"`
+
+	// A list of files or folders to hide; the file server will pretend as if
+	// they don't exist. Accepts globular patterns like "*.hidden" or "/foo/*/bar".
+	Hide []string `json:"hide,omitempty"`
+
+	// The names of files to try as index files if a folder is requested.
+	IndexNames []string `json:"index_names,omitempty"`
+
+	// Enables file listings if a directory was requested and no index
+	// file is present.
+	Browse *Browse `json:"browse,omitempty"`
+
+	// Use redirects to enforce trailing slashes for directories, or to
+	// remove trailing slash from URIs for files. Default is true.
+	CanonicalURIs *bool `json:"canonical_uris,omitempty"`
+
+	// If pass-thru mode is enabled and a requested file is not found,
+	// it will invoke the next handler in the chain instead of returning
+	// a 404 error. By default, this is false (disabled).
+	PassThru bool `json:"pass_thru,omitempty"`
 }
 
 // CaddyModule returns the Caddy module information.
-- 
cgit v1.2.3