system_timer.h: Update docs
system_timer.h: Update docs

Clarify behavior of the ticks argument to z_clock_set_timeout() and
add an important note about expected behavior in SMP environments.

Signed-off-by: Andy Ross <c70f9a6bf6ee0cd69c8af4ce5e6b131945769315@intel.com>

nashif/zephyr,punitvara/zephyr,galak/zephyr,ldts/zephyr,ldts/zephyr,punitvara/zephyr,finikorg/zephyr,Vudentz/zephyr,nashif/zephyr,explora26/zephyr,GiulianoFranchetto/zephyr,zephyrproject-rtos/zephyr,finikorg/zephyr,galak/zephyr,nashif/zephyr,GiulianoFranchetto/zephyr,punitvara/zephyr,galak/zephyr,Vudentz/zephyr,punitvara/zephyr,galak/zephyr,explora26/zephyr,Vudentz/zephyr,GiulianoFranchetto/zephyr,Vudentz/zephyr,explora26/zephyr,finikorg/zephyr,GiulianoFranchetto/zephyr,finikorg/zephyr,zephyrproject-rtos/zephyr,zephyrproject-rtos/zephyr,zephyrproject-rtos/zephyr,ldts/zephyr,punitvara/zephyr,Vudentz/zephyr,zephyrproject-rtos/zephyr,explora26/zephyr,galak/zephyr,GiulianoFranchetto/zephyr,ldts/zephyr,ldts/zephyr,explora26/zephyr,nashif/zephyr,Vudentz/zephyr,nashif/zephyr,finikorg/zephyr