this post was submitted on 07 Sep 2023
34 points (100.0% liked)
Rust
6130 readers
51 users here now
Welcome to the Rust community! This is a place to discuss about the Rust programming language.
Wormhole
Credits
- The icon is a modified version of the official rust logo (changing the colors to a gradient and black background)
founded 2 years ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
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.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.
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, losingSend
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 anexp_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!
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.