+#include "inspircd.h"
+
+/* $ModDesc: Provides support for the /WATCH command */
+
+
+/*
+ * Okay, it's nice that this was documented and all, but I at least understood very little
+ * of it, so I'm going to attempt to explain the data structures in here a bit more.
+ *
+ * For efficiency, many data structures are kept.
+ *
+ * The first is a global list `watchentries':
+ * hash_map<irc::string, std::deque<User*> >
+ *
+ * That is, if nick 'w00t' is being watched by user pointer 'Brain' and 'Om', <w00t, (Brain, Om)>
+ * will be in the watchentries list.
+ *
+ * The second is that each user has a per-user data structure attached to their user record via Extensible:
+ * std::map<irc::string, std::string> watchlist;
+ * So, in the above example with w00t watched by Brain and Om, we'd have:
+ * Brain-
+ * `- w00t
+ * Om-
+ * `- w00t
+ *
+ * Hopefully this helps any brave soul that ventures into this file other than me. :-)
+ * -- w00t (mar 30, 2008)
+ */
+
+
+/* This module has been refactored to provide a very efficient (in terms of cpu time)
+ * implementation of /WATCH.
+ *
+ * To improve the efficiency of watch, many lists are kept. The first primary list is
+ * a hash_map of who's being watched by who. For example:
+ *
+ * KEY: Brain ---> Watched by: Boo, w00t, Om
+ * KEY: Boo ---> Watched by: Brain, w00t
+ *
+ * This is used when we want to tell all the users that are watching someone that
+ * they are now available or no longer available. For example, if the hash was
+ * populated as shown above, then when Brain signs on, messages are sent to Boo, w00t
+ * and Om by reading their 'watched by' list. When this occurs, their online status
+ * in each of these users lists (see below) is also updated.
+ *
+ * Each user also has a seperate (smaller) map attached to their User whilst they
+ * have any watch entries, which is managed by class Extensible. When they add or remove
+ * a watch entry from their list, it is inserted here, as well as the main list being
+ * maintained. This map also contains the user's online status. For users that are
+ * offline, the key points at an empty string, and for users that are online, the key
+ * points at a string containing "users-ident users-host users-signon-time". This is
+ * stored in this manner so that we don't have to FindUser() to fetch this info, the
+ * users signon can populate the field for us.
+ *
+ * For example, going again on the example above, this would be w00t's watchlist:
+ *
+ * KEY: Boo ---> Status: "Boo brains.sexy.babe 535342348"
+ * KEY: Brain ---> Status: ""
+ *
+ * In this list we can see that Boo is online, and Brain is offline. We can then
+ * use this list for 'WATCH L', and 'WATCH S' can be implemented as a combination
+ * of the above two data structures, with minimum CPU penalty for doing so.
+ *
+ * In short, the least efficient this ever gets is O(n), and thats only because
+ * there are parts that *must* loop (e.g. telling all users that are watching a
+ * nick that the user online), however this is a *major* improvement over the
+ * 1.0 implementation, which in places had O(n^n) and worse in it, because this
+ * implementation scales based upon the sizes of the watch entries, whereas the
+ * old system would scale (or not as the case may be) according to the total number
+ * of users using WATCH.
+ */
+
+/*
+ * Before you start screaming, this definition is only used here, so moving it to a header is pointless.
+ * Yes, it's horrid. Blame cl for being different. -- w00t
+ */