How can I display a compiler warning upon function invocation?

user_5223757 0
Viewed 359

I've got a function I want to export in my module so people can use it. However, in ≈95% of cases, using it is a bad idea.

/// Check whether foo is a metasyntactic variable.
/// 
/// **Using this function is a mistake.** This function is slow,
/// since checking widgets is an extremely expensive operation.
/// You should be keeping track of what's what, and ideally will
/// never need to use this function.
/// 
/// If you _do_ need to use this function, please consider a refactor.
pub fn test_widget(foo: String) -> bool {
    false
}

It's mostly around for documentation and testing purposes. However, since there's the ≈5% of cases where such a thing may be genuinely useful, I want to keep it around.

I don't want people accidentally using it, so I want to make invocation of the function cause a compiler warning (unless they explicitly override it with allow or something). How can I do this?

rust static-analysis compiler-warnings
2 Answers

You can mark the function as deprecated:

// Consider summarizing this and linking to the docs, rather than putting the
// entire message here.
#[deprecated(note=
    "**Using this function is a mistake.**
This function is slow,
since checking widgets is an extremely expensive operation.
You should be keeping track of what's what, and ideally will
never need to use this function.

If you _do_ need to use this function, please consider a refactor.")]
pub fn test_widget(foo: String) -> bool {
    /// Check whether foo is a metasyntactic variable.
    false
}

If the user uses the function, they get a warning:

warning: use of deprecated item 'test_widget': **Using this function is a mistake.**
This function is slow,
since checking widgets is an extremely expensive operation.
You should be keeping track of what's what, and ideally will
never need to use this function.

If you _do_ need to use this function, please consider a refactor.

But they can turn it off with #[allow(deprecated)]:

#[allow(deprecated)]
test_widget("Hello, World!".to_string()); // no warning

Playground link.

user_18961690

The must_use seems to be fitting here and allows to specify a custom message:

#[must_use = "Calling this function is a bad idea"]
pub struct BadIdeaFunction(bool);

impl BadIdeaFunction {
    pub fn i_acknowledge_calling_this_function_is_a_bad_idea(self) -> bool {
        self.0
    }
}

/// Check whether foo is a metasyntactic variable.
///
/// **Using this function is a mistake.** This function is slow,
/// since checking widgets is an extremely expensive operation.
/// You should be keeping track of what's what, and ideally will
/// never need to use this function.
///
/// If you _do_ need to use this function, please consider a refactor.
pub fn test_widget() -> BadIdeaFunction {
    BadIdeaFunction(false)
}

fn main() {
    test_widget(); // gives a warning, but the next one doesn't

    test_widget().i_acknowledge_calling_this_function_is_a_bad_idea();
}

This creates a warning with the custom message:

warning: unused `BadIdeaFunction` that must be used
  --> src/main.rs:23:5
   |
23 |     test_widget();
   |     ^^^^^^^^^^^^^^
   |
   = note: #[warn(unused_must_use)] on by default
   = note: Calling this function is a bad idea
user_27338510
Related