Add some docs

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

1 files changed, 65 insertions, 6 deletions

diff --git a/include/logger.h b/include/logger.h
index 121d9ff25..754fa26e8 100644
--- a/include/logger.h
+++ b/include/logger.h
@@ -32,23 +32,29 @@ class CoreExport FileWriter : public EventHandler
 	/** The creator/owner of this object
 	 */
 	InspIRCd* ServerInstance;
+
 	/** The log file (fd is inside this somewhere,
 	 * we get it out with fileno())
 	 */
 	FILE* log;
+
 	/** Buffer of pending log lines to be written
 	 */
 	std::string buffer;
+
 	/** Number of write operations that have occured
 	 */
 	int writeops;
+
  public:
 	/** The constructor takes an already opened logfile.
 	 */
 	FileWriter(InspIRCd* Instance, FILE* logfile);
+
 	/** This returns false, logfiles are writeable.
 	 */
 	virtual bool Readable();
+
 	/** Handle pending write events.
 	 * This will flush any waiting data to disk.
 	 * If any data remains after the fprintf call,
@@ -56,6 +62,7 @@ class CoreExport FileWriter : public EventHandler
 	 * the rest of the data when possible.
 	 */
 	virtual void HandleEvent(EventType et, int errornum = 0);
+
 	/** Write one or more preformatted log lines.
 	 * If the data cannot be written immediately,
 	 * this class will insert itself into the
@@ -64,15 +71,37 @@ class CoreExport FileWriter : public EventHandler
 	 * attempt again to write the data.
 	 */
 	void WriteLogLine(const std::string &line);
+
 	/** Close the log file and cancel any events.
 	 */
 	virtual void Close();
+
 	/** Close the log file and cancel any events.
 	 * (indirectly call Close()
 	 */
 	virtual ~FileWriter();
 };
 
+
+
+/*
+ * New world logging!
+ * The brief summary:
+ *  Logging used to be a simple affair, a FILE * handled by a nonblocking logging class inheriting from EventHandler, that was inserted
+ *  into the socket engine, and wrote lines. If nofork was on, it was printf()'d.
+ *
+ *  We decided to horribly overcomplicate matters, and create vastly customisable logging. LogManager and LogStream form the visible basis
+ *  of the new interface. Basically, a LogStream can be inherited to do different things with logging output. We inherit from it once in core
+ *  to create a FileLogStream, that writes to a file, for example. Different LogStreams can hook different types of log messages, and different
+ *  levels of output too, for extreme customisation. Multiple LogStreams can hook the same message/levels of output, meaning that e.g. output
+ *  can go to a channel as well as a file.
+ *
+ *  HOW THIS WORKS
+ *   LogManager handles all instances of LogStreams, LogStreams (or more likely, derived classes) are instantiated and passed to it.
+ */
+
+/** LogStream base class. Modules (and other stuff) inherit from this to decide what logging they are interested in, and what to do with it.
+ */
 class CoreExport LogStream : public classbase
 {
  protected:
@@ -86,8 +115,15 @@ class CoreExport LogStream : public classbase
 
 	virtual ~LogStream() { }
 
-	void ChangeLevel(int lvl) { this->loglvl = lvl; } // For on-the-fly change of loglevel.
+	/** XXX document me properly.
+	 * Used for on the fly changing of loglevel.
+	 */
+	void ChangeLevel(int lvl) { this->loglvl = lvl; }
 
+	/** Called when there is stuff to log for this particular logstream. The derived class may take no action with it, or do what it
+	 * wants with the output, basically. loglevel and type are primarily for informational purposes (the level and type of the event triggered)
+	 * and msg is, of course, the actual message to log.
+	 */
 	virtual void OnLog(int loglevel, const std::string &type, const std::string &msg) = 0;
 };
 
@@ -96,13 +132,13 @@ typedef std::map<FileWriter*, int> FileLogMap;
 class CoreExport LogManager : public classbase
 {
  private:
-	bool Logging; // true when logging, avoids recursion
-	LogStream* noforkstream; // LogStream for nofork.
+	bool Logging;														// true when logging, avoids recursion
+	LogStream* noforkstream;											// LogStream for nofork.
 	InspIRCd *ServerInstance;
 	std::map<std::string, std::vector<LogStream *> > LogStreams;
-	std::map<LogStream *, int> AllLogStreams; // holds all logstreams
-	std::vector<LogStream *> GlobalLogStreams; //holds all logstreams with a type of *
-	FileLogMap FileLogs; /* Holds all file logs, refcounted */
+	std::map<LogStream *, int> AllLogStreams;							// holds all logstreams
+	std::vector<LogStream *> GlobalLogStreams;							//holds all logstreams with a type of *
+	FileLogMap FileLogs;												// Holds all file logs, refcounted
  public:
 	LogManager(InspIRCd *Instance)
 	{
@@ -112,6 +148,7 @@ class CoreExport LogManager : public classbase
 
 	void SetupNoFork();
 
+	/** XXX document me properly. */
 	void AddLoggerRef(FileWriter* fw)
 	{
 		FileLogMap::iterator i = FileLogs.find(fw);
@@ -125,6 +162,7 @@ class CoreExport LogManager : public classbase
 		}
 	}
 
+	/** XXX document me properly. */
 	void DelLoggerRef(FileWriter* fw)
 	{
 		FileLogMap::iterator i = FileLogs.find(fw);
@@ -136,13 +174,34 @@ class CoreExport LogManager : public classbase
 		}
 	}
 
+	/** XXX document me properly. */
 	void OpenSingleFile(FILE* f, const std::string& type, int loglevel);
+	
+	/** XXX document me properly. */
 	void OpenFileLogs();
+	
+	/** Gives all logstreams a chance to clear up (in destructors) while it deletes them.
+	 */
 	void CloseLogs();
+	
+	/** Registers a new logstream into the logging core, so it can be called for future events
+	 * XXX document me properly.
+	 */
 	bool AddLogType(const std::string &type, LogStream *l, bool autoclose);
+	
+	/** Removes a logstream from the core. After removal, it will not recieve further events.
+	 */
 	void DelLogStream(LogStream* l);
+	
+	/** XXX document me properly. */
 	bool DelLogType(const std::string &type, LogStream *l);
+	
+	/** Pretty self explanatory.
+	 */
 	void Log(const std::string &type, int loglevel, const std::string &msg);
+	
+	/** Duh.
+	 */
 	void Log(const std::string &type, int loglevel, const char *fmt, ...);
 };