Comment documentation for all the new shizzle

git-svn-id: http://svn.inspircd.org/repository/trunk/inspircd@8467 e03df62e-2008-0410-955e-edbf42e46eb7

1 files changed, 152 insertions, 28 deletions

diff --git a/include/xline.h b/include/xline.h
index 32ae04d5a..74c58e05c 100644
--- a/include/xline.h
+++ b/include/xline.h
@@ -14,28 +14,30 @@
 #ifndef __XLINE_H
 #define __XLINE_H
 
-// include the common header files
-
 #include <string>
 #include <deque>
 #include <vector>
 #include "users.h"
 #include "channels.h"
 
-const int APPLY_GLINES		= 1;
-const int APPLY_KLINES		= 2;
-const int APPLY_QLINES		= 4;
-const int APPLY_ZLINES		= 8;
-const int APPLY_PERM_ONLY	= 16;
-const int APPLY_ALL		= APPLY_GLINES | APPLY_KLINES | APPLY_QLINES | APPLY_ZLINES;
-
 /** XLine is the base class for ban lines such as G lines and K lines.
+ * Modules may derive from this, and their xlines will automatically be
+ * handled as expected by any protocol modules (e.g. m_spanningtree will
+ * propogate them using AddLine). The process of translating a type+pattern
+ * to a known line type is done by means of an XLineFactory object (see
+ * below).
  */
 class CoreExport XLine : public classbase
 {
  protected:
 
+	/** Creator */
 	InspIRCd* ServerInstance;
+
+	/** Default 'apply' action. Quits the user.
+	 * @param u User to apply the line against
+	 * @param line The line typed, used for display purposes in the quit message
+	 */
 	void DefaultApply(User* u, const std::string &line);
 
  public:
@@ -45,6 +47,7 @@ class CoreExport XLine : public classbase
 	 * @param d The duration of the xline
 	 * @param src The sender of the xline
 	 * @param re The reason of the xline
+	 * @param t The line type, should be set by the derived class constructor
 	 */
 	XLine(InspIRCd* Instance, time_t s_time, long d, const char* src, const char* re, const std::string &t)
 		: ServerInstance(Instance), set_time(s_time), duration(d), type(t)
@@ -62,6 +65,9 @@ class CoreExport XLine : public classbase
 		free(source);
 	}
 
+	/** Change creation time of an xline. Updates expiry
+	 * to be after the creation time
+	 */
 	virtual void SetCreateTime(time_t created)
 	{
 		set_time = created;
@@ -69,19 +75,48 @@ class CoreExport XLine : public classbase
 	}
 
 	/** Returns true whether or not the given user is covered by this line.
+	 * @param u The user to match against. The mechanics of the match
+	 * are defined by the derived class.
+	 * @return True if there is a match.
 	 */
 	virtual bool Matches(User *u) = 0;
 
+	/** Returns true whether or not the given string is covered by this line.
+	 * @param str The string to match against. The details of what must be
+	 * in this string and the mechanics of the match are defined by the
+	 * derived class.
+	 * @return True if there is a match
+	 */
 	virtual bool Matches(const std::string &str) = 0;
 
+	/** Apply a line against a user. The mechanics of what occurs when
+	 * the line is applied are specific to the derived class.
+	 * @param u The user to apply against
+	 */
 	virtual void Apply(User* u);
 
+	/** Called when the line is unset either via expiry or
+	 * via explicit removal.
+	 */
 	virtual void Unset() { }
 
+	/** Called when the expiry message is to be displayed for the
+	 * line. Usually a line in the form 'expiring Xline blah, set by...'
+	 * see the DisplayExpiry methods of GLine, ELine etc.
+	 */
 	virtual void DisplayExpiry() = 0;
 
+	/** Returns the displayable form of the pattern for this xline,
+	 * e.g. '*@foo' or '*baz*'. This must always return the full pattern
+	 * in a form which can be used to construct an entire derived xline,
+	 * even if it is stored differently internally (e.g. GLine stores the
+	 * ident and host parts seperately but will still return ident@host
+	 * for its Displayable() method)
+	 */
 	virtual const char* Displayable() = 0;
 
