Developer-provided compiler notes

Rust right now has very nice error messages, and can even suggest fixes for some common issues. What I think it's lacking, though, is the ability for a developer of a library to, say, for example, warn a user that their function should only be used in a specific context, may be subject to change, or other situations.

What I propose is adding the ability for a compiler to add an error as such:

#[vashta_nerada("This function is a bit hacky, and may be very buggy in practice. Tread carefully.")]
fn do_something() {
    /// something

The name is inspired by the Vashta Nerada from Doctor Who, and I think it's fitting. It can be used to signify when something's dangerous, and the compiler can't feasibly warn the user with enough information. It's also flexible enough that it could remove the need for other, more specific, features.

I'm not sure if just a crate-added attribute macro would be enough here.

Name can probably be put up for discussion, but I'd like to focus more on the specifics of how to use this.

Also, it's odd that rust has compile_error!() but doesn't have compile_warning!(), it feels incomplete.


deprecated is basically this today with some added semantics, so (a) you have a workaround, and (b) it’s clearly not too hard to implement.

One of the things that make Rust's error messages nice is that they each have a specific purpose and are actionable one way or another; the typical Rust project has no warnings except momentarily, because they've all been either fixed or allowed.

Thus, there should not be a mechanism for generically saying “this is dangerous”. It should specify what the danger is. Otherwise people will (rightly) write #[allow(vashta_nerada)] and leave the reader of the code uninformed about what the hazard is unless they also write a specific comment. At that point, you're better off if you just put the hazard in the function name. do_something_flaky().

And I say: don't make people afraid of the dark; build lights. Be precise.

You may be interested to hear of plans for adding more ways to declare custom diagnostics:


If there were a mechanism to allow (accept and dismiss) this warning for a specific third-party function to which the attribute has been attached, I can see it as possibly being useful, but a warning that applies to all uses of a function in one's API, if one intends for users to continue using that function, seems an unhelpfully blunt instrument.

The creatures described in the linked wiki article sound more dangerous than the warning does. While I've never read a Lovecraft book, I quickly think of that.

Fair enough, I made this suggestion when I was a bit tired (putting it lightly...) and stuck on some other stuff, I guess the name suggestion and whole idea was a tad affected by that. I'll save the Doctor Who references for when I inevitably try writing my own programming language :slight_smile:

@dlight mentioned there not being a compile_warning!() macro, that would probably fix up this concern too, while being more specific and not so scary-sounding.

compile_warning! would only be useful for macros, if you try to use it within your own code it will be suppressed by —cap-lints.

As alluded by the RFC that was linked earlier, the intention is to start adding such functionality over the course of the next 18 months, first to customize trait bound and type errors, and later to allow for further customization. There's some progress in stabilizing the proc-macro diagnostics APIs that would let you create both errors and warnings with the full (almost) power that rustc has. I am also exploring the possibility to work on some mechanism for custom lints, with the intention of eventually producing an API that rustc can commit to and clippy use for this (so as to reduce the number of special tools needed). This would allow people to have per projects lints to enforce invariants that for some reason or another can't be represented in the type system.

Please bear with us as we slowly make progress on this. I'm really interested in giving crate authors the tools necessary for an amazing developer experience.


We do have an attribute for this: #[doc].