Unhelpful documentation - LL_InitTick

[Andrew Neil]

eg, in stm32l0xx_ll_utils.c

/**
  * @brief  This function configures the Cortex-M SysTick source of the time base.
  *   HCLKFrequency HCLK frequency in Hz (can be calculated thanks to RCC helper macro)
  * @note   When a RTOS is used, it is recommended to avoid changing the SysTick 
  *         configuration by calling this function, for a delay use rather osDelay RTOS service.
  *   Ticks Number of ticks
  * @retval None
  */

For the 'Ticks' parameter, "Number of ticks" is pretty meaningless - what is this "number"? What does it signify??

It should say, I think, "Number of ticks per second"

Thus LL_Init1msTick  does  LL_InitTick(HCLKFrequency, 1000U)  to give 1000 ticks per second - or 1 tick per millisecond.

[Andrew Neil]

Also, the documentation fails to mention that this function (and, thus, also LL_Init1msTick) disables the SysTick interrupt.

That's an important side-effect that really needs to be noted - as can be seen from the number of forum posts about it!

[Pavel A.]

>Also, the documentation fails to mention that this function (and, thus, also LL_Init1msTick) disables the SysTick interrupt.

>That's an important side-effect that really needs to be noted

+1 

https://github.com/STMicroelectronics/STM32CubeL0/blob/e416b1d1ede2719bc253eb8c8029e8e338567f2f/Drivers/STM32L0xx_HAL_Driver/Inc/stm32l0xx_ll_utils.h#L222

[Piranha]

And the "Number of ticks per second" can be called just "Tick frequency (Hz)". Those comments are written by the Captain Obvious, who doesn't even really understand the purpose of comments. And what is really the point of this function, when CMSIS has SysTick_Config(), which does almost the same and enables the interrupt?

By the way, don't get me wrong, but, if I would report this level of issues, there would be tens and hundreds of reports for every HAL/LL file. And that is one of the reasons I count HAL as a complete junk - fixing it or even reporting all of the issues actually requires more work than rewriting a decent driver library from the scratch.

[Andrew Neil]

Dear Chicken,

If you don't report the issues, you can hardly complain about there being issues.

Love,

Egg  xx.

[Imen.D]

Hello All,

Thank you for rising this up.

An internal ticket (ID 158538) is submitted in order to improve and avoid such issue.
PS: ID 158538 is an internal tracking number and is not accessible or usable by customers.

Imen

[Andrew Neil]

@Imen.D - thanks for that.

I hope this is a general ticket - not just specific to this particular function - as this type of poor-commenting is widespread.

In general, anything which involves a physical quantity should document what "units of measure" are used - in this case, "ticks per second".

And side-effects should be noted - another example here:

https://community.st.com/t5/embedded-software-mcus/hal-uart-transmit-with-single-wire-half-duplex/m-p/579685/highlight/true#M41692