-
Notifications
You must be signed in to change notification settings - Fork 12.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Rustdoc: Visual indentation of function return type looks funky #40687
Comments
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 |
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. |
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: Since you're already on it, try to catch up the format RFC. :) |
I'd say go for it, the currently agreed upon style is described out here, or in this example. |
…cxv,GuillaumeGomez rustdoc: update formatting of fn signatures and where clauses to match style rfcs Recent updates to style RFCs ([where clauses](rust-lang/style-team#38), [function definitions](rust-lang/style-team#39)) changed the "canonical" style for these items, so this is a rustdoc update to make it emit that style where necessary. This is mainly a conversion from visual indent to block indent, which helps out in situations where there was excessive indent causing lines to wrap regardless. Samples: ![std::iter::IntoIterator](https://cloud.githubusercontent.com/assets/5217170/24712947/e586604c-19e9-11e7-87ae-4fe64d689dc3.png) ![excerpt from std::iter::Iterator](https://cloud.githubusercontent.com/assets/5217170/24713209/91e65112-19ea-11e7-9ff8-d4cf6b31aae1.png) ![std::iter::FromIterator](https://cloud.githubusercontent.com/assets/5217170/24713138/59f36114-19ea-11e7-9dbb-5f5ba7126e2e.png) ![std::cmp::min](https://cloud.githubusercontent.com/assets/5217170/24713038/1bab88b4-19ea-11e7-935d-defed5648de4.png) ![some trait impls on std::collections::HashMap](https://cloud.githubusercontent.com/assets/5217170/24713251/b7ef69e8-19ea-11e7-94a7-e01fbf89fa31.png) ![`fn extract_code_blocks`, an example given in #40687](https://cloud.githubusercontent.com/assets/5217170/24713159/672717cc-19ea-11e7-9acb-6ac278b90339.png) ![excerpt from itertools::Itertools](https://cloud.githubusercontent.com/assets/5217170/24713323/f06716ea-19ea-11e7-94cc-6ef68d9980ec.png) fixes #41025 and #40687 r? @rust-lang/docs
I have a function with this signature:
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:
alternatively,
or even (introducing where clauses):
The text was updated successfully, but these errors were encountered: