Rust

6130 readers

51 users here now

Welcome to the Rust community! This is a place to discuss about the Rust programming language.

Wormhole

[email protected]

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

[email protected]

Semver violations are common, better tooling is the answer (predr.ag)

submitted 1 year ago by [email protected] to c/[email protected]

23 comments fedilink hide all child comments

you are viewing a single comment's thread
view the rest of the comments

[–] [email protected] 1 points 1 year ago* (last edited 1 year ago) (1 children)

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!

[–] [email protected] 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.