MMDevice: Clarify docs for stage position changes

MMDevice/DeviceBase.h

@@ -1139,7 +1139,15 @@ class CDeviceBase : public T
    }
 
    /**
-    * @brief Signal that the stage has arrived at a new position.
+    * @brief Report position change (for single-axis stage).
+    *
+    * Stages that do not receive change notifications from the hardware/driver
+    * don't have to call this. In particular, they should not use this to
+    * report the destination of a move that has not yet completed.
+    *
+    * It is up to the stage whether to report only after moves finish or also
+    * periodically during moves. But the reported position should eventually
+    * catch up to the actual position after the stage stops moving.
     */
    int OnStagePositionChanged(double pos)
    {
@@ -1149,7 +1157,15 @@ class CDeviceBase : public T
    }
 
    /**
-    * @brief Signal that the XY stage has arrived at a new position.
+    * @brief Report position change (for XY stage).
+    *
+    * Stages that do not receive change notifications from the hardware/driver
+    * don't have to call this. In particular, they should not use this to
+    * report the destination of a move that has not yet completed.
+    *
+    * It is up to the stage whether to report only after moves finish or also
+    * periodically during moves. But the reported position should eventually
+    * catch up to the actual position after the stage stops moving.
     */
    int OnXYStagePositionChanged(double xPos, double yPos)
    {

MMDevice/MMDevice.h

@@ -1628,18 +1628,22 @@ namespace MM {
 
       virtual int OnPropertiesChanged(const Device* caller) = 0;
       /**
-       * @brief Signal the UI that a property changed.
+       * @brief Inform the UI that a property changed.
        *
        * The Core will check if groups or pixel size changed as a consequence of
        * the change of this property and inform the UI.
        */
       virtual int OnPropertyChanged(const Device* caller, const char* propName, const char* propValue) = 0;
       /**
-       * @brief Signal the UI when the stage has reached a new position.
+       * @brief Inform the UI when a stage has changed its position.
+       *
+       * @see CDeviceBase::OnStagePositionChanged().
        */
       virtual int OnStagePositionChanged(const Device* caller, double pos) = 0;
       /**
-       * @brief Signal the UI when the XY stage has reached a new position.
+       * @brief Inform the UI when an XY stage has changed its position.
+       *
+       * @see CDeviceBase::OnXYStagePositionChanged()
        */
       virtual int OnXYStagePositionChanged(const Device* caller, double xPos, double yPos) = 0;
       /**