• BB_C
    link
    fedilink
    arrow-up
    3
    ·
    edit-2
    1 year ago

    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
      link
      fedilink
      arrow-up
      1
      ·
      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.