improve comments and add more explanation about subtleties

svn path=/trunk/netsurf/; revision=11686

1 files changed, 28 insertions, 0 deletions

diff --git a/windows/schedule.h b/windows/schedule.h
index 2c9b55f82..e6a5d10d0 100644
--- a/windows/schedule.h
+++ b/windows/schedule.h
@@ -19,7 +19,35 @@
 #ifndef FRAMEBUFFER_SCHEDULE_H
 #define FRAMEBUFFER_SCHEDULE_H
 
+/**
+ * Process scheduled callbacks up to current time.
+ *
+ * This walks the list of outstanding scheduled events and dispatches
+ * them if they have met their scheduled time. Due to legacy issues
+ * there are a couple of subtleties with how this operates:
+ *
+ * - Generally there are so few entries on the list the overhead of
+ *     ordering the list exceeds the cost of simply enumerating them.
+ *
+ * - The scheduled time is the time *after* which we should call the
+ *     operation back, this can result in the next scheduled time
+ *     being zero. This is exceedingly rare as the core schedules in
+ *     10ms (cs) quanta and we almost always get called to schedule
+ *     after the event time.
+ *
+ * - The callbacks can cause the schedule list to be re-arranged added
+ *     to or even completely deleted. This means we must reset the
+ *     list enumeration to the beginning every time an event is
+ *     dispatched.
+ *
+ * @return The number of milliseconds untill the next scheduled event
+ * or -1 for no event.
+ */
 int schedule_run(void);
+
+/**
+ * LOG all current scheduled events.
+ */
 void list_schedule(void);
 
 #endif