[Doc📝] Correct the module examples in the NameServer and Topic service adapters
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 92/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- rust
- Domain
- documentation
Research direction
Start with the module doc comments in rocketmq-tools/rocketmq-admin/rocketmq-admin-core/src/client_adapter/services/namesrv.rs and topic.rs, and compare the imports with the caller in rocketmq-tools/rocketmq-admin/rocketmq-admin-cli/src/commands/topic/allocate_mq_sub_command.rs. Update only the two stale use paths while preserving the rust,ignore markers and surrounding prose. Run cargo fmt -p rocketmq-admin-core -- --check and cargo doc -p rocketmq-admin-core --features client-adapter --no-deps; done means both paths match the current module layout.
Written by the indexing model from the issue text.
Description
Issue Type
Incorrect/Outdated information
Location
File: rocketmq-tools/rocketmq-admin/rocketmq-admin-core/src/client_adapter/services/namesrv.rs lines 20-26
File: rocketmq-tools/rocketmq-admin/rocketmq-admin-core/src/client_adapter/services/topic.rs lines 20-26
Description
Both adapter modules open with an example whose use path cannot resolve, because
the example still points at the old core:: layout that the code has since
moved out of:
// src/client_adapter/services/namesrv.rs lines 22-26
//! ```rust,ignore
//! use rocketmq_admin_core::core::namesrv::NameServerService;
//!
//! let config = NameServerService::get_namesrv_config(&mut admin, addrs).await?;
//! ```
There is no core::namesrv module at all. Every service lives under
client_adapter::services, and src/core/mod.rs declares no namesrv entry.
// src/client_adapter/services/topic.rs lines 22-26
//! ```rust,ignore
//! use rocketmq_admin_core::core::topic::{TopicService, TopicClusterList};
//!
//! let clusters = TopicService::get_topic_cluster_list(&mut admin, "MyTopic").await?;
//! ```
There is a core::topic module, but it holds request and result models rather
than TopicService. The service and the list type are both re-exported from
client_adapter::services::topic (TopicService from operations,
TopicClusterList from types).
Because both blocks are marked rust,ignore, cargo doc and the doctest run
never compile them, which is why the stale paths have survived. A reader who
copies either example gets a compile error, and the module page is the first
thing a contributor sees for these two service families.
Suggested Fix
Point each example at the path that actually exists. Keep the rust,ignore
marker, because both examples need a live admin handle that a doctest cannot
construct.
//! ```rust,ignore
//! use rocketmq_admin_core::client_adapter::services::namesrv::NameServerService;
//!
//! let config = NameServerService::get_namesrv_config(&mut admin, addrs).await?;
//! ```
//! ```rust,ignore
//! use rocketmq_admin_core::client_adapter::services::topic::{TopicService, TopicClusterList};
//!
//! let clusters = TopicService::get_topic_cluster_list(&mut admin, "MyTopic").await?;
//! ```
Both names in the second example are re-exported by
src/client_adapter/services/topic.rs (lines 43-44), so the corrected path keeps
them together. For the exact spelling, check how a caller imports the service
today, for example
rocketmq-tools/rocketmq-admin/rocketmq-admin-cli/src/commands/topic/allocate_mq_sub_command.rs
line 22.
Verify each use path resolves before you finish:
cargo doc -p rocketmq-admin-core --features client-adapter --no-deps
Then confirm the path by searching the crate for the symbol you named:
rg "pub use .*TopicService" rocketmq-tools/rocketmq-admin/rocketmq-admin-core/src
Change only the two use lines and, if needed, the TopicClusterList mention.
Do not change the surrounding module prose, the function being called, or the
rust,ignore marker.
Willing to contribute?
- I can submit a PR for this
Acceptance Criteria
- Both
usepaths resolve against the current module layout; neither
referencescore::namesrvorcore::topic::TopicService. - Both blocks keep the
rust,ignoremarker, and the surrounding prose is
unchanged. - No source code changes outside the two module doc comments.
-
cargo doc -p rocketmq-admin-core --features client-adapter --no-deps
succeeds without new warnings.
Validation
Run from the repository root:
cargo fmt -p rocketmq-admin-core -- --check
cargo doc -p rocketmq-admin-core --features client-adapter --no-deps
cargo test -p rocketmq-admin-core --features client-adapter
The second command is what makes the doc pages render; because the examples are
rust,ignore, the doctest run will not catch a wrong path for you, so read the
rendered module page or re-derive the path from a real caller.
- Dominant language
- Rust
- Stars
- 1.5k
- Forks
- 264
- Avg merge
- 1h 34m
- Merged PRs (30d)
- 567
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from mxsm/rocketmq-rust
-
Difficulty level/Easy good first issue help wanted rocketmq-tools crate rust testing🧪
Difficulty 2/5 1-3 hours Newbie friendliness 94/100
mxsm/rocketmq-rust#10783 ·
-
bug🐛 Difficulty level/Easy good first issue help wanted rocketmq-tools crate rust
Difficulty 2/5 1-3 hours Newbie friendliness 92/100
mxsm/rocketmq-rust#10781 ·
-
Difficulty level/Easy enhancement✨ good first issue help wanted rocketmq-tui crate rust
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
mxsm/rocketmq-rust#10779 ·
-
Difficulty level/Easy good first issue help wanted rocketmq-tools crate rust testing🧪
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
mxsm/rocketmq-rust#10773 ·
-
Difficulty level/Easy good first issue help wanted refactor♻️ rocketmq-tools crate rust
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
mxsm/rocketmq-rust#10769 ·
All issues in mxsm/rocketmq-rust
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
kwakseongjae/auto-hwp#319 ·
-
area:cli bug filter-quality good first issue priority:medium
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
bevyengine/bevy#25861 ·
-
comp-datalake
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
ClickHouse/ClickHouse#121222 ·
-
enhancement remote
Difficulty 2/5 1-3 hours Newbie friendliness 68/100