+	/** Called when the xline has just been added.
+	 */
 	virtual void OnAdd() { }
 
 	/** The time the line was added.
@@ -100,11 +135,12 @@ class CoreExport XLine : public classbase
 	 */
 	char* reason;
 
-	/** Expiry time
+	/** Expiry time. Does not contain useful data if the duration is 0.
 	 */
 	time_t expiry;
 
-	/** Q, K, etc. Don't change this. Constructors set it.
+	/** "Q", "K", etc. Set only by derived classes constructor to the
+	 * type of line this is.
 	 */
 	const std::string type;
 };
@@ -114,6 +150,7 @@ class CoreExport XLine : public classbase
 class CoreExport KLine : public XLine
 {
   public:
+
 	/** Create a K-Line.
 	 * @param s_time The set time
 	 * @param d The duration of the xline
@@ -148,10 +185,10 @@ class CoreExport KLine : public XLine
 
 	virtual const char* Displayable();
 
-	/** Ident mask
+	/** Ident mask (ident part only)
 	 */
 	char* identmask;
-	/** Host mask
+	/** Host mask (host part only)
 	 */
 	char* hostmask;
 
@@ -197,10 +234,10 @@ class CoreExport GLine : public XLine
 
 	virtual const char* Displayable();
 
-	/** Ident mask
+	/** Ident mask (ident part only)
 	 */
 	char* identmask;
-	/** Host mask
+	/** Host mask (host part only)
 	 */
 	char* hostmask;
 
@@ -246,10 +283,10 @@ class CoreExport ELine : public XLine
 
 	virtual const char* Displayable();
 
-	/** Ident mask
+	/** Ident mask (ident part only)
 	 */
 	char* identmask;
-	/** Host mask
+	/** Host mask (host part only)
 	 */
 	char* hostmask;
 
@@ -290,7 +327,7 @@ class CoreExport ZLine : public XLine
 
 	virtual const char* Displayable();
 
-	/** IP mask
+	/** IP mask (no ident part)
 	 */
 	char* ipaddr;
 };
@@ -338,7 +375,13 @@ class CoreExport QLine : public XLine
  */
 typedef std::pair<std::string, std::string> IdentHostPair;
 
-
+/** XLineFactory is used to generate an XLine pointer, given just the 
+ * pattern, timing information and type of line to create. This is used
+ * for example in the spanningtree module which will call an XLineFactory
+ * to create a new XLine when it is inbound on a server link, so that it
+ * does not have to know the specifics of the internals of an XLine class
+ * and/or how to call its constructor.
+ */
 class CoreExport XLineFactory
 {
  protected:
@@ -348,12 +391,29 @@ class CoreExport XLineFactory
 
  public:
 
+	/** Create an XLine factory
+	 * @param Instance creator
+	 * @param t Type of XLine this factory generates
+	 */
 	XLineFactory(InspIRCd* Instance, const std::string &t) : ServerInstance(Instance), type(t) { }
 	
+	/** Return the type of XLine this factory generates
+	 * @return The type of XLine this factory generates
+	 */
 	virtual const std::string& GetType() { return type; }
 
+	/** Generate a specialized XLine*.
+	 * @param set_time Time this line was created
+	 * @param duration Duration of the line
+	 * @param source The sender of the line, nickname or server
+	 * @param reason The reason for the line
+	 * @param xline_specific_mask The mask string for the line, specific to the XLine type being created.
+	 * @return A specialized XLine class of the given type for this factory.
+	 */
 	virtual XLine* Generate(time_t set_time, long duration, const char* source, const char* reason, const char* xline_specific_mask) = 0;
 
+	/** Destructor
+	 */
 	virtual ~XLineFactory() { }
 };
 
@@ -368,13 +428,29 @@ class QLineFactory;
 class ZLineFactory;
 class KLineFactory;
 
+/** A map of xline factories
+ */
 typedef std::map<std::string, XLineFactory*> XLineFactMap;
