Further tidied up tools and added some documentation

src/gui/widgets/timeline/timeline-arrow-tool.hpp

@@ -37,11 +37,22 @@ namespace timeline {
 class ArrowTool : public Tool
 {
 public:
+  /**
+   * Constructor
+   * @param timeline_body The owner timeline body object
+   */
   ArrowTool(TimelineBody *timeline_body);
 
+  /**
+   * Gets the type of tool represented by this class
+   */
   ToolType get_type() const;
   
 protected:
+
+  /**
+   * Gets the cursor to display for this tool at this moment.
+   */
   Gdk::Cursor get_cursor() const;
   
 protected:

src/gui/widgets/timeline/timeline-ibeam-tool.hpp

@@ -35,16 +35,29 @@ namespace gui {
 namespace widgets {
 namespace timeline {
 
+/**
+ * A helper class to implement the timeline i-beam tool
+ */
 class IBeamTool : public Tool
 {
 public:
+  /**
+   * Constructor
+   * @param timeline_body The owner timeline body object
+   */
   IBeamTool(TimelineBody *timeline_body);
   
   ~IBeamTool();
 
+  /**
+   * Gets the type of tool represented by this class
+   */
   ToolType get_type() const;
   
 protected:
+  /**
+   * Gets the cursor to display for this tool at this moment.
+   */
   Gdk::Cursor get_cursor() const;
   
 protected:
@@ -53,21 +66,42 @@ protected:
   void on_motion_notify_event(GdkEventMotion *event);
   
 private:
+  /* ===== Internal Event Handlers ===== */
+
+  /**
+   * An internal event handler, which is called when the scroll slide
+   * timer calls it.
+   */
   bool on_scroll_slide_timer();
   
 private:
+  /* ===== Internal Methods ===== */
+
+  /**
+   * As the user drags, this function is called to update the position
+   * of the moving end of the selection.
+   */
   void set_leading_x(const int x);
   
+  /**
+   * Begins, or continues a scroll slide at a given rate
+   * @param scroll_slide_rate The distance to slide every timer event
+   * in units of 1/256th of the view width.
+   */
   void begin_scroll_slide(int scroll_slide_rate);
+  
+  /**
+   * Ends a scroll slide, and disconnects the slide timer
+   */
   void end_scroll_slide();
   
 private:
-  // ==== Internals ===== //
+  /* ==== Internals ===== */
   gavl_time_t dragStartTime;
   sigc::connection scrollSlideEvent;
   int scrollSlideRate;
   
-  // ===== Constants ===== //
+  /* ===== Constants ===== */
   static const int ScrollSlideRateDivisor;
   static const int ScrollSlideEventInterval;
 };

src/gui/widgets/timeline/timeline-tool.hpp

@@ -38,7 +38,10 @@ class TimelineWidget;
 namespace timeline {
   
 class TimelineBody;
-  
+
+/**
+ * Specifies the types of different timeline tool classes.
+ */
 enum ToolType
 {
   None,
@@ -49,13 +52,24 @@ enum ToolType
 class Tool
 {
 protected:
+  /**
+   * Constructor
+   * @param timeline_body The owner timeline body object
+   */
   Tool(TimelineBody *timeline_body);
   
 public:
   virtual ~Tool() {};
 
+  /**
+   * Gets the type of tool represented by this class.
+   * @remarks This must be implemented by all timeline tool classes.
+   */
   virtual ToolType get_type() const = 0;
   
+  /**
+   * Reaplies the cursor for the current tool at the current moment.
+   */
   bool apply_cursor();
   
 public:
@@ -65,12 +79,26 @@ public:
   virtual void on_motion_notify_event(GdkEventMotion *event) {}
   
 protected:
+  /* ===== Internal Overrides ===== */
+  /**
+   * Gets the cursor to display for this tool at this moment.
+   * @remarks This must be implemented by all timeline tool classes.
+   */
   virtual Gdk::Cursor get_cursor() const = 0;
 
 protected:
   /* ===== Utilities ===== */
+  
+  /**
+   * Helper function which retrieves the pointer to owner timeline
+   * widget object, which is the owner of the timeline body.
+   */
   lumiera::gui::widgets::TimelineWidget *get_timeline_widget() const;
   
+  /**
+   * Helper function which retrieves the rectangle of the timeline
+   * body.
+   */
   Gdk::Rectangle get_body_rectangle() const;
 
 protected: