Comment the caller0....caller8 classes

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

1 files changed, 25 insertions, 0 deletions

diff --git a/include/caller.h b/include/caller.h
index 328aed2c9..9f251d16c 100644
--- a/include/caller.h
+++ b/include/caller.h
@@ -14,6 +14,31 @@
 #ifndef __CALLER__H__
 #define __CALLER__H__
 
+/* The templates below can be auto generated by tools/create_templates.pl.
+ * They are used to represent a functor with a given number of parameters and
+ * a specific return type. To prevent passing the wrong number of parameters
+ * and have the compiler detect this error at build-time, each class is numbered
+ * according to the number of parameters it takes, e.g. caller0, caller1, caller2.
+ * These have been generated from zero parameters to eight.
+ *
+ * If you want to declare a functor which takes two parameters, a userrec and a chanrec,
+ * and returns bool, simply create it like this:
+ *
+ * caller2<bool, userrec*, chanrec*> MyFunction;
+ *
+ * and initialize it correctly, when placed into a class you will be able to call it:
+ *
+ * bool n = someclass->MyFunction(someuser, somechan);
+ *
+ * These functor templates work this way so that you can simply and easily allow
+ * for these class methods to be overridden from within a module, e.g. have a module
+ * which completely replaces the code for IsNick, etc. This is a very powerful feature
+ * which should be considered 'advanced' and not for beginners. If you do not
+ * understand these templates, STAY AWAY from playing with this until you do, as if
+ * you get this wrong, this can generate some pretty long winded and confusing error
+ * messages at compile time.
+ */
+
 template <typename ReturnType> class CoreExport HandlerBase0
 {
  public: