googleapis / googleapis/google-cloud-rust

Add tool to audit documentation for duplicate/redundant descriptions caused by re-exports

Open
#5,481 1 comment 0 reactions 1 assignee Claimed by @suzmue View on GitHub
type: feature request type: process
Dominant language
Rust
Stars
955
Forks
144
Avg merge
1d 5h
Merged PRs (30d)
279

Description

While working on documentation warnings in the storage crate, we discovered a behavior in rustdoc that can lead to redundant or confusing documentation when items are re-exported with new doc comments.

When a public re-export (like pub use ...) has its own doc comment, rustdoc concatenates it with the doc comment from the source item in the rendered documentation. If both contain descriptive text, they combine in the module list, often looking like two unrelated sentences.

We have also previously seen this behavior in API reviews when working on Pub/Sub. The documentation for BasePublisher had double of the same documentation, since we defined it in two places

We could use a tool to check for this and run it in our CI to help us catch this issue. There should be an escape hatch if we are intentionally doing this, though we may want to be more strict when it comes to types defined within our own crates, and only allow the documentation to come from a single place.

Started implementing this on a branch: https://github.com/suzmue/google-cloud-rust/blob/c358c03914adf3baa44f0396948e1954fe347f1d/tools/doc-dup-checker/src/main.rs#L22

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.