- Documentation fixes

- Fixed boolean return values in libmidi++ to return bool instead of int


git-svn-id: svn://localhost/trunk/ardour2midi@538 d708f5d6-7413-0410-9779-e7cbd77b26cf

14 files changed, 69 insertions, 82 deletions

diff --git a/gtk2_ardour/axis_view.h b/gtk2_ardour/axis_view.h
index 38deece11a..fccb48e911 100644
--- a/gtk2_ardour/axis_view.h
+++ b/gtk2_ardour/axis_view.h
@@ -34,7 +34,7 @@ namespace ARDOUR {
 }
 
 /**
- * AxisView defines the abstract base class for time-axis trackviews and routes.
+ * The abstract base class for time-axis trackviews and routes.
  *
  */
 class AxisView : public virtual sigc::trackable
diff --git a/gtk2_ardour/crossfade_view.h b/gtk2_ardour/crossfade_view.h
index b4931c94c0..2294671de3 100644
--- a/gtk2_ardour/crossfade_view.h
+++ b/gtk2_ardour/crossfade_view.h
@@ -47,7 +47,7 @@ struct CrossfadeView : public TimeAxisViewItem
     AudioRegionView& right_view;
 
     std::string get_item_name();
-    void set_height (double);
+    void set_height (double h);
 
     bool valid() const { return _valid; }
     bool visible() const { return _visible; }
diff --git a/gtk2_ardour/glade_factory.h b/gtk2_ardour/glade_factory.h
index 2fff3bd167..93ffbc4b53 100644
--- a/gtk2_ardour/glade_factory.h
+++ b/gtk2_ardour/glade_factory.h
@@ -29,10 +29,9 @@
 typedef Glib::RefPtr<Gnome::Glade::Xml> GladeRef;
 
 /**
-   This is the base class for all glade 
-   factories so that the same domain is
-   used.
-*/
+ * This is the base class for all glade factories so that the same domain
+ * is used.
+ */
 class GladeFactory {
 	
 protected:
diff --git a/gtk2_ardour/gtk-custom-ruler.c b/gtk2_ardour/gtk-custom-ruler.c
index 0e7ceb5875..19a8a5dba6 100644
--- a/gtk2_ardour/gtk-custom-ruler.c
+++ b/gtk2_ardour/gtk-custom-ruler.c
@@ -300,18 +300,16 @@ gtk_custom_ruler_set_range (GtkCustomRuler *ruler,
     gtk_widget_queue_draw (GTK_WIDGET (ruler));
 }
 
-/**
- * gtk_custom_ruler_get_range:
- * @ruler: a #GtkCustomRuler
- * @lower: location to store lower limit of the ruler, or %NULL
- * @upper: location to store upper limit of the ruler, or %NULL
- * @position: location to store the current position of the mark on the ruler, or %NULL
- * @max_size: location to store the maximum size of the ruler used when calculating
- *            the space to leave for the text, or %NULL.
- *
- * Retrieves values indicating the range and current position of a #GtkCustomRuler.
+/** Retrieves values indicating the range and current position of a #GtkCustomRuler.
  * See gtk_custom_ruler_set_range().
- **/
+ *
+ * @param ruler: a #GtkCustomRuler
+ * @param lower: location to store lower limit of the ruler, or %NULL
+ * @param upper: location to store upper limit of the ruler, or %NULL
+ * @param position: location to store the current position of the mark on the ruler, or %NULL
+ * @param max_size: location to store the maximum size of the ruler used when calculating
+ *            the space to leave for the text, or %NULL.
+ */
 void
 gtk_custom_ruler_get_range (GtkCustomRuler *ruler,
 		     gdouble  *lower,
diff --git a/gtk2_ardour/gtkscrolledwindow.c b/gtk2_ardour/gtkscrolledwindow.c
index dcb6372afa..4161ea1baa 100644
--- a/gtk2_ardour/gtkscrolledwindow.c
+++ b/gtk2_ardour/gtkscrolledwindow.c
@@ -518,15 +518,13 @@ gtk_scrolled_window_set_policy (GtkScrolledWindow *scrolled_window,
     }
 }
 
-/**
- * gtk_scrolled_window_get_policy:
- * @scrolled_window: a #GtkScrolledWindow
- * @hscrollbar_policy: location to store the policy for the horizontal scrollbar, or %NULL.
- * @vscrollbar_policy: location to store the policy for the horizontal scrollbar, or %NULL.
- * 
- * Retrieves the current policy values for the horizontal and vertical
+/** * Retrieves the current policy values for the horizontal and vertical
  * scrollbars. See gtk_scrolled_window_set_policy().
- **/
+ *
+ * @param scrolled_window a GtkScrolledWindow
+ * @param hscrollbar_policy location to store the policy for the horizontal scrollbar, or %NULL.
+ * @param vscrollbar_policy location to store the policy for the horizontal scrollbar, or %NULL.
+ */
 void
 gtk_scrolled_window_get_policy (GtkScrolledWindow *scrolled_window,
 				GtkPolicyType     *hscrollbar_policy,
@@ -556,14 +554,11 @@ gtk_scrolled_window_set_placement (GtkScrolledWindow *scrolled_window,
     }
 }
 
-/**
- * gtk_scrolled_window_get_placement:
- * @scrolled_window: a #GtkScrolledWindow
+/** Gets the placement of the scrollbars for the scrolled window.
+ * See gtk_scrolled_window_set_placement().
  *
- * Gets the placement of the scrollbars for the scrolled window. See 
- * gtk_scrolled_window_set_placement().
- *
- * Return value: the current placement value.
+ * @param scrolled_window a GtkScrolledWindow
+ * \return the current placement value.
  **/
 GtkCornerType
 gtk_scrolled_window_get_placement (GtkScrolledWindow *scrolled_window)
@@ -573,15 +568,10 @@ gtk_scrolled_window_get_placement (GtkScrolledWindow *scrolled_window)
   return scrolled_window->window_placement;
 }
 
