- 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

22 files changed, 114 insertions, 128 deletions

diff --git a/SConstruct b/SConstruct
index 6663674a3c..af89a24a2d 100644
--- a/SConstruct
+++ b/SConstruct
@@ -495,7 +495,7 @@ if env['SYSLIBS']:
 
 #    libraries['flowcanvas'] = LibraryInfo(LIBS='flowcanvas', LIBPATH='#/libs/flowcanvas', CPPPATH='#libs/flowcanvas')
     libraries['soundtouch'] = LibraryInfo()
-    libraries['soundtouch'].ParseConfig ('pkg-config --cflags --libs soundtouch-1.0')
+    libraries['soundtouch'].ParseConfig ('pkg-config --cflags --libs libSoundTouch')
 
     coredirs = [
         'templates'
diff --git a/ardour.dox b/ardour.dox
index 8bd87d6fa3..bd9d6a34db 100644
--- a/ardour.dox
+++ b/ardour.dox
@@ -138,7 +138,7 @@ SHORT_NAMES            = NO
 # comments will behave just like the Qt-style comments (thus requiring an 
 # explicit @brief command for a brief description.
 
-JAVADOC_AUTOBRIEF      = NO
+JAVADOC_AUTOBRIEF      = YES
 
 # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen 
 # treat a multi-line C++ special comment block (i.e. a block of //! or /// 
@@ -406,19 +406,19 @@ FILE_VERSION_FILTER    =
 # The QUIET tag can be used to turn on/off the messages that are generated 
 # by doxygen. Possible values are YES and NO. If left blank NO is used.
 
-QUIET                  = NO
+QUIET                  = YES
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are 
 # generated by doxygen. Possible values are YES and NO. If left blank 
 # NO is used.
 
-WARNINGS               = YES
+WARNINGS               = NO
 
 # If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings 
 # for undocumented members. If EXTRACT_ALL is set to YES then this flag will 
 # automatically be disabled.
 
-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO
 
 # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for 
 # potential errors in the documentation, such as not documenting some 
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
diff --git a/libs/midi++2/midi++/channel.h b/libs/midi++2/midi++/channel.h
index 1efde3cb93..f534f7e6da 100644
--- a/libs/midi++2/midi++/channel.h
+++ b/libs/midi++2/midi++/channel.h
@@ -73,37 +73,37 @@ class Channel : public sigc::trackable {
 		controller_val[n%128] = val;
 	}
 
-	int channel_msg (byte id, byte val1, byte val2);
+	bool channel_msg (byte id, byte val1, byte val2);
 
-	int all_notes_off () {
+	bool all_notes_off () {
 		return channel_msg (MIDI::controller, 123, 0);
 	}
 	
-	int control (byte id, byte value) {
+	bool control (byte id, byte value) {
 		return channel_msg (MIDI::controller, id, value);
 	}
 	
-	int note_on (byte note, byte velocity) {
+	bool note_on (byte note, byte velocity) {
 		return channel_msg (MIDI::on, note, velocity);
 	}
 	
-	int note_off (byte note, byte velocity) {
+	bool note_off (byte note, byte velocity) {
 		return channel_msg (MIDI::off, note, velocity);
 	}
 	
-	int aftertouch (byte value) {
+	bool aftertouch (byte value) {
 		return channel_msg (MIDI::chanpress, value, 0);
 	}
 
-	int poly_aftertouch (byte note, byte value) {
+	bool poly_aftertouch (byte note, byte value) {
 		return channel_msg (MIDI::polypress, note, value);
 	}
 
-	int program_change (byte value) {
+	bool program_change (byte value) {
 		return channel_msg (MIDI::program, value, 0);
 	}
 
-	int pitchbend (byte msb, byte lsb) {
+	bool pitchbend (byte msb, byte lsb) {
 		return channel_msg (MIDI::pitchbend, lsb, msb);
 	}
 
diff --git a/libs/midi++2/midi++/port.h b/libs/midi++2/midi++/port.h
index 81e28615d0..442cc4e5ed 100644
--- a/libs/midi++2/midi++/port.h
+++ b/libs/midi++2/midi++/port.h
@@ -50,17 +50,17 @@ class Port : public sigc::trackable {
 
 	/* Direct I/O */
 
+	/** \return number of bytes successfully written */
 	virtual int write (byte *msg, size_t msglen) = 0;	
+
+	/** \return number of bytes successfully written to \a buf */
 	virtual int read (byte *buf, size_t max) = 0;
 
-	/* slowdown i/o to a loop of single byte emissions
+	/** Slow down I/O to a loop of single byte emissions
 	   interspersed with a busy loop of 10000 * this value.
 
-	   This may be ignored by a particular instance
-	   of this virtual class. See FD_MidiPort for an 
-	   example of where it used.  
-	*/
-
+	   This may be ignored by a particular instance of this virtual
+	   class. See FD_MidiPort for an example of where it used.  */
 	void set_slowdown (size_t n) { slowdown = n; }
 
 	/* select(2)/poll(2)-based I/O */
@@ -99,21 +99,25 @@ class Port : public sigc::trackable {
 		}
 	}
 	
-	int midimsg (byte *msg, size_t len) {
+	/** Write a message.
+	 * \return true on success. */
+	bool midimsg (byte *msg, size_t len) {
 		return !(write (msg, len) == (int) len);
 	} 
 
-	int three_byte_msg (byte a, byte b, byte c) {
+	/** Write a 3-byte message.
+	 * \return true on success. */
+	bool three_byte_msg (byte a, byte b, byte c) {
 		byte msg[3];
-
-            	msg[0] = a;
+		
+        msg[0] = a;
 		msg[1] = b;
 		msg[2] = c;
 
 		return !(write (msg, 3) == 3);
 	} 
 	
-	int clock ();
+	bool clock ();
 	
 	const char *device () const { return _devname.c_str(); }
 	const char *name () const   { return _tagname.c_str(); }
diff --git a/libs/midi++2/midichannel.cc b/libs/midi++2/midichannel.cc
index a6759b7962..42949591fe 100644
--- a/libs/midi++2/midichannel.cc
+++ b/libs/midi++2/midichannel.cc
@@ -249,9 +249,11 @@ Channel::process_reset (Parser &parser)
 	reset ();
 }
 
-int
+/** Write a message to a channel.
+ * \return true if success
+ */
+bool
 Channel::channel_msg (byte id, byte val1, byte val2)
-
 {
 	unsigned char msg[3];
 	int len = 0;
diff --git a/libs/midi++2/midiparser.cc b/libs/midi++2/midiparser.cc
index 04ac2728f1..975a77a2c5 100644
--- a/libs/midi++2/midiparser.cc
+++ b/libs/midi++2/midiparser.cc
@@ -523,13 +523,9 @@ Parser::scanner (unsigned char inbyte)
 	return;
 }
 
-/*
- * realtime_msg(inbyte)
- *
- * Call the real-time function for the specified byte, immediately.
+/** Call the real-time function for the specified byte, immediately.
  * These can occur anywhere, so they don't change the state.
  */
-
 void
 Parser::realtime_msg(unsigned char inbyte)
 
@@ -565,12 +561,9 @@ Parser::realtime_msg(unsigned char inbyte)
 	any (*this, &inbyte, 1);
 }
 
-/*
- * channel_msg(inbyte)
- *
- * Interpret a Channel (voice or mode) Message status byte.
- */
 
+/** Interpret a Channel (voice or mode) Message status byte.
+ */
 void
 Parser::channel_msg(unsigned char inbyte)
 {
@@ -611,16 +604,12 @@ Parser::channel_msg(unsigned char inbyte)
 	}
 }
 
-/*
- * system_msg(inbyte)
- *
- * Initialize (and possibly emit) the signals for the
+/** Initialize (and possibly emit) the signals for the
  * specified byte.  Set the state that the state-machine
  * should go into.  If the signal is not emitted
  * immediately, it will be when the state machine gets to
  * the end of the MIDI message.
  */
-
 void
 Parser::system_msg (unsigned char inbyte)
 {
diff --git a/libs/midi++2/midiport.cc b/libs/midi++2/midiport.cc
index 6d374ed8c0..a7c4ba0940 100644
--- a/libs/midi++2/midiport.cc
+++ b/libs/midi++2/midiport.cc
@@ -83,7 +83,10 @@ Port::~Port ()
 	}
 }
 
-int
+/** Send a clock tick message.
+ * \return true on success.
+ */
+bool
 Port::clock ()
 	
 {
@@ -93,7 +96,7 @@ Port::clock ()
 		return midimsg (&clockmsg, 1);
 	}
 	
-	return 0;
+	return false;
 }
 
 void
diff --git a/libs/pbd3/pbd/ringbufferNPT.h b/libs/pbd3/pbd/ringbufferNPT.h
index d559a53d94..2ff469dc12 100644
--- a/libs/pbd3/pbd/ringbufferNPT.h
+++ b/libs/pbd3/pbd/ringbufferNPT.h
@@ -24,8 +24,9 @@
 #include <sys/mman.h>
 #include <pbd/atomic.h>
 
-/* ringbuffer class where the element size is not required to be a power of two */
-
+/** Ringbuffer class where the element size is not required to be a
+ * power of two.
+ */
 template<class T>
 class RingBufferNPT
 {