Don't include headings in search summary

[jsha]

A search for "add" includes these results:

std::time::Instant::add    Panics
std::time::SystemTime::add    Panics

This gives the impression that those functions unconditionally panic, which they don't. I think the fix here is that the summary for search purposes should only be taken from text that appears before the first heading in the docblock. If there is no text before a heading, there should be no summary.

[camelid]

I agree; this has bothered me for a long time.

[camelid]

There are advantages and disadvantages to the current behavior and the behavior suggested here. For now, I'm unassigning myself since I won't have time to investigate alternatives.

[lolbinarycat]

triage: no change

[RodBurman]

Simplest fix change "Panics" to "Can Panic" or "May Panic"?

[lolbinarycat]

the problem is thus:

• rustdoc uses the first line of the documention as a summary
• these functions have no "explanation" portion, since their names are self-documenting
• they do however, have a "Panics" section which explains under which circumstances the function panics
• rustdoc thus takes the name of this section, strips the heading property, and uses it as a summary

[RodBurman]

My suggestion is to change the wording of that first line rather than the construction process of the documentation (which is a lot more work). Currently "Panics" is a short form for/has the meaning "Will panic when", but "Panics" gives the wrong impression when seen out of context in the search screen, thus:

trait              std::ops::Add                  The addition operator +.
trait method       std::ops::Add::add             Performs the + operation.
method             pointer::add                   Adds an unsigned offset to a pointer.
method             std::ptr::NonNull::add         Adds an offset to a pointer (convenience for …
method             std::time::Instant::add        Panics
method             std::time::SystemTime::add     Panics
method             f16::add
etc.

Whereas the documentation immediately gives context, thus:

fn add(self, other: Duration) -> Instant
Panics
This function may panic if the resulting point in time cannot be represented by the underlying data structure. See Instant::checked_add for a version without panic

Considering both, I am not sure "Panics" adds to the documentation but certainly may panic :) the unwary in the search, so rather than search for a different wording it may be best to just remove it? Alternatively change to something akin to the first line of the search so "The addition operator + which may panic.".

[camelid]

Another solution could be to add a line of documentation to those functions, despite their straightforward names. Your proposal could also work, but "Panics" is also a very well established convention in the library docs (and likely third-party docs too), so it would be nice to avoid changing that just for this. For example, there are 403 occurrences of a "Panics" heading in the stdlib. Either way, both of these would be for T-libs to consider, if we don't plan to change rustdoc's search summary logic.