From 7a783efd5da42ce9a3a21a547998eb6bcb48b816 Mon Sep 17 00:00:00 2001
From: James Hillyerd <james@hillyerd.com>
Date: Sat, 7 Apr 2018 15:53:44 -0700
Subject: [PATCH] config: Document MailboxNaming for #33

---
 doc/config.md        | 29 +++++++++++++++++++++++++++--
 pkg/config/config.go |  2 +-
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/doc/config.md b/doc/config.md
index d0a64fb..1342cb7 100644
--- a/doc/config.md
+++ b/doc/config.md
@@ -9,6 +9,7 @@ variables it supports:
 
     KEY                                 DEFAULT             DESCRIPTION
     INBUCKET_LOGLEVEL                   info                debug, info, warn, or error
+    INBUCKET_MAILBOXNAMING              local               Use local or full addressing
     INBUCKET_SMTP_ADDR                  0.0.0.0:2500        SMTP server IP4 host:port
     INBUCKET_SMTP_DOMAIN                inbucket            HELO domain
     INBUCKET_SMTP_MAXRECIPIENTS         200                 Maximum RCPT TO per message
@@ -53,6 +54,30 @@ off with `warn` or `error`.
 - Default: `info`
 - Values: one of `debug`, `info`, `warn`, or `error`
 
+### Mailbox Naming
+
+`INBUCKET_MAILBOXNAMING`
+
+The mailbox naming setting determines the name of a mailbox for an incoming
+message, and thus where it must be retrieved from later.
+
+#### `local` ensures the domain is removed, such that:
+
+- `james@inbucket.org` is stored in `james`
+- `james+spam@inbucket.org` is stored in `james`
+
+#### `full` retains the domain as part of the name, such that:
+
+- `james@inbucket.org` is stored in `james@inbucket.org`
+- `james+spam@inbucket.org` is stored in `james@inbucket.org`
+
+Prior to the addition of the mailbox naming setting, Inbucket always operated in
+local mode.  Regardless of this setting, the `+` wildcard/extension is not
+incorporated into the mailbox name.
+
+- Default: `local`
+- Values: one of `local` or `full`
+
 
 ## SMTP
 
@@ -350,12 +375,12 @@ separated list of key:value pairs.
 - Default: None
 - Examples: `maxkb=10240` or `path=/tmp/inbucket`
 
-#### file parameters
+#### `file` type parameters
 
 - `path`: Operating system specific path to the directory where mail should be
   stored.
 
-#### memory parameters
+#### `memory` type parameters
 
 - `maxkb`: Maximum size of the mail store in kilobytes.  The oldest messages in
   the store will be deleted to enforce the limit.  In-memory storage has some
diff --git a/pkg/config/config.go b/pkg/config/config.go
index ecd5971..3071907 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -56,7 +56,7 @@ func (n *mbNaming) Decode(v string) error {
 // Root contains global configuration, and structs with for specific sub-systems.
 type Root struct {
 	LogLevel      string   `required:"true" default:"info" desc:"debug, info, warn, or error"`
-	MailboxNaming mbNaming `required:"true" default:"local" desc:"local or full"`
+	MailboxNaming mbNaming `required:"true" default:"local" desc:"Use local or full addressing"`
 	SMTP          SMTP
 	POP3          POP3
 	Web           Web