diff --git a/libs/ardour/ardour/session.h b/libs/ardour/ardour/session.h
index c44fa9eba1..82fe06a9f3 100644
--- a/libs/ardour/ardour/session.h
+++ b/libs/ardour/ardour/session.h
@@ -274,7 +274,15 @@ class Session : public PBD::StatefulDestructible, public PBD::ScopedConnectionLi
 
 	/* Transport mechanism signals */
 
-	PBD::Signal0<void> TransportStateChange; /* generic */
+	/** Emitted on the following changes in transport state:
+	 *  - stop (from the butler thread)
+	 *  - change in whether or not we are looping (from the process thread)
+	 *  - change in the play range (from the process thread)
+	 *  - start (from the process thread)
+	 *  - engine halted
+	*/
+	PBD::Signal0<void> TransportStateChange;
+	
 	PBD::Signal1<void,framepos_t> PositionChanged; /* sent after any non-sequential motion */
 	PBD::Signal1<void,framepos_t> Xrun;
 	PBD::Signal0<void> TransportLooped;
diff --git a/libs/ardour/session_transport.cc b/libs/ardour/session_transport.cc
index 3dc1f9e7b3..ac384c4876 100644
--- a/libs/ardour/session_transport.cc
+++ b/libs/ardour/session_transport.cc
@@ -924,8 +924,8 @@ Session::locate (framepos_t target_frame, bool with_roll, bool with_flush, bool
 }
 
 /** Set the transport speed.
- * @param speed New speed
- * @param abort
+ *  Called from the process thread.
+ *  @param speed New speed
  */
 void
 Session::set_transport_speed (double speed, bool abort, bool clear_state)
@@ -1097,6 +1097,7 @@ Session::stop_transport (bool abort, bool clear_state)
 	_butler->schedule_transport_work ();
 }
 
+/** Called from the process thread */
 void
 Session::start_transport ()
 {
@@ -1447,7 +1448,7 @@ Session::engine_halted ()
 void
 Session::xrun_recovery ()
 {
-	Xrun (_transport_frame); //EMIT SIGNAL
+	Xrun (_transport_frame); /* EMIT SIGNAL */
 
 	if (Config->get_stop_recording_on_xrun() && actively_recording()) {