-/**
- * gtk_scrolled_window_set_shadow_type:
- * @scrolled_window: a #GtkScrolledWindow
- * @type: kind of shadow to draw around scrolled window contents
- *
- * Changes the type of shadow drawn around the contents of
- * @scrolled_window.
- * 
- **/
+/** Changes the type of shadow drawn around the contents of \a scrolled_window.
+ * @param scrolled_window a GtkScrolledWindow
+ * @param type kind of shadow to draw around scrolled window contents
+ */
 void
 gtk_scrolled_window_set_shadow_type (GtkScrolledWindow *scrolled_window,
 				     GtkShadowType      type)
@@ -602,15 +592,12 @@ gtk_scrolled_window_set_shadow_type (GtkScrolledWindow *scrolled_window,
     }
 }
 
-/**
- * gtk_scrolled_window_get_shadow_type:
- * @scrolled_window: a #GtkScrolledWindow
- *
- * Gets the shadow type of the scrolled window. See 
- * gtk_scrolled_window_set_shadow_type().
+/** Gets the shadow type of the scrolled window.
+ * See gtk_scrolled_window_set_shadow_type().
  *
- * Return value: the current shadow type
- **/
+ * @param scrolled_window a GtkScrolledWindow
+ * \return the current shadow type
+ */
 GtkShadowType
 gtk_scrolled_window_get_shadow_type (GtkScrolledWindow *scrolled_window)
 {
@@ -1387,14 +1374,11 @@ gtk_scrolled_window_add_with_viewport (GtkScrolledWindow *scrolled_window,
   gtk_container_add (GTK_CONTAINER (viewport), child);
 }
 
-/**
- * _gtk_scrolled_window_get_spacing:
- * @scrolled_window: a scrolled window
- * 
- * Gets the spacing between the scrolled window's scrollbars and
- * the scrolled widget. Used by GtkCombo
- * 
- * Return value: the spacing, in pixels.
+/** Gets the spacing between the scrolled window's scrollbars and
+ * the scrolled widget. Used by GtkCombo.
+ *
+ * @param scrolled_window: a scrolled window
+ * \return the spacing, in pixels.
  **/
 gint
 _gtk_scrolled_window_get_scrollbar_spacing (GtkScrolledWindow *scrolled_window)
diff --git a/gtk2_ardour/imageframe_socket_handler.h b/gtk2_ardour/imageframe_socket_handler.h
index 5af1824417..9627c6eb67 100644
--- a/gtk2_ardour/imageframe_socket_handler.h
+++ b/gtk2_ardour/imageframe_socket_handler.h
@@ -209,9 +209,10 @@ class ImageFrameSocketHandler : public sigc::trackable
 		/**
 		 * Send a message indicating that an ImageFrameView has been renamed
 		 *
-		 * @param item the ImageFrameView which has been renamed
+		 * @param new_id the renamed item's new ID
+		 * @param old_id the renamed item's old ID
 		 * @param src the identity of the object that initiated the change
-		 * @param item the renamed item
+		 * @param item the ImageFrameView which has been renamed
 		 */
 		void send_imageframe_view_renamed(const string & new_id, const string & old_id, void* src, ImageFrameView* item) ;
 		
diff --git a/gtk2_ardour/imageframe_time_axis.h b/gtk2_ardour/imageframe_time_axis.h
index cefd0c5d09..82a910e09e 100644
--- a/gtk2_ardour/imageframe_time_axis.h
+++ b/gtk2_ardour/imageframe_time_axis.h
@@ -79,7 +79,7 @@ class ImageFrameTimeAxis : public VisualTimeAxis
 		 *
 		 * @param h the TrackHeight value to set
 		 */	
-		virtual void set_height(TimeAxisView::TrackHeight) ;
+		virtual void set_height(TimeAxisView::TrackHeight h) ;
 		
 		/**
 		 * Sets the number of samples per unit that are used.
diff --git a/gtk2_ardour/imageframe_time_axis_group.h b/gtk2_ardour/imageframe_time_axis_group.h
index 1cd62d73f5..a22adb6660 100644
--- a/gtk2_ardour/imageframe_time_axis_group.h
+++ b/gtk2_ardour/imageframe_time_axis_group.h
@@ -104,7 +104,7 @@ class ImageFrameTimeAxisGroup : public sigc::trackable
 		 *
 		 * @param height the new height
 		 */
-		int set_item_heights(gdouble) ;
+		int set_item_heights(gdouble height) ;
 		
 		/**
 		 * Sets the current samples per unit.
@@ -119,7 +119,7 @@ class ImageFrameTimeAxisGroup : public sigc::trackable
 		 *
 		 * @param color the new base color
 		 */
-		void apply_item_color(Gdk::Color&) ;
+		void apply_item_color(Gdk::Color& color) ;
 		
 		
 		//---------------------------------------------------------------------------------------//
@@ -130,7 +130,6 @@ class ImageFrameTimeAxisGroup : public sigc::trackable
 		 * the new ImageFrameView is returned
 		 *
 		 * @param item_id the unique id of the new item
-		 * @param image_id the id/name of the image data we are usin
 		 * @param start the position the new item should be placed upon the time line
 		 * @param duration the duration the new item should be placed upon the timeline
 		 * @param rgb_data the rgb data of the image
@@ -139,7 +138,8 @@ class ImageFrameTimeAxisGroup : public sigc::trackable
 		 * @param num_channels the number of channles within the rgb_data
 		 * @param src the identity of the object that initiated the change
 		 */
-		ImageFrameView* add_imageframe_item(const string & item_id, jack_nframes_t start, jack_nframes_t duration, unsigned char* rgb_data, uint32_t width, uint32_t height, uint32_t num_channels, void* src) ;
+		ImageFrameView* add_imageframe_item(const string & item_id, jack_nframes_t start, jack_nframes_t duration,
+			unsigned char* rgb_data, uint32_t width, uint32_t height, uint32_t num_channels, void* src) ;
 		
 		/**
 		 * Returns the named ImageFrameView or 0 if the named view does not exist on this view helper
@@ -171,8 +171,9 @@ class ImageFrameTimeAxisGroup : public sigc::trackable
 		 * if ifv is not upon this TimeAxis, this method takes no action
 		 *
 		 * @param ifv the ImageFrameView to remove
+		 * @param src the identity of the object that initiated the change
 		 */
-		void remove_imageframe_item(ImageFrameView*, void* src) ;
+		void remove_imageframe_item(ImageFrameView* ifv, void* src) ;
 		
 	
 		//---------------------------------------------------------------------------------------//
diff --git a/gtk2_ardour/imageframe_time_axis_view.h b/gtk2_ardour/imageframe_time_axis_view.h
index d51901d4e0..f9487af058 100644
--- a/gtk2_ardour/imageframe_time_axis_view.h
+++ b/gtk2_ardour/imageframe_time_axis_view.h
@@ -87,7 +87,7 @@ class ImageFrameTimeAxisView : public sigc::trackable
 		 *
 		 * @param height the new height
 		 */
-		int set_height(gdouble) ;
+		int set_height(gdouble height) ;
 		
 		/**
 		 * Sets the position of this view helper on the canvas
@@ -117,7 +117,7 @@ class ImageFrameTimeAxisView : public sigc::trackable
 		 *
 		 * @param color the new base color
 		 */
-		void apply_color (Gdk::Color&) ;
+		void apply_color (Gdk::Color& color) ;
 		
 		//---------------------------------------------------------------------------------------//
 		// Child ImageFrameTimeAxisGroup Accessors/Mutators
@@ -152,6 +152,7 @@ class ImageFrameTimeAxisView : public sigc::trackable
 		 * Removes the specified ImageFrameTimeAxisGroup from the list of ImageFrameTimeAxisGroups upon this TimeAxis.
 		 *
 		 * @param iftag the ImageFrameView to remove
+		 * @param src the identity of the object that initiated the change
 		 */
 		void remove_imageframe_group(ImageFrameTimeAxisGroup* iftag, void* src) ;
 		
@@ -162,7 +163,7 @@ class ImageFrameTimeAxisView : public sigc::trackable
 		/**
 		 * Sets the currently selected group upon this time axis
 		 *
-		 * @param ifv the item to set selected
+		 * @param iftag the item to set selected
 		 */
 		void set_selected_imageframe_group(ImageFrameTimeAxisGroup* iftag) ;
 		
diff --git a/gtk2_ardour/imageframe_view.h b/gtk2_ardour/imageframe_view.h
index c599082580..2e67ff1c6c 100644
--- a/gtk2_ardour/imageframe_view.h
+++ b/gtk2_ardour/imageframe_view.h
@@ -53,6 +53,7 @@ class ImageFrameView : public TimeAxisViewItem
 		 * @param tv the time axis view that this item is to be placed upon
 		 * @param group the ImageFrameGroup that this item is a member of
 		 * @param spu the current samples per canvas unit
+		 * @param base_color the base color of this item
 		 * @param start the start frame ogf this item
 		 * @param duration the duration of this item
 		 * @param rgb_data the rgb data of the image
@@ -61,11 +62,11 @@ class ImageFrameView : public TimeAxisViewItem
 		 * @param num_channels the number of color channels within rgb_data
 		 */
 		ImageFrameView(const std::string & item_id,
-			 ArdourCanvas::Group *parent,
+			ArdourCanvas::Group *parent,
 			ImageFrameTimeAxis *tv,
 			ImageFrameTimeAxisGroup* group,
 			double spu,
-		        Gdk::Color& base_color,
+			Gdk::Color& base_color,
 			jack_nframes_t start,
 			jack_nframes_t duration,
 			unsigned char* rgb_data,
diff --git a/gtk2_ardour/marker_time_axis_view.h b/gtk2_ardour/marker_time_axis_view.h
index 1dd742a459..9eddafa59a 100644
--- a/gtk2_ardour/marker_time_axis_view.h
+++ b/gtk2_ardour/marker_time_axis_view.h
@@ -125,10 +125,10 @@ class MarkerTimeAxisView : public sigc::trackable
 		 * the new MarkerView is returned
 		 *
 		 * @param ifv the ImageFrameView that the new item is marking up
-		 * @param mark_text the text to be displayed uopn the new marker item
+		 * @param mark_type the text to be displayed uopn the new marker item
 		 * @param mark_id the unique id of the new item
 		 * @param start the position the new item should be placed upon the time line
-		 * @param duration the duration the new item should be placed upon the timeline
+		 * @param dur the duration the new item should be placed upon the timeline
 		 * @param src the identity of the object that initiated the change
 		 */
 		MarkerView* add_marker_view(ImageFrameView* ifv, std::string mark_type, std::string mark_id, jack_nframes_t start, jack_nframes_t dur, void* src) ;
@@ -163,7 +163,7 @@ class MarkerTimeAxisView : public sigc::trackable
 		/**
 		 * Removes mv from the list of MarkerView upon this TimeAxis
 		 *
-		 * @param mv the MarkerView to remove
+		 * @param item the MarkerView to remove
 		 * @param src the identity of the object that initiated the change
 		 */
 		void remove_marker_view(MarkerView* item, void* src) ;
diff --git a/gtk2_ardour/regionview.h b/gtk2_ardour/regionview.h
index cb71a8f3a7..690e21927b 100644
--- a/gtk2_ardour/regionview.h
+++ b/gtk2_ardour/regionview.h
@@ -64,9 +64,9 @@ class AudioRegionView : public TimeAxisViewItem
     void set_valid (bool yn) { valid = yn; }
 
     std::string get_item_name();
-    void set_height (double);
-    void set_samples_per_unit (double);
-    bool set_duration (jack_nframes_t, void*);
+    void set_height (double h);
+    void set_samples_per_unit (double spu);
+    bool set_duration (jack_nframes_t dur, void* src);
 
     void set_amplitude_above_axis (gdouble spp);
 
@@ -193,7 +193,7 @@ class AudioRegionView : public TimeAxisViewItem
     void store_flags ();
 
     void set_colors ();
-    void compute_colors (Gdk::Color&);
+    void compute_colors (Gdk::Color& color);
     virtual void set_frame_color ();
     void reset_width_dependent_items (double pixel_width);
     void set_waveview_data_src();
diff --git a/gtk2_ardour/time_axis_view.h b/gtk2_ardour/time_axis_view.h
index c607c78166..d761b316e3 100644
--- a/gtk2_ardour/time_axis_view.h
+++ b/gtk2_ardour/time_axis_view.h
@@ -263,7 +263,7 @@ class TimeAxisView : public virtual AxisView
 	/**
 	 * Displays the standard LHS controls size menu for the track heights
 	 *
-	 * @parem when the popup activation time
+	 * @param when the popup activation time
 	 */
  	void popup_size_menu(guint32 when);
 
diff --git a/gtk2_ardour/time_axis_view_item.h b/gtk2_ardour/time_axis_view_item.h
index c9e4fd5dd5..b802acf118 100644
--- a/gtk2_ardour/time_axis_view_item.h
+++ b/gtk2_ardour/time_axis_view_item.h
@@ -48,6 +48,7 @@ class TimeAxisViewItem : public sigc::trackable, public Selectable
      *
      * @param pos the new position
      * @param src the identity of the object that initiated the change
+	 * @param delta ignored
      * @return true if the position change was a success, false otherwise
      */
     virtual bool set_position(jack_nframes_t pos, void* src, double* delta = 0) ;
@@ -92,7 +93,7 @@ class TimeAxisViewItem : public sigc::trackable, public Selectable
     /**
      * Sets the minimu duration that this item may be set to
      *
-     * @param the minimum duration that this item may be set to
+     * @param dur the minimum duration that this item may be set to
      * @param src the identity of the object that initiated the change
      */
     virtual void set_min_duration(jack_nframes_t dur, void* src) ;
@@ -342,12 +343,13 @@ class TimeAxisViewItem : public sigc::trackable, public Selectable
      * @param parent the parent canvas group
      * @param tv the TimeAxisView we are going to be added to
      * @param spu samples per unit
-     * @param base_color
+     * @param base_color base color
      * @param start the start point of this item
      * @param duration the duration of this item
+	 * @param v visibility
      */
-    TimeAxisViewItem(const std::string & it_name, ArdourCanvas::Group& parent, TimeAxisView& tv, double spu, Gdk::Color& base_color, 
-		     jack_nframes_t start, jack_nframes_t duration, Visibility v = Visibility (0));
+    TimeAxisViewItem(const std::string & it_name, ArdourCanvas::Group& parent, TimeAxisView& tv, double spu,
+		Gdk::Color& base_color, jack_nframes_t start, jack_nframes_t duration, Visibility v = Visibility (0));
     
     /**
      * Calculates some contrasting color for displaying various parts of this item, based upon the base color