How use_sim_time works?

edit

The documentation you link to does describe how it works. As stated in section 2, when the parameter use_sim_time is true, the ROS API used to get times (e.g. ros::Time time = ros::Time::now()) will retrieve time data from the /clock topic rather than using the system clock. If you have something publishing time values to that topic (such as rosbag or Gazebo) then this means any nodes using the ROS time APIs will act as though the time is what /clock says it is.

If you turn use_sim_time off then any time values published to /clock will be ignored, meaning that any data published by rosbag will have time stamps that are different (probably massively different) from the current system time, and so data processing nodes may ignore that data as being out of date.

The /clock topic is useful for more than just playing back older data. If you write your nodes to process data based on times from the ros::Time API and not from its own loop, then you can effectively slow down and even stop the functioning of your system by controlling the /clock topic. This is particularly useful when working with simulations.