+
+/** A map of XLines indexed by string
+ */
 typedef std::map<std::string, XLine *> XLineLookup;
+
+/** A map of XLineLookup maps indexed by string
+ */
 typedef std::map<std::string, XLineLookup > XLineContainer;
+
+/** An iterator in an XLineContainer
+ */
 typedef XLineContainer::iterator ContainerIter;
+
+/** An interator in an XLineLookup
+ */
 typedef XLineLookup::iterator LookupIter;
 
-/** XLineManager is a class used to manage glines, klines, elines, zlines and qlines.
+/** XLineManager is a class used to manage glines, klines, elines, zlines and qlines,
+ * or any other line created by a module. It also manages XLineFactory classes which
+ * can generate a specialized XLine for use by another module.
  */
 class CoreExport XLineManager
 {
@@ -387,14 +463,25 @@ class CoreExport XLineManager
 	 */
 	std::vector<XLine *> pending_lines;
 
+	/** Current xline factories
+	 */
 	XLineFactMap line_factory;
 
+	/** Core xline factories for G/E/K/Q/Z lines
+	 * (These generate GLine, ELine, KLine, QLine and ZLine
+	 * respectively)
+	 */
 	GLineFactory* GFact;
 	ELineFactory* EFact;
 	KLineFactory* KFact;
 	QLineFactory* QFact;
 	ZLineFactory* ZFact;
 
+	/** Container of all lines, this is a map of maps which
+	 * allows for fast lookup for add/remove of a line, and
+	 * the shortest possible timed O(n) for checking a user
+	 * against a line.
+	 */
 	XLineContainer lookup_lines;
 
  public:
@@ -404,6 +491,8 @@ class CoreExport XLineManager
 	 */
 	XLineManager(InspIRCd* Instance);
 
+	/** Destructor
+	 */
 	~XLineManager();
 
 	/** Split an ident and host into two seperate strings.
@@ -415,22 +504,27 @@ class CoreExport XLineManager
 	 */
 	void CheckELines();
 
-	/** Get all lines of a certain type to an XLineLookup (std::map<std::string, XLine*>)
+	/** Get all lines of a certain type to an XLineLookup (std::map<std::string, XLine*>).
+	 * NOTE: When this function runs any expired items are removed from the list before it
+	 * is returned to the caller.
+	 * @param The type to look up
+	 * @return A list of all XLines of the given type.
 	 */
 	XLineLookup* GetAll(const std::string &type);
 
-	/** Return all known types of line currently stored by the XLineManager
+	/** Return all known types of line currently stored by the XLineManager.
+	 * @return A vector containing all known line types currently stored in the main list.
 	 */
 	std::vector<std::string> GetAllTypes();
 
-	/** Add a new GLine
+	/** Add a new XLine
 	 * @param line The line to be added
 	 * @param user The user adding the line or NULL for the local server
 	 * @return True if the line was added successfully
 	 */
 	bool AddLine(XLine* line, User* user);
 
-	/** Delete a GLine
+	/** Delete an XLine
 	 * @param hostmask The xline-specific string identifying the line, e.g. "*@foo"
 	 * @param type The type of xline
 	 * @param user The user removing the line or NULL if its the local server
@@ -447,15 +541,19 @@ class CoreExport XLineManager
 	 * you do not know the full details of the item you wish to create, e.g. in a 
 	 * server protocol module like m_spanningtree, when you receive xlines from other
 	 * servers.
+	 * @param xlf XLineFactory pointer to register
 	 */
 	bool RegisterFactory(XLineFactory* xlf);
 
-	/** Unregisters an xline factory
+	/** Unregisters an xline factory.
+	 * You must do this when your module unloads.
+	 * @param xlf XLineFactory pointer to unregister
 	 */
 	bool UnregisterFactory(XLineFactory* xlf);
 
 	/** Get the XLineFactory for a specific type.
-	 * Returns NULL if there is no known handler for this xline type
+	 * Returns NULL if there is no known handler for this xline type.
+	 * @param type The type of XLine you require the XLineFactory for
 	 */
 	XLineFactory* GetFactory(const std::string &type);
 
@@ -473,15 +571,21 @@ class CoreExport XLineManager
 	 */
 	XLine* MatchesLine(const std::string &type, const std::string &pattern);
 
-	/** Expire a line given two iterators which identify it
+	/** Expire a line given two iterators which identify it in the main map.
+	 * @param container Iterator to the first level of entries the map
+	 * @param item Iterator to the second level of entries in the map
 	 */
 	void ExpireLine(ContainerIter container, LookupIter item);
 
-	/** Apply any new lines that are pending to be applied
+	/** Apply any new lines that are pending to be applied.
+	 * This will only apply lines in the pending_lines list, to save on
+	 * CPU time.
 	 */
 	void ApplyLines();
 
 	/** Handle /STATS for a given type.
+	 * NOTE: Any items in the list for this particular line type which have expired
+	 * will be expired and removed before the list is displayed.
 	 * @param numeric The numeric to give to each result line
 	 * @param user The username making the query
 	 * @param results The string_list to receive the results
@@ -489,11 +593,15 @@ class CoreExport XLineManager
 	void InvokeStats(const std::string &type, int numeric, User* user, string_list &results);
 };
 
+/** An XLineFactory specialized to generate GLine* pointers
+ */
 class CoreExport GLineFactory : public XLineFactory
 {
  public:
 	GLineFactory(InspIRCd* Instance) : XLineFactory(Instance, "G") { }
 
+	/** Generate a GLine
+	 */
 	XLine* Generate(time_t set_time, long duration, const char* source, const char* reason, const char* xline_specific_mask)
 	{
 		IdentHostPair ih = ServerInstance->XLines->IdentSplit(xline_specific_mask);
@@ -501,11 +609,15 @@ class CoreExport GLineFactory : public XLineFactory
 	}
 };
 
+/** An XLineFactory specialized to generate ELine* pointers
+ */
 class CoreExport ELineFactory : public XLineFactory
 {
  public:
 	ELineFactory(InspIRCd* Instance) : XLineFactory(Instance, "E") { }
 
+	/** Generate an ELine
+	 */
 	XLine* Generate(time_t set_time, long duration, const char* source, const char* reason, const char* xline_specific_mask)
 	{
 		IdentHostPair ih = ServerInstance->XLines->IdentSplit(xline_specific_mask);
@@ -513,11 +625,15 @@ class CoreExport ELineFactory : public XLineFactory
 	}
 };
 
+/** An XLineFactory specialized to generate KLine* pointers
+ */
 class CoreExport KLineFactory : public XLineFactory
 {
  public:
         KLineFactory(InspIRCd* Instance) : XLineFactory(Instance, "K") { }
 
+	/** Generate a KLine
+	 */
         XLine* Generate(time_t set_time, long duration, const char* source, const char* reason, const char* xline_specific_mask)
         {
                 IdentHostPair ih = ServerInstance->XLines->IdentSplit(xline_specific_mask);
@@ -525,22 +641,30 @@ class CoreExport KLineFactory : public XLineFactory
         }
 };
 
+/** An XLineFactory specialized to generate QLine* pointers
+ */
 class CoreExport QLineFactory : public XLineFactory
 {
  public:
         QLineFactory(InspIRCd* Instance) : XLineFactory(Instance, "Q") { }
 
+	/** Generate a QLine
+	 */
         XLine* Generate(time_t set_time, long duration, const char* source, const char* reason, const char* xline_specific_mask)
         {
                 return new QLine(ServerInstance, set_time, duration, source, reason, xline_specific_mask);
         }
 };
 
+/** An XLineFactory specialized to generate ZLine* pointers
+ */
 class CoreExport ZLineFactory : public XLineFactory
 {
  public:
         ZLineFactory(InspIRCd* Instance) : XLineFactory(Instance, "Z") { }
 
+	/** Generate a ZLine
+	 */
         XLine* Generate(time_t set_time, long duration, const char* source, const char* reason, const char* xline_specific_mask)
         {
                 return new ZLine(ServerInstance, set_time, duration, source, reason, xline_specific_mask);