I'm arguing (humbly of course) that intended vs. unintended use of what is at the end of the day a part of the public interface shouldn't be taken into consideration by default. Otherwise, other cases can be argued as non-breaking too!

Foo was never meant to be sent to other threads, So, losing Send is not a semver- breaking change!

Exhaustive enum Bar is only meant to be matched exhaustively internally. We say so in the docs. So adding a variant to it is not a semver-breaking change!

And giving more powers to a (kludge) doc attribute just doesn't seem in my eyes to be a generally wise move.

A: cargo-semver is still complaining about this item which I already have cfg-ed under an exp_api crate feature (which I don't want to rename). CI is failing.

B: PRO-TIP: Just slap a #[doc(hidden)] on it and CI will pass!

A: What if I still want to see the docs?

B: We are pushing for --document-hidden-items to stabilize soon. So you can just simply use that!

[–] notriddle@programming.dev 1 points 1 year ago

That's a good point.

cargo-semver-check should definitely provide a way to mark syntactically-public items as "de-facto private," because some projects just need to do bad things and leaving them out in the cold is not helpful. But you've convinced me that doc(hidden) is a poor way to do it.