docs: Fixed multi_usrp docstring for get_master_clock_rate

1 files changed, 14 insertions, 7 deletions

diff --git a/host/include/uhd/usrp/multi_usrp.hpp b/host/include/uhd/usrp/multi_usrp.hpp
index 8c50178eb..f0029c1af 100644
--- a/host/include/uhd/usrp/multi_usrp.hpp
+++ b/host/include/uhd/usrp/multi_usrp.hpp
@@ -160,15 +160,22 @@ public:
 
     /*!
      * Set the master clock rate.
-     * This controls the rate of the clock that feeds the FPGA DSP.
-     * On some devices, this re-tunes the clock to the specified rate.
-     * If the specified rate is not available, this method will throw.
-     * On other devices, this method notifies the software of the rate,
-     * but requires the the user has made the necessary hardware change.
+     *
+     * What exactly this changes is device-dependent, but it will always
+     * affect the rate at which the ADC/DAC is running.
+     *
+     * Like tuning receive or transmit frequencies, this call will do a best
+     * effort to change the master clock rate. The device will coerce to the
+     * closest clock rate available, and on many devices won't actually change
+     * anything at all. Call get_master_clock_rate() to see which rate was
+     * actually applied.
+     *
+     * Note that changing this value during streaming is not recommended and
+     * can have random side effects.
      *
      * If the device has an 'auto clock rate' setting (e.g. B200, see also
-     * \ref b200_auto_mcr), this will get disabled and the clock rate will be
-     * fixed to \p rate.
+     * \ref b200_auto_mcr), calling this function will disable the automatic
+     * clock rate selection, and the clock rate will be fixed to \p rate.
      *
      * \param rate the new master clock rate in Hz
      * \param mboard the motherboard index 0 to M-1