HardwareTimer: update function header and parameter description

Fixes #1430

Signed-off-by: Alexandre Bourdiol <alexandre.bourdiol@st.com>

Author: ABOSTM

cores/arduino/HardwareTimer.cpp

@@ -826,7 +826,7 @@ void HardwareTimer::setCaptureCompare(uint32_t channel, uint32_t compare, TimerC
   *           TICK_FORMAT:     return value is the number of tick for Capture/Compare value
   *           MICROSEC_FORMAT: return value is the number of microsecondes for Capture/Compare value
   *           HERTZ_FORMAT:    return value is the frequency in hertz for Capture/Compare value
-  * @retval None
+  * @retval Capture/Compare value
   */
 uint32_t HardwareTimer::getCaptureCompare(uint32_t channel,  TimerCompareFormat_t format)
 {
@@ -880,10 +880,8 @@ uint32_t HardwareTimer::getCaptureCompare(uint32_t channel,  TimerCompareFormat_
   * @param  pin: Arduino pin number, ex D1, 1 or PA1
   * @param  frequency: PWM frequency expessed in hertz
   * @param  dutycycle: PWM dutycycle expressed in percentage
-  * @param  format of return value. If ommited default format is Tick
-  *           TICK_FORMAT:     return value is the number of tick for Capture/Compare value
-  *           MICROSEC_FORMAT: return value is the number of microsecondes for Capture/Compare value
-  *           HERTZ_FORMAT:    return value is the frequency in hertz for Capture/Compare value
+  * @param  PeriodCallback: timer period callback (timer rollover upon udate event)
+  * @param  CompareCallback: timer compare callback
   * @retval None
   */
 void HardwareTimer::setPWM(uint32_t channel, uint32_t pin, uint32_t frequency, uint32_t dutycycle, callback_function_t PeriodCallback, callback_function_t CompareCallback)
@@ -897,10 +895,8 @@ void HardwareTimer::setPWM(uint32_t channel, uint32_t pin, uint32_t frequency, u
   * @param  pin: pin name, ex PB_0
   * @param  frequency: PWM frequency expessed in hertz
   * @param  dutycycle: PWM dutycycle expressed in percentage
-  * @param  format of return value. If ommited default format is Tick
-  *           TICK_FORMAT:     return value is the number of tick for Capture/Compare value
-  *           MICROSEC_FORMAT: return value is the number of microsecondes for Capture/Compare value
-  *           HERTZ_FORMAT:    return value is the frequency in hertz for Capture/Compare value
+  * @param  PeriodCallback: timer period callback (timer rollover upon udate event)
+  * @param  CompareCallback: timer compare callback
   * @retval None
   */
 void HardwareTimer::setPWM(uint32_t channel, PinName pin, uint32_t frequency, uint32_t dutycycle, callback_function_t PeriodCallback, callback_function_t CompareCallback)
@@ -1142,7 +1138,7 @@ HardwareTimer::~HardwareTimer()
 /**
   * @brief  return timer index from timer handle
   * @param  htim : one of the defined timer
-  * @retval None
+  * @retval timer index
   */
 timer_index_t get_timer_index(TIM_TypeDef *instance)
 {
@@ -1263,7 +1259,7 @@ timer_index_t get_timer_index(TIM_TypeDef *instance)
 
 /**
   * @brief  This function return the timer clock frequency.
-  * @param  tim: timer instance
+  * @param  None
   * @retval frequency in Hz
   */
 uint32_t HardwareTimer::getTimerClkFreq()
@@ -1395,7 +1391,7 @@ uint32_t HardwareTimer::getTimerClkFreq()
 
 /**
   * @brief  This function will reset the timer
-  * @param  obj : Hardware timer instance ex: Timer6, ...
+  * @param  None
   * @retval None
   */
 void HardwareTimer::timerHandleDeinit()