Azure / Azure/azure-sdk-for-rust

[Service Bus] Write the samples, the README, and the migration guide

Open
#4,959 0 comments 1 reaction 0 assignees View on GitHub
Client Docs Service Bus
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.