Pretty large coding style cleanup, in source doc

cleanup, and allow protocol mods to depend on each
other

1 files changed, 66 insertions, 12 deletions

diff --git a/include/access.h b/include/access.h
index 558dbeb5c..918dd7be6 100644
--- a/include/access.h
+++ b/include/access.h
@@ -8,7 +8,6 @@
  * Based on the original code of Epona by Lara.
  * Based on the original code of Services by Andy Church.
  *
- *
  */
 
 #ifndef ACCESS_H
@@ -25,19 +24,25 @@ enum
 	ACCESS_FOUNDER = 10001
 };
 
+/* A privilege, probably configured using a privilege{} block. Most
+ * commands require specific privileges to be executed. The AccessProvider
+ * backing each ChanAccess determines whether that ChanAccess has a given
+ * privilege.
+ */
 struct CoreExport Privilege
 {
 	Anope::string name;
 	Anope::string desc;
+	/* Rank relative to other privileges */
 	int rank;
 
-	Privilege(const Anope::string &n, const Anope::string &d, int r);
+	Privilege(const Anope::string &name, const Anope::string &desc, int rank);
 	bool operator==(const Privilege &other) const;
 };
 
 class CoreExport PrivilegeManager
 {
-	static std::vector<Privilege> privs;
+	static std::vector<Privilege> Privileges;
  public:
 	static void AddPrivilege(Privilege p);
 	static void RemovePrivilege(Privilege &p);
@@ -46,25 +51,34 @@ class CoreExport PrivilegeManager
 	static void ClearPrivileges();
 };
 
-
+/* A provider of access. Only used for creating ChanAccesses, as
+ * they contain pure virtual functions.
+ */
 class CoreExport AccessProvider : public Service
 {
  public:
-	AccessProvider(Module *o, const Anope::string &n);
+	AccessProvider(Module *owner, const Anope::string &name);
 	virtual ~AccessProvider();
+
+	/** Creates a new ChanAccess entry using this provider.
+	 * @return The new entry
+	 */
 	virtual ChanAccess *Create() = 0;
 
  private:
-	static std::list<AccessProvider *> providers;
+	static std::list<AccessProvider *> Providers;
  public:
 	static const std::list<AccessProvider *>& GetProviders();
 };
 
+/* Represents one entry of an access list on a channel. */
 class CoreExport ChanAccess : public Serializable
 {
  public:
+ 	/* The provider that created this access entry */
 	AccessProvider *provider;
-	serialize_obj<ChannelInfo> ci;
+	/* Channel this access entry is on */
+	Serialize::Reference<ChannelInfo> ci;
 	Anope::string mask;
 	Anope::string creator;
 	time_t last_seen;
@@ -73,29 +87,69 @@ class CoreExport ChanAccess : public Serializable
 	ChanAccess(AccessProvider *p);
 	virtual ~ChanAccess();
 
-	Serialize::Data serialize() const anope_override;
-	static Serializable* unserialize(Serializable *obj, Serialize::Data &);
+	Serialize::Data Serialize() const anope_override;
+	static Serializable* Unserialize(Serializable *obj, Serialize::Data &);
 
+	/** Check if this access entry matches the given user or account
+	 * @param u The user
+	 * @param nc The account
+	 */
 	virtual bool Matches(const User *u, const NickCore *nc) const;
+
+	/** Check if this access entry has the given privilege.
+	 * @param name The privilege name
+	 */
 	virtual bool HasPriv(const Anope::string &name) const = 0;
-	virtual Anope::string Serialize() const = 0;
-	virtual void Unserialize(const Anope::string &data) = 0;
 
+	/** Serialize the access given by this access entry into a human
+	 * readable form. chanserv/access will return a number, chanserv/xop
+	 * will be AOP, SOP, etc.
+	 */
+	virtual Anope::string AccessSerialize() const = 0;
+
+	/** Unserialize this access entry from the given data. This data
+	 * will be fetched from AccessSerialize.
+	 */
+	virtual void AccessUnserialize(const Anope::string &data) = 0;
+
+	/* Comparison operators to other Access entries */
 	bool operator>(const ChanAccess &other) const;
 	bool operator<(const ChanAccess &other) const;
 	bool operator>=(const ChanAccess &other) const;
 	bool operator<=(const ChanAccess &other) const;
 };
 
+/* A group of access entries. This is used commonly, for example with ChannelInfo::AccessFor,
+ * to show what access a user has on a channel because users can match multiple access entries.
+ */
 class CoreExport AccessGroup : public std::vector<ChanAccess *>
 {
  public:
+ 	/* Channel these access entries are on */
  	const ChannelInfo *ci;
+	/* Account these entries affect, if any */
 	const NickCore *nc;
-	bool SuperAdmin, Founder;
+	/* super_admin always gets all privs. founder is a special case where ci->founder == nc */
+	bool super_admin, founder;
+
 	AccessGroup();
+
+	/** Check if this access group has a certain privilege. Eg, it
+	 * will check every ChanAccess entry of this group for any that
+	 * has the given privilege.
+	 * @param priv The privilege
+	 * @return true if any entry has the given privilege
+	 */
 	bool HasPriv(const Anope::string &priv) const;
+
+	/** Get the "highest" access entry from this group of entries.
+	 * The highest entry is determined by the entry that has the privilege
+	 * with the highest rank (see Privilege::rank).
+	 * @return The "highest" entry
+	 */
 	const ChanAccess *Highest() const;
+
+	/* Comparison operators to other AccessGroups */
 	bool operator>(const AccessGroup &other) const;
 	bool operator<(const AccessGroup &other) const;
 	bool operator>=(const AccessGroup &other) const;