Azure / Azure/azure-sdk-for-rust
[Service Bus] Write the samples, the README, and the migration guide
- Dominant language
- Rust
- Stars
- 884
- Forks
- 365
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 112
Description
## Summary
The documentation does not match the crate. The README describes commands without saying where they run, the examples carry boilerplate, several doc comments describe behaviour the code does not have, and there is no migration guide.
## Motivation
Several open items on #2293 are documentation defects: the `az` usage in the README and the scripts, the boilerplate in the examples, the CONTRIBUTING file, and the padding in the doc comments. A stable release needs the documentation to be accurate, because the doc comments are the crates.io landing page.
The doc comments are actively misleading in places. `Receiver::receive_deferred_message` documents itself as a placeholder.
## Proposal
- Rewrite the README so each command states where it runs.
- Trim the examples to the one thing each demonstrates.
- Correct or delete the doc comments that describe unimplemented behaviour.
- Write a migration guide for callers coming from the community `azservicebus` crate.
- Remove or rewrite CONTRIBUTING.md.
## Dependencies
Blocked by:
- #4941 [Service Bus] Settle the public API shape before API review
Sub-issue of #4934.
Contributor guide
Research direction
Start by reviewing the API-shape dependency in #4941, then inspect the Service Bus README, examples, doc comments, and CONTRIBUTING.md mentioned in the issue. Compare the documentation with the current crate behavior and the community azservicebus crate. Done means the commands, examples, comments, migration guidance, and contribution instructions accurately match the stable API.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100