docs: correct Arkade terminology and fix the docs.rs landing page - #268
Conversation
Seven of the ten published crate descriptions described Arkade as "Ark", "the Ark protocol", or an "Ark server". Those are the descriptions crates.io shows, so they are the most visible surface we have. Arkade is a distinct system, and other teams ship unrelated protocols under the "Ark" name, so the old wording invited a conflation we do not want. Rewrite the descriptions and the crate READMEs to use current terms: the operator instead of "Ark/Arkade server", virtual output instead of VTXO, batch swap instead of round, and onchain instead of "on-chain". Also fix the ark-rs landing page on docs.rs. It rendered ark_core alone, because ark_client and ark_grpc sit behind non-default features and the crate carried no docs.rs metadata and no crate-level documentation. Add both, register cfg(docsrs) with the workspace check-cfg list, and give the root README a docs.rs badge and a direct link instead of a search query. Verified with cargo check and cargo doc on stable, and with RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features: all three re-exports now render, with feature badges on client and grpc. Refs #216, #205
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (15)
Included review availability: Your plan includes up to 1 review per rolling hour; 0 remain after this review. WalkthroughThe PR aligns Arkade terminology across workspace metadata and READMEs. It adds crate badges and updated documentation links, and configures ChangesArkade SDK documentation alignment
Estimated code review effort: 2 (Simple) | ~10 minutes Merge Risk: ⚪ Minimal · up to This PR updates documentation terminology and improves the ark-rs documentation landing page without changing application logic; no actionable merge-blocking risk remains after normal checks and review. Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
arkana-ai-bot
left a comment
arkana-ai-bot
left a comment
There was a problem hiding this comment.
Documentation and metadata only — no protocol logic, signing paths, VTXO handling, or public Rust symbols are touched. No security or protocol concerns.
Nit 1 — minor terminology drift in ark-delegator
ark-delegator/Cargo.toml description is changed to "Arkade delegate services", but ark-delegator/README.md (line 3) and the root README.md (crates table) still read "Arkade delegator services". The two terms mean different things in a delegation protocol. Whichever form is canonical, the three surfaces should agree.
Nit 2 — hardcoded version in crate-level doc
ark-rs/src/lib.rs lines ~20-21 (the # Install snippet):
ark-rs = { version = "0.10.1", features = ["client", "grpc"] }Pinning an exact version in a doc comment will become stale on every release. Consider "0.10" (semver-compat range) or a MAJOR.MINOR placeholder, which is the convention most Rust crates use for install snippets.
Danger warning ("Source changed with no test changes") is a false positive here — there is nothing runtime-behavioural to test in a docs/metadata pass.
The cfg_attr(docsrs, feature(doc_cfg)) / doc(cfg(feature = "…")) pattern is correct and is only activated under the nightly docs.rs build; stable consumers are unaffected. The check-cfg extension to add cfg(docsrs) at the workspace level is the right fix for the unexpected_cfgs lint. No objection to merging once the nits above are decided on.
|
The Verified: with #272's change applied, The |
3 participants
Two related documentation fixes. No application logic is touched — only crate metadata, READMEs, and
ark-rs/src/lib.rsre-export attributes.1. Terminology in the published crate descriptions
Seven of the ten published crates described Arkade as "Ark", "the Ark protocol", or an "Ark server":
ark-rson-chainandoff-chaintransactions via the Ark protocolark-clientark-grpcark-restark-coreark-delegatorark-bdk-walletark-clienton-chain wallet traits…ark-clientonchain wallet traits…ark-introspector-clientThese are the strings crates.io renders on each crate page, so they are the most widely seen prose in the repo. Arkade is a distinct system, and unrelated protocols ship under the "Ark" name, so the old wording invited exactly the conflation we want to avoid.
The same pass through
ark-client/README.md,ark-grpc/README.md,ark-rest/README.md,ark-bdk-wallet/README.md, and the root README replaces:Crate names, module paths, and every code identifier are unchanged. Renaming an exported symbol is a breaking change and is out of scope here.
2. The docs.rs landing page for
ark-rshttps://docs.rs/ark-rs/latest/ark_rs/ served a page whose only visible re-export was
ark_core.ark_clientandark_grpcsit behind non-default features, and the crate had no docs.rs metadata and no crate-level documentation, so the landing page told a reader almost nothing.This adds:
//!crate doc onark-rs/src/lib.rs: what the crate is for, a table mapping each module to its crate and feature, an install snippet, the forwarded features, and a pointer toark_client::Clientas the place to start.[package.metadata.docs.rs] all-features = trueplusrustdoc-args = ["--cfg", "docsrs"].#[cfg_attr(docsrs, doc(cfg(feature = "…")))]on theclientandgrpcre-exports, so the rendered page shows which feature gates each one.cfg(docsrs)registered in the workspacecheck-cfglist, so the new attribute does not trip theunexpected_cfgslint.docs.rs/ark-rslink replacing adocs.rs/releases/search?query=ark-rsquery.Verification
Inspecting the generated
ark_rs/index.htmlfrom the nightly build: all three re-exports (ark_core,ark_client,ark_grpc) render, and the feature badges resolve toclientandgrpc. Thedoc_cfgattribute is gated behindcfg(docsrs), so stable builds are unaffected.Relation to open issues
Closes most of #216 — crate doc, docs.rs metadata,
doc(cfg)annotations, README badge and link. The per-crate READMEs and the root crate list it also asked for had already landed.Also covers the last two unchecked non-coverage items on #205. What remains on both issues is rustdoc coverage across all public items, which is a separate and much larger effort worth its own issue.
Summary by CodeRabbit
Documentation
Improvements