An analysis of semver compliance in Rust finds accidental semver violations are common even in the most popular crates. Human error is not the cause, and better tooling is the way forward.
“Just don’t write bugs” ( or “Just don’t write semver violations” in this case) is now rightfully recognized as a joke proposition by many (although derivative ability/experience arguments are sometimes still used, UNIRONICALLY). But it’s the “better education” (or its sister magic pill “better docs”) that still has many believers. So it is still valuable to explicitly make the argument for reliable automated tooling as the only real logical solution. But I digress.
if our Example enum above was #[doc(hidden)], adding a new variant would not have violated semver.
Violations in #[doc(hidden)] items should definitely trigger errors by default IMHO. To give what was a kludge in the first place more powers is not something I would call wise. Not to mention, module source code is just one click away from html docs, and it’s also one click/key-combination away from a crate user’s editor/IDE with LSP (rust-analyzer).
So
how #[doc(hidden)] items sometimes have semver obligations after all,
I would argue it’s always the case, unless the user of the tool explicitly decides it’s not.
What do you think #[doc(hidden)] is for, other than declaring something “private” that the language unfortunately doesn’t let you declare as truly private right now?
I’ve mostly seen it used as a way to expose tools to macro APIs. For example, these internal parts of the quote! macro, or these internal parts of the vec! macro. Changing these things shouldn’t be considered a semver violation, because they’re not really part of the API, even though the quote! macro can’t enforce it.
The only other cases I can think of where I’ve seen #[doc(hidden)] used are even bigger kludges, and the hidden items definitely aren’t part of the platonic API, like pre-#[non_exhaustive] crates that wanted to reserve the right to add new variants to their enums.
It would be nice if we had something like pub(macro), which would make something public but only inside macros from the same crate. So they are usable in macros but not part of the public API.
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!
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.
Probably a spicy take, but I think any API being used by a macro should be made public. A macro shouldn’t be the only way to do something; it should just be a way to remove the boilerplate required to do it.
Good work.
“Just don’t write bugs” ( or “Just don’t write semver violations” in this case) is now rightfully recognized as a joke proposition by many (although derivative ability/experience arguments are sometimes still used, UNIRONICALLY). But it’s the “better education” (or its sister magic pill “better docs”) that still has many believers. So it is still valuable to explicitly make the argument for reliable automated tooling as the only real logical solution. But I digress.
Violations in
#[doc(hidden)]items should definitely trigger errors by default IMHO. To give what was a kludge in the first place more powers is not something I would call wise. Not to mention, module source code is just one click away from html docs, and it’s also one click/key-combination away from a crate user’s editor/IDE with LSP (rust-analyzer).So
I would argue it’s always the case, unless the user of the tool explicitly decides it’s not.
What do you think
#[doc(hidden)]is for, other than declaring something “private” that the language unfortunately doesn’t let you declare as truly private right now?I’ve mostly seen it used as a way to expose tools to macro APIs. For example, these internal parts of the
quote!macro, or these internal parts of thevec!macro. Changing these things shouldn’t be considered a semver violation, because they’re not really part of the API, even though thequote!macro can’t enforce it.The only other cases I can think of where I’ve seen
#[doc(hidden)]used are even bigger kludges, and the hidden items definitely aren’t part of the platonic API, like pre-#[non_exhaustive]crates that wanted to reserve the right to add new variants to their enums.It would be nice if we had something like
pub(macro), which would make something public but only inside macros from the same crate. So they are usable in macros but not part of the public API.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!
Foowas never meant to be sent to other threads, So, losingSendis not a semver- breaking change!Exhaustive enum
Baris 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-semveris still complaining about this item which I already have cfg-ed under anexp_apicrate 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!
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.Probably a spicy take, but I think any API being used by a macro should be made public. A macro shouldn’t be the only way to do something; it should just be a way to remove the boilerplate required to do it.