Gate Rules-helpers on unstable

[Manishearth]

According to
#6659 (comment), all experimental APIs should be gated (not hidden) on unstable. We have not yet implemented the plan in that PR, but we should try to follow it for new things behind the unstable feature.

#7092 put Rules behind the unstable feature, but it made it doc(hidden). For Rules specifically, it needs to be doc(hidden) since datetime uses it, but the other types should be fully gated.

This PR fully gates the YearInfo types, and makes Rules narrowly doc(hidden). It also adds additional docs that explain the unstableness of the parameters on LunarChinese and Hijri since the trait docs will not be visible when the feature is disabled

[robertbastian]

I would like to review this tomorrow, there are a lot of changes here

[Manishearth]

Sure.

I put the cross-crate import behind hidden mod unstable_internal, which decouples the unstable-gated code that we expect experimental users to use from the internal cross-crate stuff. I think that's a good change overall, we can be consistent about fully gating unstable stuff.

This plan was somewhat sketched out in #6659 (comment)

[sffc]

I think I'm happy with this for 2.1 purposes. @robertbastian wants to review again.

[sffc]

Suggestion: I think this can bind on FormattableHijriRules, and then we have only 1 user of the calendar trait in the datetime crate

[Manishearth]

That would be cyclic, yes? FHR depends on UnstableSealed

[robertbastian]

It also adds additional docs that explain the unstableness of the parameters on LunarChinese and Hijri since the trait docs will not be visible when the feature is disabled

in #6659 we decided that the unstable feature would be enabled on docs.rs, so I don't see the necessity of this. in fact, if you build local docs with the actual features you have enabled you shouldn't need to know this. I don't want to set a precedent for explaining unstable APIs on other APIs because of the possibility that someone builds docs locally without the unstable feature

[robertbastian]

not a fan of unstable modules, and I don't think we have agreed on doing this

[Manishearth]

What we agreed on doing was gating these.

We're not doing that here: we're conditionally-doc(hidden)ing them, because we have to.

We have not agreed on a route to take for this case. The route proposed here seems okay and easy to change in the future.

My justification for this route is that a conditional doc(hidden) will still show up on docs.rs, which means people may use it without enabling the unstable feature. This module means that if people wish to use the thing on docs.rs they must explicitly opt in to the unstable feature, and internally we use a different, secret path that is very clearly unstable.

[robertbastian]

ok the route proposed here seems okay and I guess because it's unstable we can change it at any time

[Manishearth]

in fact, if you build local docs with the actual features you have enabled you shouldn't need to know this

Yes, you should: With local docs, you will see an unlinked Rules trait and not necessarily know what the valid types are for this type parameter. This is what this line is attempting to clarify. I think the new_china() and new_korea() constructors help, but it's nice to be explicit.

[Manishearth]

Merging based on Robert's review and Shane's earlier statement. Nothing in this PR is irreversible, anyway.

[Manishearth]

I want to do more unstable-gating work on traits here but I think it will clash with error handling.