We depend upon builder patterns and iterators, or special purpose traits, for interface sugar in rust, ala default args, varadic generics, etc., so it's important we do builder patterns well. There are two rust doc features that should noticeably improve builder patterns:
Add capability to search method names by return type and possibly argument type, and to search type parameters by constraint. (edit: exists, see below)
Add annotation that places builder methods along side their return type or other arguments. As an example, we'd add Builder::go under some Related Functions section in the documentation for both Foo and Bar, along with Builder.
impl Builder {
/// Yo
fn go(self, foo: #[doc_at] Foo) -> #[doc_at] Bar { .. }
}
Maybe I haven't done enough builder patterns, but there are too many steps being skipped for me to follow how this is supposed to improve documentation. Could a small example of docs before/after this be made?
And for the connection: I much prefer to start the build as Type::build() -> TypeBuilder, not TypeBuilder::new() -> Type, which handles the connection of the builder type from the type being built.
I'd never noticed the tabs, so yes the search already exists. Thank you!
I suppose Type::build() works for actual builder patterns, but much more commonly we simply transform one type into another. We can simply explain the connection in the docs in English and manual hyperlinks of course.
Also, there are commonly Source -> Builder -> Goal transitions for which you'd need #[doc_at(Goal)] fn Source::goal_builder() -> Builder, but again English and manual hyperlinks handle well.
