如何在函数调用时显示编译器警告？

Question

我有一个我想在我的模块中导出的函数，以便人们可以使用它。然而，在 95% 的情况下，使用它是一个坏主意。

/// 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
}

它主要用于文档和测试目的。但是，因为有 5% 的情况下这样的东西可能真正有用，所以我想保留它。

我不希望人们不小心使用它，所以我想调用该函数会导致编译器警告（除非他们明确地用allow或其他东西覆盖它）。我怎样才能做到这一点？

Answer 1

您可以将该函数标记为已弃用：

// 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
}

如果用户使用该功能，他们会收到警告：

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.

但他们可以通过以下方式将其关闭#[allow(deprecated)]：

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

游乐场链接。

Answer 2

在must_use似乎很贴切，并允许指定自定义消息：

#[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();
}

这将创建一个带有自定义消息的警告：

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