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/caddyauth/basicauth.go | 19 +++++++++++++++----
 modules/caddyhttp/caddyauth/caddyauth.go |  3 +++
 modules/caddyhttp/caddyauth/hashes.go    | 14 +++++++++++---
 3 files changed, 29 insertions(+), 7 deletions(-)

(limited to 'modules/caddyhttp/caddyauth')

diff --git a/modules/caddyhttp/caddyauth/basicauth.go b/modules/caddyhttp/caddyauth/basicauth.go
index 8aa44f1..74aa407 100644
--- a/modules/caddyhttp/caddyauth/basicauth.go
+++ b/modules/caddyhttp/caddyauth/basicauth.go
@@ -28,9 +28,14 @@ func init() {
 
 // HTTPBasicAuth facilitates HTTP basic authentication.
 type HTTPBasicAuth struct {
-	HashRaw     json.RawMessage `json:"hash,omitempty" caddy:"namespace=http.authentication.hashes inline_key=algorithm"`
-	AccountList []Account       `json:"accounts,omitempty"`
-	Realm       string          `json:"realm,omitempty"`
+	// The algorithm with which the passwords are hashed. Default: bcrypt
+	HashRaw json.RawMessage `json:"hash,omitempty" caddy:"namespace=http.authentication.hashes inline_key=algorithm"`
+
+	// The list of accounts to authenticate.
+	AccountList []Account `json:"accounts,omitempty"`
+
+	// The name of the realm. Default: restricted
+	Realm string `json:"realm,omitempty"`
 
 	Accounts map[string]Account `json:"-"`
 	Hash     Comparer           `json:"-"`
@@ -125,9 +130,15 @@ type Comparer interface {
 
 // Account contains a username, password, and salt (if applicable).
 type Account struct {
+	// A user's username.
 	Username string `json:"username"`
+
+	// The user's hashed password, base64-encoded.
 	Password []byte `json:"password"`
-	Salt     []byte `json:"salt,omitempty"` // for algorithms where external salt is needed
+
+	// The user's password salt, base64-encoded; for
+	// algorithms where external salt is needed.
+	Salt []byte `json:"salt,omitempty"`
 }
 
 // Interface guards
diff --git a/modules/caddyhttp/caddyauth/caddyauth.go b/modules/caddyhttp/caddyauth/caddyauth.go
index c814caf..aefeec5 100644
--- a/modules/caddyhttp/caddyauth/caddyauth.go
+++ b/modules/caddyhttp/caddyauth/caddyauth.go
@@ -28,7 +28,10 @@ func init() {
 }
 
 // Authentication is a middleware which provides user authentication.
+// Rejects requests with HTTP 401 if the request is not authenticated.
 type Authentication struct {
+	// A set of authentication providers. If none are specified,
+	// all requests will always be unauthenticated.
 	ProvidersRaw caddy.ModuleMap `json:"providers,omitempty" caddy:"namespace=http.authentication.providers"`
 
 	Providers map[string]Authenticator `json:"-"`
diff --git a/modules/caddyhttp/caddyauth/hashes.go b/modules/caddyhttp/caddyauth/hashes.go
index 3ca5116..5a3173e 100644
--- a/modules/caddyhttp/caddyauth/hashes.go
+++ b/modules/caddyhttp/caddyauth/hashes.go
@@ -52,9 +52,17 @@ func (BcryptHash) Compare(hashed, plaintext, _ []byte) (bool, error) {
 
 // ScryptHash implements the scrypt KDF as a hash.
 type ScryptHash struct {
-	N         int `json:"N,omitempty"`
-	R         int `json:"r,omitempty"`
-	P         int `json:"p,omitempty"`
+	// scrypt's N parameter. If unset or 0, a safe default is used.
+	N int `json:"N,omitempty"`
+
+	// scrypt's r parameter. If unset or 0, a safe default is used.
+	R int `json:"r,omitempty"`
+
+	// scrypt's p parameter. If unset or 0, a safe default is used.
+	P int `json:"p,omitempty"`
+
+	// scrypt's key length parameter (in bytes). If unset or 0, a
+	// safe default is used.
 	KeyLength int `json:"key_length,omitempty"`
 }
 
-- 
cgit v1.2.3