How to mark an API as volatile

help
1

Certain parts of my public API are subject to changes.

I don't want to hide them, but I do want to warn people that using them may break code later on with newer versions.

Is there an attribute I can set on the volatile functions?

2

Usually such interfaces are hidden behind a feature flag with a name like "unstable".

#[cfg(feature = "unstable")]

You can enable feature flags for docs.rs, so that it's still visible there even if it's off by default.

1 Like
3

OK, that's what I'm doing right now, but I was hoping for a way to give some warnings like the standard Rust API's.

4

What do you mean by "standard Rust APIs"? If that's about nightly features, then they are using the same idea, only on the compiler level, not managed by Cargo.

5

I don't think there's any option to make them warn on every use, except the deprecated attribute.

6

You can pass a note to the deprecated attribute to make it a bit clearer what's going on.

If you used this method:

#[deprecated(note = "this method is in active development and may change")]
fn test() {
  todo!();   
}

It would show this in the console:

warning: use of deprecated item 'test': this method is in active development and may change
 --> src/main.rs:8:5
  |
8 |     test();
  |     ^^^^
  |
  = note: `#[warn(deprecated)]` on by default
2 Likes
7

The deprecated attribute looks like something I can use.

Is there any other similar attributes that I can consider?

8

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.