Improve documentation #279
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
github-actions
bot
added
part:tests
llucax
added
type:enhancement
github-actions
bot
added
the
part:utilities
It is good to let users know where they can find the full documentation. Signed-off-by: Leandro Lucarella <[email protected]>
When functions don't take arguments and just trivially return something, there is no need to add a `Returns:` section just duplicating the function description. This is also true for properties, which should be documented as attributes. Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
We start all other documentation with capitals, so this way it is more homogeneous. Signed-off-by: Leandro Lucarella <[email protected]>
This style is more in line with the Google style guide. Signed-off-by: Leandro Lucarella <[email protected]>
We use "initialize" instead of "create" as this function doesn't really create anything, but just initializes an already created object. Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
Don't expose the implementation details, as this is intended to be consumed by users, not developers of the library. Where appropriate, move the details as code comments. Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
Receivers are not necessarily attached to a channel, as we already have some utility receivers that generates messages from other sources (like time, files or arbitrary events). For senders we don't have that yet, but there is also no reason to limit them to channels. Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
We are not really initializing anything here, just returning. Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
shsms
reviewed
Mar 5, 2024
Co-authored-by: daniel-zullo-frequenz <[email protected]> Co-authored-by: Sahas Subramanian <[email protected]> Signed-off-by: Leandro Lucarella <[email protected]>
|
Accepted all suggestions, thanks! |
|
Enabling auto-merge. |
shsms
approved these changes
Mar 6, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR includes a lot of small documentation improvements and fixes, trying to make the documentation more consistent and easier to read.
The commits are not particularly very well split, as many stuff was done in parallel and the splitting was done afterwards. Cleaning it up is very time demaning as it produces a lot of conflicts when rebasing.