use IPV6 loopback and documentation address in documentation over V4 by default

[2ndDerivative]

This defaults all documentation unrelated to specific IP versions to the current IPv6.

Related to issue #161832

I didn't touch any tests, as I'm pretty new and don't know much about the test infrastructure, but maybe it should be considered to run all the tests via the v6 loopback by default too.

Feel free to discuss and / or critique!

[rustbot]

Thanks for the pull request, and welcome! The Rust Project has assigned @joboet (or someone else) to review your changes, you should hear from them (or someone else) within the next two weeks.

Please see the contribution instructions and our LLM policy for more information.

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: @ChrisDenton, libs
• @ChrisDenton, libs expanded to 13 candidates
• Random selection from 6 candidates

[rustbot]

⚠️ Warning ⚠️

• There are issue links (such as #123) in the commit messages of the following commits.
  Please move them to the PR description, to avoid spamming the issues with references to the commit, and so this bot can automatically canonicalize them to avoid issues with subtree.
  • 917ee86

[joboet]

I really don't have an opinion here, networking isn't my domain (pun intended).

@rustbot reroll

[ChrisDenton]

I admit I'm struggling to feel strongly about this either way. This does feel like a policy decision though:

I think the Rust docs could be doing their part to normalize using [IPv6].

@rust-lang/libs does anybody have thoughts on this?

[NobodyXu]

How about keeping both versions side-by-side?

Many, for example me, aren't familiar with IPv6, having both will help me read the docs while bridge me into ipv6

Suggested change

	/// let mut stream = TcpStream::connect("[::1]:34254").unwrap();
	/// let mut stream = TcpStream::connect("127.0.0.1:34254").unwrap(); // ipv4
	/// let mut stream = TcpStream::connect("[::1]:34254").unwrap(); // ipv6

View changes since the review

[2ndDerivative]

would this be for every TcpStream::connect in the docs?
It's just the localhost address everywhere, but if the duplication is not a problem, sure! 👍🏻

[clarfonthey]

I like this idea, honestly. Since examples are also doctests, it makes sense to have "coverage" for these, I think.

[2ndDerivative]

would I just redeclare the stream/whateverit'snamed variable on every doctest or how would we do that? :-)

[clarfonthey]

I mean, it would depend on the test, but you're welcome to use your own judgement. It would be fine to define both but only "use" the v6 one imo

[2ndDerivative]

considering that adding both versions to every site where I changed it would be a lot of clutter, I suggest my newest change, which is adding an ipv4_x declaration to UdpSocket, TcpListener and TcpStream struct examples (meaning they show up on the top of the page in rustdoc)

[clarfonthey]

I can take this over since I did the previous one. r? clarfonthey

[tgross35]

I think the Rust docs could be doing their part to normalize using [IPv6].

@rust-lang/libs does anybody have thoughts on this?

Personally I'm -0.75 – users are way more likely to encounter IPv4 at the time being, and likely for the foreseeable future. I don't think I've ever seen documentation anywhere use [::1] rather than 127.0.0.1 when both are an option.