Add some more doxygen comments

git-svn-id: https://znc.svn.sourceforge.net/svnroot/znc/trunk@1718 726aef4b-f618-498e-8847-2d620e286838

Modules.h

@@ -46,10 +46,33 @@ typedef void* ModHandle;
 	double ZNCModVersion() { return VERSION; } \
 	bool ZNCModGlobal() { return GLOBAL; } \
 
+/** Instead of writing a constructor, you should call this macro. It accepts all
+ *  the necessary arguments and passes them on to CModule's constructor. You
+ *  should assume that there are no arguments to the constructor.
+ *
+ *  Usage:
+ *  \code
+ *  class MyModule : public CModule {
+ *      MODCONSTRUCTOR(MyModule) {
+ *          // Your own constructor's code here
+ *      }
+ *  }
+ *  \endcode
+ *
+ *  @param CLASS The name of your module's class.
+ *  @see For global modules you need GLOBALMODCONSTRUCTOR.
+ */
 #define MODCONSTRUCTOR(CLASS) \
 	CLASS(ModHandle pDLL, CUser* pUser, const CString& sModName, \
 			const CString& sModPath) \
 			: CModule(pDLL, pUser, sModName, sModPath)
+
+/** At the end of your source file, you must call this macro in global context.
+ *  It defines some static functions which ZNC needs to load this module.
+ *  @param CLASS The name of your module's class.
+ *  @param DESCRIPTION A short description of your module.
+ *  @see For global modules you need GLOBALMODULEDEFS.
+ */
 #define MODULEDEFS(CLASS, DESCRIPTION) \
 	extern "C" { \
 		MODCOMMONDEFS(DESCRIPTION, false) \
@@ -65,9 +88,12 @@ typedef void* ModHandle;
 // !User Module Macros
 
 // Global Module Macros
+/** This works exactly like MODCONSTRUCTOR, but for global modules. */
 #define GLOBALMODCONSTRUCTOR(CLASS) \
 	CLASS(ModHandle pDLL, const CString& sModName, const CString& sModPath) \
 			: CGlobalModule(pDLL, sModName, sModPath)
+
+/** This works exactly like MODULEDEFS, but for global modules. */
 #define GLOBALMODULEDEFS(CLASS, DESCRIPTION) \
 	extern "C" { \
 		MODCOMMONDEFS(DESCRIPTION, true) \

Utils.h

@@ -26,6 +26,17 @@ using std::pair;
 using std::cout;
 using std::endl;
 
+/** Output a debug info if debugging is enabled.
+ *  If ZNC was compiled with <code>--enable-debug</code> or was started with
+ *  <code>--debug</code>, the given argument will be sent to stdout.
+ *
+ *  You can use all the features of C++ streams:
+ *  @code
+ *  DEBUG("I had " << errors << " errors");
+ *  @endcode
+ *
+ *  @param f The expression you want to display.
+ */
 #define DEBUG(f) do { \
 	if (CUtils::Debug()) { \
 		cout << f << endl; \
@@ -110,19 +121,78 @@ protected:
 };
 
 
+/** Generate a grid-like output from a given input.
+ *
+ *  @code
+ *  CTable table;
+ *  table.AddColumn("a");
+ *  table.AddColumn("b");
+ *  table.AddRow();
+ *  table.SetCell("a", "hello");
+ *  table.SetCell("b", "world");
+ *
+ *  unsigned int idx = 0;
+ *  CString tmp;
+ *  while (table.GetLine(idx++, tmp)) {
+ *      // Output tmp somehow
+ *  }
+ *  @endcode
+ *
+ *  The above code would generate the following output:
+ *  @verbatim
++-------+-------+
+| a     | b     |
++-------+-------+
+| hello | world |
++-------+-------+@endverbatim
+ */
 class CTable : protected vector<vector<CString> > {
 public:
 	CTable() {}
 	virtual ~CTable() {}
 
+	/** Adds a new column to the table.
+	 *  Please note that you should add all columns before starting to fill
+	 *  the table!
+	 *  @param sName The name of the column.
+	 *  @return false if a column by that name already existed.
+	 */
 	bool AddColumn(const CString& sName);
+
+	/** Adds a new row to the table.
+	 *  After calling this you can fill the row with content.
+	 *  @return The index of this row
+	 */
 	unsigned int AddRow();
+
+	/** Sets a given cell in the table to a value.
+	 *  @param sColumn The name of the column you want to fill.
+	 *  @param sValue The value to write into that column.
+	 *  @param uRowIdx The index of the row to use as returned by AddRow().
+	 *                 If this is not given, the last row will be used.
+	 *  @return True if setting the cell was successful.
+	 */
 	bool SetCell(const CString& sColumn, const CString& sValue, unsigned int uRowIdx = ~0);
+
+	/** Get a line of the table's output
+	 *  @param uIdx The index of the line you want.
+	 *  @param sLine This string will receive the output.
+	 *  @return True unless uIdx is past the end of the table.
+	 */
 	bool GetLine(unsigned int uIdx, CString& sLine) const;
 
+	/** Return the width of the given column.
+	 *  Please note that adding and filling new rows might change the
+	 *  result of this function!
+	 *  @param uIdx The index of the column you are interested in.
+	 *  @return The width of the column.
+	 */
 	unsigned int GetColumnWidth(unsigned int uIdx) const;
 
+	/// Completely clear the table.
 	void Clear();
+
+	/// @return The number of rows in this table, not counting the header.
 	using vector<vector<CString> >::size;
 private:
 	unsigned int GetColumnIndex(const CString& sName) const;

main.h

@@ -53,4 +53,22 @@
 #define MODULECALL(macFUNC, macUSER, macCLIENT, macEXITER)
 #endif
 
+/** @mainpage
+ *  Welcome to the API documentation for ZNC.
+ *
+ *  To write your own module, you should start with writing a new class which
+ *  inherits from CModule. Use #MODCONSTRUCTOR for the module's constructor and
+ *  call #MODULEDEFS at the end of your source file.
+ *  Congratulations, you just wrote your first module. <br>
+ *  For global modules, the procedure is similar. Instead of CModule you inherit
+ *  from CGlobalModule. The two macros are replaced by #GLOBALMODCONSTRUCTOR and
+ *  #GLOBALMODULEDEFS.
+ *
+ *  If you want your module to actually do something, you should override some
+ *  of the hooks from CModule. These are the functions whose names start with
+ *  "Do". They are called when the associated event happens.
+ *
+ *  Feel free to also look at existing modules.
+ */
+
 #endif // !_MAIN_H