RFC: link from struct docs to their constructors?

1

I was looking today at Fuse in std::iter - Rust and it reminded me of what I think is a general problem in Rust library docs:

This tells me there is a Fuse type with certain behavior. Great! How would I get one?
There's no link or guidance on the doc page, and in this case even using the search box for "fuse" is not helpful.

Unlike in Java/C++/etc, there's no constructor directly on the type, so it doesn't natrually occur on this page. In general it's probably not possible for the compiler to infer how you should construct the type.

It turns out I actually want to call Iterator.fuse().

After using Rust for a while you can guess this but for newcomers it's harder, and seems like a weak point in the generally great library docs.

So my suggestion is:

  • I'll put a PR to add a link in this particular case
  • and also suggest that the style guide for comments, should recommend adding such links in general

What do you think?

2

Yes please!

As I write docs, I try to do this. But because it needs to be done manually, I haven't gotten to eveything yet. I appreciate all PRs that increase these links, for sure.

1 Like
3

Thanks!

If those are basically reasonable I can do some more of these cleanups.

1 Like