[Doc📝] Correct the module examples in the NameServer and Topic service adapters

Open Beginner friendly
#10,774 0 comments 0 reactions 0 assignees View on GitHub

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

Difficulty level/Easy documentation📝 good first issue help wanted rocketmq-tools crate rust
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 use paths resolve against the current module layout; neither
    references core::namesrv or core::topic::TopicService.
  • Both blocks keep the rust,ignore marker, 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from mxsm/rocketmq-rust

All issues in mxsm/rocketmq-rust

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.