Hints about primitive and standard type's functions implemented in another crates in std docs

documentation
1

There are pros and cons of itertools (and other helper crates that adds more features to standard and primitive types) of being included in std.

But can there be a middle ground between “on board - in std” and “thrown away into ocean of crates.io”? Maybe documentation can contain explicit names of functions like interleave? The content may suggest varied level of endorsement:

  • [minimal] Explicit statement that there is no interleave function for Iterator. So user could stop searching the page again trying to fix a typo in search query or try synonyms or some.
  • [small] Advice to search the interleave function somewhere on crates.io.
  • [normal] Advice to use itertools
  • [maximal] Short doc snippet of itertools's interleave with the statement that this function is stable, verified by libstd’s developers and is encouraged to be used.

It’s no joy trying to find a function and not being sure if I am searching wrong or there is just no such thing. Things that are typically searched for may have explicit “landing pads” that terminates the search.

This way a feature that is not in std may still have exposure as if it were in std.

2

I’m assuming that this is not specific to itertools but is general to other crates as well.

For the searchability part, I think a good search-via-type/function-name mechanism that is cross-crate on docs.rs, similar to what is provided by hayoo and hoogle would be very helpful.

In the far future, RLS could perhaps start searching the ecosystem for a function with the name you are looking for. And rustc could do the same in error-fixing-suggestions if enabled. Tho perhaps this is going too far.

Other than that, a uniform redirection+blessing-approach sounds nice, how about?:

trait Iterator {
    ...
    #![search_advice(does_not_exist, interleave)]

    #![search_advice(on_crates_io, interleave)]

    #![search_advice(in_crate, itertools::Itertools::interleave,
        https://docs.rs/itertools/0.7.4/itertools/trait.Itertools.html#method.interleave)]

    #![search_advice(in_crate, itertools::Itertools::interleave,
        https://docs.rs/itertools/0.7.4/itertools/trait.Itertools.html#method.interleave,
        Some random comment on why this is stable, great and verified)]
}
1 Like
3

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.