add a disclaimer to the net::ip methods that are susceptible to change #60239
Comments
jonas-schievink
added
C-enhancement
|
@little-dude Would you like to do this yourself? Or would you like me to do it? I am also wondering: What do you think is the most appropriate location on placing this disclaimer? Somewhere just above the "Organization" heading inside net::ip? |
|
@GuillaumeGomez would it be possible to display a yellow box similar to the "This is a nightly-only experimental API" but with a custom message? I think that adding a entire "stability" heading for each method is a little heavy... Something like this:
|
|
I am against adding such a special feature to rustdoc; a stability heading makes sense here IMO - if it's too heavy to put it on each method, that may be avoidable by putting a general header at the type level and linking to it from the functions, but I would lean towards functions for the default. |
|
Ok, I'm going to go with the heading then. |
|
You can provide a custom message to the unstable attribute like this: #[unstable(feature = "unstable_test_feature", reason = "put your stuff here", issue = "0")] |
Feature tracking issue: rust-lang#27709 - Stabilize the following methods: - `IpAddr::is_global` - `IpAddr::is_documentation` - `Ipv4Addr::is_global` - `Ipv4addr::is_shared` - `Ipv4Addr::is_ietf_protocol_assignment` - `Ipv4addr::is_benchmarking` - `Ipv4Addr::is_reserved` - `Ipv6Addr::is_global` - `Ipv6Addr::is_unique_local` - `Ipv6Addr::is_unicast_link_local_strict` - `Ipv6Addr::is_unicast_link_local` - `Ipv6Addr::is_unicast_site_local` - `Ipv6Addr::is_documentation` - `Ipv6Addr::is_unicast_global` - `Ipv6Addr::multicast_scope` - Stabilize the following enum: `Ipv6MulticastScope` - Document IP helpers stability guarantees (fixes rust-lang#60239)
|
Triage: not 100% sure what all methods would need this here, it seems like the ones directly referenced aren't stabilized yet. |
This issue has come up in #60145
See in particular @the8472's comment.
The IP specifications are constantly changing as new RFCs get written and accepted, and the bits of the specification that are implemented in the standard library may need to be updated accordingly. That means that in the future, we may have to change the behavior of methods that are stable (I think that this is allowed by Rust's rules regarding stability as long as we don't modify the API, but someone more knowledgeable should confirm).
For this reason, it would be nice to add a disclaimer in the documentation of the methods which behavior is susceptible to change in the future, a little bit like the Platform Specific Behavior disclaimer in the doc of some IO methods.
cc @the8472
The text was updated successfully, but these errors were encountered: