include: kernel: doc: add doxygen for k_sem

It can be confusing for users browsing the API docs to not find any
documentation for the k_sem structure. This commit adds doxygen
comments so that it now shows up.

Fixes zephyrproject-rtos/zephyr#90608.

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>