From a1b1279b6c9c7e36a228d8677ce7db9210eb972b Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@curecanti.org>
Date: Tue, 16 Dec 2008 21:14:12 -0700
Subject: [PATCH] Improve documentation.

---
 imp/config/servers.php.dist | 148 +++++++++++++++++++++++---------------------
 1 file changed, 78 insertions(+), 70 deletions(-)

diff --git a/imp/config/servers.php.dist b/imp/config/servers.php.dist
index 71bcc7497..60608e11e 100644
--- a/imp/config/servers.php.dist
+++ b/imp/config/servers.php.dist
@@ -1,16 +1,17 @@
 <?php
 /**
- * This file is where you specify what mail servers people using your
- * installation of IMP can log in to.
+ * This file specifies which mail servers people using your installation of
+ * IMP can login to.
  *
  * Properties that can be set for each server:
  *
- * name: This is the plaintext, English name that you want displayed if using
- *       the drop down server list.
+ * name: (string) This is the plaintext, English name that you want displayed
+ *       if using the drop down server list.
  *
- * hostspec: The hostname/IP address of the mail server to connect to.
+ * hostspec: (string) The hostname/IP address of the mail server to connect to.
  *
- * hordeauth: true - IMP will attempt to use the user's existing credentials
+ * hordeauth: (mixed) One of the following values:
+ *            true - IMP will attempt to use the user's existing credentials
  *                   (the username/password they used to log in to Horde) to
  *                   login to this source.
  *            false - Everything after and including the first @ in the
@@ -18,81 +19,88 @@
  *                    authentication. (DEFAULT)
  *            'full' - The username will be used unmodified.
  *
- * protocol: Either 'pop' or 'imap' (DEFAULT).
+ * protocol: (string) Either 'pop' or 'imap' (DEFAULT).
  *
  *           If using 'pop' you will connect to a POP3 mail server and all
  *           folder options will be automatically turned off (POP3 does
  *           not support folders).  If you want folders (and for much
  *           improved performance) it is HIGHLY RECOMMENDED that IMAP should
- *           be used instead.  The PHP imap module must be build into PHP in
+ *           be used instead.  The PHP imap module must be built into PHP in
  *           order to use a POP3 server.
  *
- * secure: 'ssl' - Use SSL to connect to the server.
+ * secure: (mixed) One of the following values:
+ *         'ssl' - Use SSL to connect to the server.
  *         'tls' - Use TLS to connect to the server.
  *         false - Do not use any encryption (DEFAULT).
  *
- *           The 'ssl' and 'tls' options will only work if you've compiled PHP
- *           with SSL support and the mail server supports SSL.
- *
- * port: The port that the mail service/protocol you selected runs on.
- *       Default values:
- *         pop (unsecure or w/TLS):    110
- *         pop (w/SSL):                995
- *         imap (unsecure or w/TLS):   143
- *         imap (w/SSL):               993
- *
- * maildomain: What to put after the @ when sending mail. i.e. if you want
- *             all mail to look like 'From: user@example.com' set
- *             maildomain to 'example.com'. It is generally useful when
- *             the sending host is different from the mail receiving host. This
- *             will also be used to complete unqualified addresses when
- *             composing mail.
- *
- * smtphost: If specified, and $conf['mailer']['type'] is set to 'smtp',
- *           IMP will use this host for outbound SMTP connections.  This
- *           value overrides any existing $conf['mailer']['params']['host']
- *           value at runtime.
- *
- * smtpport: If specified, and $conf['mailer']['type'] is set to 'smtp',
- *           IMP will use this port for outbound SMTP connections.  This value
- *           overrides any existing $conf['mailer']['params']['port'] value at
- *           runtime.
- *
- * realm: ONLY USE REALM IF YOU ARE USING IMP FOR HORDE AUTHENTICATION,
- *        AND YOU HAVE MULTIPLE SERVERS AND USERNAMES OVERLAP BETWEEN
- *        THOSE SERVERS. If you only have one server, or have multiple
- *        servers with no username clashes, or have full user@example.com
- *        usernames, you DO NOT need a realm setting. If you set one, an
- *        '@' symbol plus the realm will be appended to the username that
- *        users log in to IMP with to create the username that Horde treats
- *        the user as. So with a realm of 'example.com', the username
- *        'jane' would be treated by Horde (NOT your IMAP/POP server) as
- *        'jane@example.com', and the username 'jane@example.com' would be
- *        treated as 'jane@example.com@example.com' - an occasion where you
- *        probably don't need a realm setting.
- *
- * preferred: Only useful if you want to use the same servers.php file
+ *         The 'ssl' and 'tls' options will only work if you've compiled PHP
+ *         with SSL support and the mail server supports secure connections.
+ *
+ * port: (integer) The port that the mail service/protocol you selected runs
+ *       on. Default values:
+ *         pop (unsecure or w/TLS):   110
+ *         pop (w/SSL):               995
+ *         imap (unsecure or w/TLS):  143
+ *         imap (w/SSL):              993
+ *
+ * maildomain: (string) What to put after the @ when sending mail. This setting
+ *             is generally useful when the sending host is different from the
+ *             mail receiving host. This setting will also be used to complete
+ *             unqualified addresses when composing mail.
+ *             E.g. If you want all mail to look like 'From: user@example.com',
+ *             set maildomain to 'example.com'.
+ *
+ * smtphost: (string) If specified, and $conf['mailer']['type'] is set to
+ *           'smtp', IMP will use this host for outbound SMTP connections.
+ *           This value overrides any existing
+ *           $conf['mailer']['params']['host'] value at runtime.
+ *
+ * smtpport: (integer) If specified, and $conf['mailer']['type'] is set to
+ *           'smtp', IMP will use this port for outbound SMTP connections.
+ *           This value overrides any existing
+ *           $conf['mailer']['params']['port'] value at runtime.
+ *
+ * realm: (string) ONLY USE REALM IF YOU ARE USING IMP FOR HORDE
+ *        AUTHENTICATION AND YOU HAVE MULTIPLE SERVERS AND USERNAMES OVERLAP
+ *        BETWEEN THOSE SERVERS.
+ *
+ *        If you only have one server, or have multiple servers with no
+ *        username clashes, or have full user@example.com usernames, you DO
+ *        NOT need a realm setting. If you set one, a '@' symbol plus the
+ *        realm value will be appended to the username that users login to
+ *        IMP with to create the username that Horde treats the user as.
+ *
+ *        Example: with a realm of 'example.com', the username 'jane' would
+ *        be treated by Horde (NOT your IMAP/POP server) as 'jane@example.com',
+ *        and the username 'jane@example.com' would be treated as
+ *        'jane@example.com@example.com' - an occasion where you probably
+ *        don't need a realm setting.
+ *
+ * preferred: (string) Only useful if you want to use the same servers.php file
  *            for different machines: if the hostname of the IMP machine is
  *            identical to one of those in the preferred list, then the
  *            corresponding option in the select box will include SELECTED
  *            (i.e. it is selected per default). Otherwise the first entry
  *            in the list is selected.
  *
- * quota: Use this if you want to display a users quota status on various
- *        IMP pages. Set 'driver' equal to the mailserver and 'params'
+ * quota: (array) Use this if you want to display a user's quota status on
+ *        various IMP pages. Set 'driver' equal to the mailserver and 'params'
  *        equal to any extra parameters needed by the driver (see the
  *        comments located at the top of imp/lib/Quota/[quotadriver].php
  *        for the parameters needed for each driver). Set
  *        'hide_when_unlimited' to true if you want to hide quota output
  *        when the server reports an unlimited quota.
  *
+ *        Set this to an empty value to disable quota (the DEFAULT).
+ *
  *        The optional 'format' parameter is supported by all drivers and
  *        specifies the formats of the quota messages in the user
  *        interface. The parameter must be specified as a hash with the four
  *        possible elements 'long', 'short', 'nolimit_long', and
  *        'nolimit_short' with according versions of the quota message. The
  *        strings will be passed through sprintf().
- *        These are the built-in default values, though they might look
+ *
+ *        These are the built-in default values, though they may appear
  *        differently in some translations:
  *          'long'          -- Quota status: %.2f MB / %.2f MB  (%.2f%%)
  *          'short'         -- %.0f%% of %.0f MB
@@ -100,8 +108,6 @@
  *          'nolimit_short' -- %.0f MB
  *
  *        Currently available drivers:
- *          false        --  Disable quota checking (DEFAULT).
- *
  *          'command'    --  Use the UNIX quota command to handle quotas.
  *          'hook'       --  Use the _imp_hook_quota function to handle quotas.
  *          'imap'       --  Use the IMAP QUOTA extension to handle quotas.
@@ -116,19 +122,21 @@
  *          'mercury32'  --  Use Mercury/32 servers to handle quotas.
  *          'sql'        --  Use arbitrary SQL queries to handle quotas.
  *
- * admin: Use this if you want to enable mailbox management for administrators
- *        via Horde's user administration interface.  The mailbox management
- *        gets enabled if you let IMP handle the Horde authentication with the
- *        'application' authentication driver.  Your IMAP server needs to
- *        support mailbox management via IMAP commands.
+ * admin: (array) Use this if you want to enable mailbox management for
+ *        administrators via Horde's user administration interface.  The
+ *        mailbox management gets enabled if you let IMP handle the Horde
+ *        authentication with the 'application' authentication driver.  Your
+ *        IMAP server needs to support mailbox management via IMAP commands.
  *        Do not define this value if you do not want mailbox management.
  *
- * acl: Set to true if you want to use Access Control Lists (folder sharing).
- *      Not all IMAP servers currently support this feature.
+ * acl: (boolean) Set to true if you want to use Access Control Lists (folder
+ *      sharing). Set to false to disable (DEFAULT). Not all IMAP servers
+ *      support this feature.
+ *
+ * cache: (mixed) Enables caching for the the server. This requires
+ *        configuration of a Horde_Cache driver in Horde. Will be disabled on
+ *        any empty value and enabled on any non-false value.
  *
- * cache: Enables caching for the the server. This requires configuration
- *        of a Horde_Cache driver in Horde.  Will be disabled on a false
- *        value and enabled on any non-false value.
  *        The following optional configuration items are available:
  *        'compress' - (string) Should the contents of the cache files be
  *                     compressed before they are stored? This results in
@@ -156,18 +164,18 @@
  * *** you are doing! FOR MOST PEOPLE, AUTO-DETECTION OF THESE PARAMETERS  ***
  * *** (the default if the parameters are not set) SHOULD BE USED!         ***
  *
+ * namespace: (array) The list of namespaces that exist on the server. The
+ *            entries must be encoded in the UTF7-IMAP charset. Example:
  *
- * namespace: The list of namespaces that exist on the server.  This entry
- *            must be an array and the namespaces must be encoded in the
- *            UTF7-IMAP charset. Example:
  *              'namespace' => array('#shared/', '#news/', '#public/')
- *            This paramater should only be used if you want to allow access
+ *
+ *            This parameter should only be used if you want to allow access
  *            to namespaces that may not be publicly advertised by the IMAP
  *            server (see RFC 2342 [3]). These additional namespaces will be
  *            added to the list of available namespaces returned by the
  *            server.  This entry is only pertinent for IMAP servers.
  *
- * timeout: Set the server timeout (in seconds).
+ * timeout: (integer) Set the server timeout (in seconds).
  */
 
 /* Any entries whose key value ('foo' in $servers['foo']) begin with '_'
-- 
2.11.0