Rustdoc: Visual indentation of function return type looks funky

[killercup]

I have a function with this signature:

pub fn extract_code_blocks<'md, I: Iterator<Item=Event<'md>>>(md_events: I) -> Result<Vec<CodeBlock>, Error>

So far so good. In the original source, it's all on one line, but Rustdoc uses quite a large font, so it makes sense to split it up. The problem is with the way it tries to reformat the signature, i.e., by putting the return type directly beneath the opening bracket of the arguments:

And while it doesn't look great on a wide screen, resizing the window makes it look just broken:

To get a good idea how to format functions it might be wise to check the discussion of the fmt team in rust-lang/style-team#39, but I don't think Rustdoc has the same constraints as rustfmt.

In particular, I would render the function signature quoted above as:

pub fn extract_code_blocks<'md, I: Iterator<Item=Event<'md>>>(
    md_events: I,
) -> Result<Vec<CodeBlock>, Error>

alternatively,

pub fn extract_code_blocks<'md, I: Iterator<Item=Event<'md>>>
    (md_events: I)
    -> Result<Vec<CodeBlock>, Error>

or even (introducing where clauses):

pub fn extract_code_blocks<'md, I>(md_events: I)
    -> Result<Vec<CodeBlock>, Error>
    where I: Iterator<Item=Event<'md>>

[GuillaumeGomez]

pub fn extract_code_blocks<'md, I: Iterator<Item=Event<'md>>>(
    md_events: I)
    -> Result<Vec<CodeBlock>, Error>

I propose this one (because I don't like when ) starts a new line).

[QuietMisdreavus]

After some discussion in #rust-docs, I noticed that the first style mentioned is pretty close to how the fmt-rfcs issue about function signatures wound up. It's also suspiciously close to my initial implementation when I first put that indentation code in. I'll see about sketching out this change.

[retep998]

That first alternative is in fact block indentation which is what that rustfmt RFC agreed on. As a result, rustdoc should reflect that decision and switch to block indentation for all function definitions in generated documentation.

[QuietMisdreavus]

Got an initial implementation sketched out. Should I adjust where clause indentation at the same time, since those guidelines have changed since that implementation?

[GuillaumeGomez]

@QuietMisdreavus: Since you're already on it, try to catch up the format RFC. :)

[killercup]

Should I adjust where clause indentation at the same time, since those guidelines have changed since that implementation?

I'd say go for it, the currently agreed upon style is described out here, or in this example.

[Mark-Simulacrum]

I believe this is fixed today.