[RustDoc] Could "Summary" still show the first line of docs?
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 119k
- Forks
- 16.1k
- PR merge metrics
- PR metrics pending
Description
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.)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the rustdoc-rendered u32 carrying_mul_add method page and the Summary control described in the issue. Compare the expanded and collapsed method presentation, then determine and document a consistent way for collapsed methods to expose their first documentation sentence while preserving the existing summary behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100