This issue inspired by a private conversation where people were discussing whether method documentation should have different rules from module-level functions since they don't have the same rustdoc summary list that uses that first sentence. Clippy's too_long_first_doc_paragraph lint also specifically talks about "in the module page".
But maybe rustdoc should be taking advantage of the short-first-paragraph in some way for methods too?
As one possible idea, maybe folding the methods could still show the first line?
Take https://doc.rust-lang.org/std/primitive.u32.html#method.carrying_mul_add, for example, which has a long comment
Today it folds to just the signature
But maybe it would make sense to fold also showing the same first-sentence that would be shown in a module table, perhaps something like
I think that might help the "summary" button
since if I just want a list of names there's the sidebar, and signature + 1st-doc-line might be a useful middle ground between "everything" and "just the names".
(Spitballing: I don't know if it's worth putting a separate block into the HTML to repeat the first sentence. Maybe overflow: hidden with a 1-line height when collapsed, or something? And removing the extra margin? I'm pretty terrible at HTML+CSS, so you'll probably come up with something better than I can.)
This issue inspired by a private conversation where people were discussing whether method documentation should have different rules from module-level functions since they don't have the same rustdoc summary list that uses that first sentence. Clippy's too_long_first_doc_paragraph lint also specifically talks about "in the module page".
But maybe rustdoc should be taking advantage of the short-first-paragraph in some way for methods too?
As one possible idea, maybe folding the methods could still show the first line?
Take https://doc.rust-lang.org/std/primitive.u32.html#method.carrying_mul_add, for example, which has a long comment
Today it folds to just the signature
But maybe it would make sense to fold also showing the same first-sentence that would be shown in a module table, perhaps something like
I think that might help the "summary" button
since if I just want a list of names there's the sidebar, and signature + 1st-doc-line might be a useful middle ground between "everything" and "just the names".
(Spitballing: I don't know if it's worth putting a separate block into the HTML to repeat the first sentence. Maybe
overflow: hiddenwith a 1-line height when collapsed, or something? And removing the extra margin? I'm pretty terrible at HTML+CSS, so you'll probably come up with something better than I can.)