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
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