Have a separate Constructors section in rustdoc for each type that shows functions that can be used to construct the type.

[05storm26]

When you are reading the documentation of a type sometimes it is difficult to find out, how one should actually create an instance of that type from the documentation.

Having a separate Constructors section for each type, would be useful to navigate the documentation and understand how a type should be created (by calling what method/function) in unknown/unfamiliar crates.

Related pr: #107926

[fmease]

I generally like this idea, several times I've found myself a bit lost looking for “constructors” when facing an unfamiliar API. Of course, this would need to be discussed with the rustdoc team first.

Note that there are some implementation concerns as well as design concerns.

Re. implementation, we would need to at least recurse into the return type of a function to be able to flag e.g., fn new(…) -> Result<Self, …> as a constructor. We might also need to recurse into all argument types to eliminate potential false positives like the contrived fn map(this: Self, mapper: impl FnOnce(…) -> …) -> Self which could come with a slight perf hit.

We might also want to consider extra to be a constructor in sth. like

impl<T> Wrapper<T> {
    fn new(x: T) -> Self { … }
    fn extra(x: T) -> Wrapper<(T, T)> { … }
}

so we should also look for Wrapper not just Self and we can ignore the generic arguments.

For (inlined) cross-crate re-exports, rustdoc has to work with lowered / desugared function signatures that no longer contain the Self type alias but the concrete type. It receives impl<T> Wrapper<T> { fn new() -> Wrapper<T> { … } } for example. So we need to accept Wrapper anyway, not just Self.

Luckily, rustdoc wouldn't need to perform full type unification while recursing into the return type to “find Self” if we want to accept Wrapper<…> in general. If we don't and only want to accept Wrapper<T> if the impl self type is Wrapper<T>, well, perf will be sad unless we impl fast rejection.

[LunarLambda]

I do agree that rustdoc should have some mechanism for pointing out "entry points" to a given type/API.

However, doing it heuristically has a lot of challenges. One not mentioned yet: what about types with multiple impl blocks? Particularly ones with different trait bounds. e.g.

impl<T: Default> MyType<T> {
   fn special_constructor() -> Self { ... }
}

Maybe it could be an attribute, #[doc(constructor)]? I'm not sure if older Rust/rustdoc versions error on unrecognized attributes (such that they could be added to a project without a MSRV bump). It would be more manual work, but it feels much more in line with other documentation-level modifiers like #[doc(inline)].