Clarify Path::extension() semantics in docs abstract

[mqudsi]

State up-front and center what shape the returned extension will have, without making the user read through the description and examples.

This is a doc-only change. There are no changes to the API contract and the clarification is in line with what was already stated/promised in the existing doc text - just clarified, summarized, and served bright and early.

Rationale: Various frameworks and libraries for different platforms have their different conventions as to whether an "extension" is ".ext" or just "ext" and anyone that's had to deal with this ambiguity in the past is always double- or triple-checking to make sure the function call returns an extension that matches the expected semantics. Offer the answer to this important question right off the bat instead of making them dig to find it.

@rustbot label +A-docs

[rustbot]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[rust-highfive]

r? @thomcc

(rust-highfive has picked a reviewer for you, use r? to override)

[thomcc]

@bors r+ rollup

[bors]

📌 Commit c291d2a has been approved by thomcc

It is now in the queue for this repository.

[mqudsi]

Thanks, @thomcc.

[the8472]

Offer the answer to this important question right off the bat instead of making them dig to find it.

But there are other important questions. E.g. is .tar.gz the extension or just .gz? What makes this question more important than others?

[thomcc]

I'd approve additional clarifications like that, but I don't think they block this one.

[mqudsi]

@the8472 pedantically, whether or not an "extension" is ".ext" or "ext" affects each and every file and each and every extension while "tar.gz" or "gz" affects only cases where you are matching against a compound extension or a file with potentially a compound extension. Developers that get the first one wrong will get the wrong answer every single time, while developers not taking into account the relatively fringe case of compound extensions will have broken code some fraction of the time.

Less pedantically and on a more personal/subjective level, as best as I can recollect, every api I've worked with treated the extension of "foo.tar.gz" to be ".gz" (or "gz" as the case may be) so it's not a question that I personally found as pressing to answer (it's also IMHO the only logical result because any file may have a dot/period in the non-ext part of its name/path).

[the8472]

People have at least asked for such methods, e.g. in #86319 so if they existed then we'd have to disambiguate the difference which I think would be more important than mentioning whether the dot is included or not.