wishlist: Formatting a syn::Type for rustdoc

[chrysn]

In working on rustwasm/wasm-bindgen#2381, I'm trying to build documentation from additional information expressed as Rust syn data.

To give an illustrative example, generated documentation could look like

The returned type is &dyn Any, but in usual cases the type behind it will be Foo; you can get that back through let result: &Foo = result.downcast_ref()?;.

It's reasonably straightforward to get to that string representation -- format!("... {} ...", quote! { #syn_type }) does that. (There's some room for improvement around Option < Foo > or :: some_crate :: SomeType's lavish whitespace, but so what).

What I'd like to have, however, is rustdoc links to the indicated type. For simple cases like Foo it works to put them in angular brackets to produce the right links; for types like Option<Foo> or anything slice-ish, that fails.

Would it be within scope for syn to provide a method for Type like fn to_rustdoc(&self) -> String that produces output like this?

[`::some_crate::SomeType`] 
`[&mut `[`Foo`]`]`
[`Option`]`<`[`Foo`]`>`

(for the first example, the lavish whitespace needs to be gone or else rustdoc doesn't get it -- but it may be easier to use a more verbose form to get an equivalent link without having to remove all of that)

[dtolnay]

I would prefer not to build this into syn, but it could be suitable for you to build as an external crate.

[chrysn]

Fair enough, thanks for processing this quickly.

Right now the few cases I need are introduced in rustwasm/wasm-bindgen#2387 as a doc_prettyprint(&syn::Type) -> String function, which can be a starting point for any future work in an own crate.