drivers: can: clarify the meaning of minimum/maximum supported bitrates

Clarify the meaning of of minimum/maximum supported bitrates in the CAN
controller driver API.

Signed-off-by: Henrik Brix Andersen <[email protected]>

Author: henrikbrixandersen

include/zephyr/drivers/can.h

@@ -835,8 +835,16 @@ static inline int z_impl_can_get_core_clock(const struct device *dev, uint32_t *
  *
  * Get the minimum supported bitrate for the CAN controller/transceiver combination.
  *
+ * @note The minimum bitrate represents limitations of the CAN controller/transceiver
+ * combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock
+ * rate and the minimum CAN timing limits.
+ *
+ * @see can_get_core_clock()
+ * @see can_get_timing_min()
+ * @see can_get_timing_data_min()
+ *
  * @param dev Pointer to the device structure for the driver instance.
- * @return Minimum supported bitrate in bits/s
+ * @return Minimum supported bitrate in bits/s. A value of 0 means the lower limit is unspecified.
  */
 __syscall uint32_t can_get_bitrate_min(const struct device *dev);
 
@@ -854,8 +862,17 @@ static inline uint32_t z_impl_can_get_bitrate_min(const struct device *dev)
  *
  * @deprecated Use @a can_get_bitrate_min() instead.
  *
+ * @note The minimum bitrate represents limitations of the CAN controller/transceiver
+ * combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock
+ * rate and the minimum CAN timing limits.
+ *
+ * @see can_get_core_clock()
+ * @see can_get_timing_min()
+ * @see can_get_timing_data_min()
+ *
  * @param dev Pointer to the device structure for the driver instance.
- * @param[out] min_bitrate Minimum supported bitrate in bits/s
+ * @param[out] min_bitrate Minimum supported bitrate in bits/s. A value of 0 means the lower limit
+ *                         is unspecified.
  *
  * @retval -EIO General input/output error.
  * @retval -ENOSYS If this function is not implemented by the driver.
@@ -872,6 +889,14 @@ __deprecated static inline int can_get_min_bitrate(const struct device *dev, uin
  *
  * Get the maximum supported bitrate for the CAN controller/transceiver combination.
  *
+ * @note The maximum bitrate represents limitations of the CAN controller/transceiver
+ * combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock
+ * rate and the maximum CAN timing limits.
+ *
+ * @see can_get_core_clock()
+ * @see can_get_timing_max()
+ * @see can_get_timing_data_max()
+ *
  * @param dev Pointer to the device structure for the driver instance.
  * @return Maximum supported bitrate in bits/s
  */
@@ -891,6 +916,14 @@ static inline uint32_t z_impl_can_get_bitrate_max(const struct device *dev)
  *
  * @deprecated Use @a can_get_bitrate_max() instead.
  *
+ * @note The maximum bitrate represents limitations of the CAN controller/transceiver
+ * combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock
+ * rate and the maximum CAN timing limits.
+ *
+ * @see can_get_core_clock()
+ * @see can_get_timing_max()
+ * @see can_get_timing_data_max()
+ *
  * @param dev Pointer to the device structure for the driver instance.
  * @param[out] max_bitrate Maximum supported bitrate in bits/s
  *