rust-lang source file boilerplate

snippet-foo.rs

// SPDX-FileCopyrightText: <text> © 2020 Alan D. Salewski <ads@salewski.email> </text>
//
// SPDX-License-Identifier: GPL-2.0-or-later

// Crate-specific settings. Note that we set these here rather than in the
// 'build.rustflags' section of .cargo/config.toml because we want them to
// apply to compilation of our crate only, not to dependency code that we have
// no control over. Also, specifying them via the RUSTFLAGS environment
// variable or via cargo-rustc(1) is much less reliable because we do not have
// any build-tool wrapping (Makefile, GNU Autotools, etc.).
//
// ----------------------------------------------------------------------------
// By default 'unused_must_use' is only a warning, but for our code we will
// treat it as an error. Any instance of our code ignoring something
// flagged with the #[must_use] attribute is probably a bug.
//
// Where truly warranted, you can override this in targetted locations
// within the code by specifying the '#[allow(unused_must_use)] attribute
// above the relevant item.
//
// Note that 'unused_must_use' is entirely different than
// 'unused_variables' (which we still allow b/c they are useful during
// development).
//
// See also:
//     $ rustc -W help | grep '^[[:space:]]*unused-' | less
//     https://users.rust-lang.org/t/unused-comparison-that-must-be-used/43715/2
//     https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#unused-must-use
//     https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-must_use-attribute
//
#![deny(unused_must_use)]