Skip to content

Tricky rustdoc warning messages when using include_str #118549

Closed
@shnewto

Description

@shnewto

I wanted to share something that made me scratch my head in case it makes anyone else scratch their head too. But I'm not sure I'd call this a bug or an error. It just stumped me for a minute and thought I'd bring it up and let y'all decide whether it's either.

(and in case it helps set the tone of my comments below, I love rustdoc, I love the include_str feature, and I'm grateful for all the work and care that goes into it all!)

When using #![doc = include_str!("../README.md")], if the contents of README.md generate warnings, it's not immediately clear what's to be done.

Here's a screenshot of output from cargo doc when the badge urls in my README.md were bare rather than atomatic urls.

rustdoc-warning

I guess my misguided thought process went something like, "hmm it must be thinking about the path ../README.md as a url?" and I think that derailed me really seeing that the urls provided in the output were the root of the issue and not just "helpful" examples.

...I don't really know what "better" would look like either, I can imagine myself being similarly confused if the terminal output showed me lines from a .md file 😅

Thanks for taking a look! And if you decide that I'm just too easily confused, please feel free to close this issue 😄

Metadata

Metadata

Assignees

Labels

A-diagnosticsArea: Messages for errors, warnings, and lintsA-lintsArea: Lints (warnings about flaws in source code) such as unused_mut.D-incorrectDiagnostics: A diagnostic that is giving misleading or incorrect information.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions