add documentation for scheduler factory

src/simulator/scheduler-factory.h

@@ -25,11 +25,23 @@ namespace ns3 {
 
 class Scheduler;
 
+/**
+ * \brief a base class to create event schedulers
+ *
+ * If you want to make the core simulation engine use a new
+ * event scheduler without editing the code of the simulator,
+ * you need to create a subclass of this base class and implement
+ * the ns3::SchedulerFactory::real_create method.
+ */
 class SchedulerFactory {
 public:
 	virtual ~SchedulerFactory ();
 	Scheduler *create (void) const;
 private:
+	/**
+	 * \returns a newly-created scheduler. The caller takes 
+	 *          ownership of the returned pointer.
+	 */
 	virtual Scheduler *real_create (void) const = 0;
 };
 

src/simulator/scheduler.h

@@ -29,6 +29,26 @@ namespace ns3 {
 
 class EventImpl;
 
+/**
+ * \brief Maintain the event list
+ *
+ * This base class specifies the interface used to maintain the 
+ * event list. If you want to provide a new event list scheduler, 
+ * you need to create a subclass of this base class and implement 
+ * all the private pure virtual methods defined here. Namely:
+ *   - ns3::Scheduler::real_insert
+ *   - ns3::Scheduler::real_is_empty
+ *   - ns3::Scheduler::real_peek_next
+ *   - ns3::Scheduler::real_peek_next_key
+ *   - ns3::Scheduler::real_remove_next
+ *   - ns3::Scheduler::real_remove
+ *   - ns3::Scheduler::real_is_valid
+ *
+ * If you need to provide a new event list scheduler without
+ * editing the main simulator class, you need to also implement
+ * a subclass of the ns3::SchedulerFactory base class and
+ * feed it to ns3::Simulator::set_external.
+ */
 class Scheduler {
  public:
 	struct EventKey {
@@ -51,12 +71,50 @@ class Scheduler {
 	bool is_valid (EventId id);
 
 private:
+	/**
+	 * \param event event to store in the event list
+	 * \param key timecode associated to this new event
+	 * \returns an event id which identifies the event inserted
+	 *
+	 * This method takes ownership of the event pointer.
+	 */
 	virtual EventId real_insert (EventImpl *event, EventKey key) = 0;
+	/**
+	 * \returns true if the event list is empty and false otherwise.
+	 */
 	virtual bool real_is_empty (void) const = 0;
+	/**
+	 * \returns a pointer to the next earliest event. The caller
+	 *          takes ownership of the returned pointer.
+	 *
+	 * This method cannot be invoked if the list is empty.
+	 */
 	virtual EventImpl *real_peek_next (void) const = 0;
+	/**
+	 * \returns the timecode associated with the next earliest event.
+	 *
+	 * This method cannot be invoked if the list is empty.
+	 */
 	virtual Scheduler::EventKey real_peek_next_key (void) const = 0;
+	/**
+	 * This method cannot be invoked if the list is empty.
+	 * Remove the next earliest event from the event list.
+	 */
 	virtual void real_remove_next (void) = 0;
+	/**
+	 * \param id the id of the event to remove
+	 * \param key the timecode of the event removed
+	 * \returns a pointer to the event removed. The caller
+	 *          takes ownership of the returned pointer.
+	 *
+	 * This methods cannot be invoked if the list is empty.
+	 */
 	virtual EventImpl *real_remove (EventId id, EventKey *key) = 0;
+	/**
+	 * \param id event id to validate
+	 * \returns true if the event id identifies an existing valid
+	 *          event stored in the event list and false otherwise.
+	 */
 	virtual bool real_is_valid (EventId id) = 0;
 };