Improve library user documentation#685
Merged
allenporter merged 2 commits intoPython-roborock:mainfrom Dec 17, 2025
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves the documentation for first-time library users by clarifying device control patterns and making device commands and traits easier to discover. The changes focus on explaining the trait system, providing clearer quick-start examples, and reorganizing documentation to distinguish user-facing information from implementation details.
Key changes:
- Simplified the main README example to use email/code login instead of password login and added explanatory comments about the trait system
- Enhanced documentation for
CommandTraitandRoborockCommandwith usage examples and purpose clarification - Reorganized device documentation to separate usage guides from internal architecture details
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Updated quick start example to use code login, added trait usage explanations, and reorganized sections to clarify functionality |
| roborock/roborock_typing.py | Added docstring to RoborockCommand with usage example |
| roborock/devices/traits/v1/command.py | Expanded CommandTrait docstring with use cases and examples |
| roborock/devices/traits/v1/init.py | Restructured module docstring to separate user guide from implementation details, added submodule imports to __all__ |
| roborock/devices/traits/a01/init.py | Added comprehensive module docstring explaining A01 API usage |
| roborock/devices/traits/init.py | Added module-level documentation explaining trait submodules |
| roborock/devices/README.md | Reorganized headings to distinguish user-facing usage from internal architecture |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| The library interacts with devices through specific API properties based on the device protocol: | ||
|
|
||
| * **Standard Vacuums (V1 Protocol)**: Most robot vacuums use this. Interaction is done through `device.v1_properties`, which contains traits like `status`, `consumables`, and `maps`. Use the `command` trait for actions like starting or stopping cleaning. |
There was a problem hiding this comment.
Corrected spelling of 'vacuumes' to 'vacuums'.
Update the documentation to answer basic questions from a first time library user perspective. Given the deeper submodules, it may be harder to find so we add details so users can understand the bigger picture. Some existing documentation was focused more on design details for deeper implementation issues, so this clarifies what is lower level vs higher level.
Lash-L
approved these changes
Dec 16, 2025
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Update the documentation to answer basic questions from a first time library user perspective.
Focuses on two things:
(1) Clarifying the quick start example as to what is going on (drops password example, explains how traits work)
(2) Beef up documentation for device commands and traits making it easier to find.
Given the deeper submodules, it may be harder to find so we add details so users can understand the bigger picture. Some existing documentation was focused more on design details for deeper implementation issues, so this clarifies what is lower level vs higher level.
Fixes #684
Fixes #671