No-op: comments.

git-svn-id: svn://localhost/ardour2/branches/3.0@5245 d708f5d6-7413-0410-9779-e7cbd77b26cf

gtk2_ardour/group_tabs.cc

@@ -78,8 +78,10 @@ GroupTabs::on_button_press_event (GdkEventButton* ev)
 		_drag_from = p < h;
 
 		if (_drag_from) {
+			/* limit is the end of the previous tab */
 			_drag_limit = prev ? prev->to : 0;
 		} else {
+			/* limit is the start of the next tab */
 			_drag_limit = next ? next->from : extent ();
 		}
 
@@ -109,13 +111,15 @@ GroupTabs::on_motion_notify_event (GdkEventMotion* ev)
 	if (_drag_from) {
 		
 		double f = _dragging->from + p - _drag_last;
-		
+
 		if (f < _drag_limit) {
+			/* limit drag in the `too big' direction */
 			f = _drag_limit;
 		}
 
 		double const t = _dragging->to - _dragging->last_ui_size;
 		if (f > t) {
+			/* limit drag in the `too small' direction */
 			f = t;
 		}
 		
@@ -126,11 +130,13 @@ GroupTabs::on_motion_notify_event (GdkEventMotion* ev)
 		double t = _dragging->to + p - _drag_last;
 
 		if (t > _drag_limit) {
+			/* limit drag in the `too big' direction */
 			t = _drag_limit;
 		}
 
 		double const f = _dragging->from + _dragging->first_ui_size;
 		if (t < f) {
+			/* limit drag in the `too small' direction */
 			t = f;
 		}
 		
@@ -154,9 +160,11 @@ GroupTabs::on_button_release_event (GdkEventButton* ev)
 	}
 
 	if (!_drag_moved) {
+		/* toggle active state */
 		_dragging->group->set_active (!_dragging->group->is_active (), this);
 		_dragging = 0;
 	} else {
+		/* finish drag */
 		_dragging = 0;
 		reflect_tabs (_tabs);
 		set_dirty ();
@@ -187,6 +195,13 @@ GroupTabs::render (cairo_t* cr)
 }
 
 
+/** Convert a click position to a tab.
+ *  @param c Click position.
+ *  @param prev Filled in with the previous tab to the click, or 0.
+ *  @param next Filled in with the next tab after the click, or 0.
+ *  @return Tab under the click, or 0.
+ */
+ 
 GroupTabs::Tab *
 GroupTabs::click_to_tab (double c, Tab** prev, Tab** next)
 {

gtk2_ardour/group_tabs.h

@@ -27,6 +27,9 @@ namespace ARDOUR {
 
 class Editor;
 
+/** Parent class for tabs which represent route groups as coloured tabs;
+ *  Currently used on the left-hand side of the editor and at the top of the mixer.
+ */
 class GroupTabs : public CairoWidget
 {
 public:
@@ -37,23 +40,46 @@ public:
 protected:
 
 	struct Tab {
-		double from;
-		double to;
-		Gdk::Color colour;
-		ARDOUR::RouteGroup* group;
-		double first_ui_size;
-		double last_ui_size;
+		double from; ///< start coordinate
+		double to; ///< end coordinate
+		Gdk::Color colour; ///< colour
+		ARDOUR::RouteGroup* group; ///< route group
+		double first_ui_size; ///< GUI size of the first route in the group
+		double last_ui_size; ///< GUI size of the last route in the group
 	};
 
-	ARDOUR::Session* _session;
+	ARDOUR::Session* _session; ///< our session
 
 private:
+	/** Compute all the tabs for this widget.
+	 *  @return Tabs.
+	 */
 	virtual std::list<Tab> compute_tabs () const = 0;
-	virtual void draw_tab (cairo_t *, Tab const &) const = 0;
+
+	/** Draw a tab.
+	 *  @param cr Cairo context.
+	 *  @param t Tab.
+	 */
+	virtual void draw_tab (cairo_t* cr, Tab const & t) const = 0;
+
+	/** @param x x coordinate
+	 *  @param y y coordinate
+	 *  @return x or y, depending on which is the primary coordinate for this widget.
+	 */
 	virtual double primary_coordinate (double, double) const = 0;
-	virtual void reflect_tabs (std::list<Tab> const &) = 0;
+
+	/** Take a list of tabs and alter the route groups to reflect the tabs.
+	 *  @param tabs.
+	 */
+	virtual void reflect_tabs (std::list<Tab> const & tabs) = 0;
+
+	/** @return Size of the widget along the primary axis */
 	virtual double extent () const = 0;
-	virtual Gtk::Menu* get_menu (ARDOUR::RouteGroup *) = 0;
+
+	/** @param g Route group.
+         *  @return Menu to be popped up on right-click over the given route group.
+	 */
+	virtual Gtk::Menu* get_menu (ARDOUR::RouteGroup* g) = 0;
 
 	void render (cairo_t *);
 	void on_size_request (Gtk::Requisition *);
@@ -63,10 +89,10 @@ private:
 
 	Tab * click_to_tab (double, Tab**, Tab**);
 
-	std::list<Tab> _tabs;
-	Tab* _dragging;
-	bool _drag_moved;
-	bool _drag_from;
-	double _drag_last;
-	double _drag_limit;
+	std::list<Tab> _tabs; ///< current list of tabs
+	Tab* _dragging; ///< tab being dragged, or 0
+	bool _drag_moved; ///< true if there has been movement during any current drag
+	bool _drag_from; ///< true if the drag is of the `from' end of the tab, otherwise it's the `to' end
+	double _drag_last; ///< last mouse pointer position during drag
+	double _drag_limit; ///< limit of the current drag
 };

gtk2_ardour/utils.cc

@@ -113,6 +113,13 @@ fit_to_pixels (const ustring& str, int pixel_width, Pango::FontDescription& font
 	return txt;
 }
 
+/** Try to fit a string into a given horizontal space by ellipsizing it.
+ *  @param cr Cairo context in which the text will be plotted.
+ *  @param name Text.
+ *  @param avail Available horizontal space.
+ *  @return (Text, possibly ellipsized) and (horizontal size of text)
+ */
+
 std::pair<std::string, double>
 fit_to_pixels (cairo_t* cr, std::string name, double avail)
 {