core: thread_flags: improve documentation#7536
Conversation
jnohlgard
left a comment
There was a problem hiding this comment.
Looks good, apart from the minor comment on the #ifdef
| * thread_flags_t flags = thread_flags_wait_any(0xFFFF); | ||
| * if (flags & THREAD_FLAG_MSG_WAITING) { | ||
| * msg_t msg; | ||
| * while (msg_try_receive(&msg) == 1) { |
There was a problem hiding this comment.
Other than the mask and using > 0 instead of == 1, I used this exact same loop for my event loop after writing #7533
There was a problem hiding this comment.
Hopefully we'll see this pattern in more places throughout the code base. ;)
core/include/thread_flags.h
Outdated
| * | ||
| * It is only reset through thread_flags_wait_*(), not by msg_receive(). | ||
| * Care must be taken to a) not lose message notifications and b) not block for | ||
| * messages but not thread flags. |
There was a problem hiding this comment.
difficult to understand what you mean by "not block messages but not thread flags."
There was a problem hiding this comment.
does "not block the thread for messages without blocking for flags" describe what you meant?
(bl rx vs. bl anyfl)
There was a problem hiding this comment.
I've completely reworded the not, is it clearer like this?
core/include/thread_flags.h
Outdated
| * @{ | ||
| */ | ||
|
|
||
| #if defined(MODULE_CORE_THREAD_FLAGS) || defined(DOXYGEN) |
There was a problem hiding this comment.
Should not be necessary to check for MODULE_CORE_THREAD_FLAGS since we are in the thread_flags.h header.
If you want to add additional checks you could do
#ifndev MODULE_CORE_THREAD_FLAGS
#error Missing USEMODULE += core_thread_flags
#endif
jnohlgard
left a comment
There was a problem hiding this comment.
Didn't mean to approve until the ifdef and wording was addressed
|
Hm, seems hidden in "outdated". I've changed the explanation you commented on, is it clearer like this? |
6165b5b to
ee94597
Compare
Previously, due to borked doxygen, the thread flags docs where half missing and half hidden in the thread module docs.
This PR creates a doxygen group for thread flags.
It also adds documentation for the THREAD_FLAG_MESSAGE_WAITING flag as implemented in #7533.