search

kornelski / rust-rgb

struct RGB for sharing pixels between crates
https://lib.rs/rgb
MIT License
98 stars 19 forks source link

Why so much `doc(hidden)`? #127

Closed ripytide closed 3 months ago

ripytide commented 3 months ago

I've noticed you've doc(hidden) a lot of items in the crate for some of the legacy items. Would it not be better to keep them visible and instead deprecate them with an explanation to users why to move away from it?

Otherwise there's the possibility that users can't find a method on the docs.rs page that is already being used in a legacy codebase and so can't learn about it (even if it is discouraged from being used/deprecated).

kornelski commented 3 months ago

The compiler will warn users about the deprecated items whenever they're used. This is much easier than manually looking up what's deprecated.

I've put doc(hidden) on trivial items that don't need documentation. This reduces chance that new users will find these items in docs and start using them. It also makes the docs less noisy.