Improve documentation #136
Conversation
llucax
commented
Jul 13, 2023
llucax
commented
- Add missing enum members documentation
- Make cross-linking more consistent
- Improve Timer documentation
github-actions
bot
added
part:synchronization
llucax
added
part:docs
Otherwise they are not rendered as part of the documentation at all. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
Add some more cross-linking and list all the available missed ticks policies. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
| @@ -18,7 +18,7 @@ | |||
|
|
|||
|
|
|||
| class Selected(Generic[_T]): | |||
| """A result of a [`select`][frequenz.channels.util.select] iteration. | |||
| """A result of a [`select()`][frequenz.channels.util.select] iteration. | |||
There was a problem hiding this comment.
So we always want to use () when referencing functions?
There was a problem hiding this comment.
In the rest of the file we always were referring to the select function as select(), so in this case I just wanted to have a consistent style.
src/frequenz/channels/util/_timer.py
Outdated
| @@ -270,36 +270,49 @@ def __repr__(self) -> str: | |||
| class Timer(Receiver[timedelta]): | |||
| """A timer receiver that triggers every `interval` time. | |||
|
|
|||
| The timer as microseconds resolution, so the `interval` must be at least | |||
| The timer as microseconds resolution, so the | |||
|
|
||
| This drift will likely never be `0`, because if there is a task that is | ||
| running when it should trigger, the timer will be delayed. In this case the | ||
| drift will be positive. A negative drift should be technically impossible, | ||
| as the timer uses `asyncio`s loop monotonic clock. | ||
| as the timer uses [`asyncio`][asyncio]s loop monotonic clock. |
There was a problem hiding this comment.
We seem to be using a mix of of () and [] here. Is [name][ref] different from (name)[ref]?
There was a problem hiding this comment.
[name](ref) is a regular, standard, markdown link, [name][ref] is a mkdocstrings extension to do code-crosslinking, so ref can only be a valid fully-qualified Python symbol.
There was a problem hiding this comment.
When configuring external "object inventories", this references can even point to external python packages, in this case asyncio will link to Python's official docs.
There was a problem hiding this comment.
BTW, (name)[ref] is incorrect, so if you spotted one is a bug, but I'm assuming is just a typo in your GitHub comment.
There was a problem hiding this comment.
This is one of my forever confusions in markdown syntax 😅 I can never remember the right order
src/frequenz/channels/util/_timer.py
Outdated
| the `missed_tick_policy`. Missing ticks might or might not trigger | ||
| a message and the drift could be accumulated or not depending on the | ||
| chosen policy. | ||
| If the timer is delayed too much, then the timer will behave according to the |
There was a problem hiding this comment.
If the timer is delayed too much, then
the timerit will
Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
