Document a little more accurrately the privilege stuff and document why the access lists behave as they do

1 files changed, 22 insertions, 8 deletions

diff --git a/data/chanserv.example.conf b/data/chanserv.example.conf
index 7810c20e6..dba4466eb 100644
--- a/data/chanserv.example.conf
+++ b/data/chanserv.example.conf
@@ -173,18 +173,18 @@ module
  * ChanServ privilege configuration.
  *
  * ChanServ privileges are used to determine who has what access in channels. By default the core has its own
- * set of levels it uses for various ChanServ commands, which are defined below. Privilege ranks are used to
- * determine how powerful privileges are relative to each other, which is used by Anope to determine who has greater
- * access in a channel.
+ * set of privileges it uses for various commands, which are defined below. Privilege ranks are used to
+ * determine how powerful privileges are relative to other privileges, which is used by Anope to determine
+ * who has greater access in a channel.
  *
- * If you loaded cs_access, you may define a level for the privilege, which is used by chanserv/access and chanserv/levels.
+ * If you load cs_access, you may define a level for the privilege, which is used by chanserv/access and chanserv/levels.
  * The levels defined will be used as the default levels for newly registered channels.
  * The level "founder" is a special level which means anyone with the privilege FOUNDER on the channel
  * has that permission. Additionally, the level "disabled" means that no one can use the privilege, including founders.
  *
- * If you loaded cs_flags, you may define a flag associated with that privilege for use in chanserv/flags.
+ * If you load cs_flags, you may define a flag associated with that privilege for use in chanserv/flags.
  *
- * If you loaded cs_xop, you may define a xop command to associate the privilege with.
+ * If you load cs_xop, you may define a XOP command to associate the privilege with.
  *
  * The name of privileges are uesd to associate them with channel modes. If you are using an IRCd that allows you to define additional
  * channel status modes, such as InspIRCd, you can associate privileges (and thus access levels, flags, xop) with the mode by naming
@@ -829,7 +829,12 @@ command { service = "ChanServ"; name = "HELP"; command = "generic/help"; }
  * Provides commands chanserv/access and chanserv/levels.
  * Provides the access system "levels".
  *
- * Used for giving users access in channels.
+ * Used for giving users access in channels using a levels system. Allows allows redefining which privileges
+ * are representated by given level on a per channel basis.
+ *
+ * The "LIST" subcommand of chanserv/access will show every access entry on the channel, including access
+ * entries not added by cs_access. The "level" of these entries will be the representation of the access
+ * entry by the other access system, which could be an XOP command name, or a set of flags.
  */
 module { name = "cs_access" }
 command { service = "ChanServ"; name = "ACCESS"; command = "chanserv/access"; group = "chanserv/access"; }
@@ -921,6 +926,10 @@ command { service = "ChanServ"; name = "ENTRYMSG"; command = "chanserv/entrymsg"
  * Provides the access system "flags".
  *
  * Used for giving users access in channels.
+ *
+ * The "LIST" subcommand of chanserv/flags will show every access entry on the channel, including access
+ * entries not added by cs_flags. The "Flags" of these entries will be the flags representation of the
+ * privilege set granted by the access entry. 
  */
 module { name = "cs_flags" }
 command { service = "ChanServ"; name = "FLAGS"; command = "chanserv/flags"; group = "chanserv/access"; }
@@ -1032,7 +1041,9 @@ command { service = "ChanServ"; name = "LOG"; command = "chanserv/log"; group =
  *
  * Provides the command chanserv/mode and chanserv/modes.
  *
- * Used for changing mode locks and changing modes.
+ * Used for changing mode locks and changing modes. Multiple commands may be mapped to chanserv/modes, the
+ * configuration directive 'set' and 'unset' are used to tell chanserv/modes which modes should be set or
+ * unset when the command is executed.
  */
 module
 {
@@ -1255,6 +1266,9 @@ command { service = "ChanServ"; name = "UP"; command = "chanserv/up"; group = "c
  * privileges given by each is determined by the privilege:xop settings above. These commands should
  * be ordered from highest to lowest, as each command inherits the privileges of the commands below
  * it.
+ *
+ * The "LIST" subcommand of chanserv/xop will show only XOP access entries of the given XOP type. You
+ * can not view the entire access list at once, and instead should use another access system to do that.
  */
 module { name = "cs_xop" }
 command { service = "ChanServ"; name = "QOP"; command = "chanserv/xop"; group = "chanserv/access"; }