rust-lang / rust-lang/rust

[RustDoc] Could "Summary" still show the first line of docs?

Open
#160,922 4 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-rustdoc-ui C-enhancement T-rustdoc T-rustdoc-frontend
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

Image

Today it folds to just the signature

Image

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

Image

I think that might help the "summary" button

Image

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.