I am writing a crate that I plan to publish. When publishing, one of the most important thing (in my opinion) is to ensure the crate is well documented. Therefore my question : is there a warning to be turned on which warms undocumented sections of the code ?
E.g.: I typically think of something like #[warn(undocumented)].
Yes, such a lint exists. The rustc compiler provides the missing_docs lint, which warns about missing documentation on public items when enabled. The clippy linter provides the missing_docs_in_private_items lint, which additionally warns… well, you guessed it. Note that missing_docs_in_private_items warns for all items, so you don't need missing_docs if you enable it.
You can enable the lints using
#![warn(missing_docs)]
#![warn(clippy::missing_docs_in_private_items)]
for warnings or
#![deny(missing_docs)]
#![deny(clippy::missing_docs_in_private_items)]
for errors.
You are looking for the missing-docs lint in the Rust compiler.
Example:
#![warn(missing_docs)]
fn foo(bar: i32) {}
The output from the compiler:
warning: missing documentation for crate
--> src/lib.rs:1:1
|
1 | / #![warn(missing_docs)]
2 | |
3 | | fn foo(bar: i32) {}
| |___________________^
|
You may also find more lints in the rustc book.
Related
Sometimes you want to suppress a clippy warning for the time being and you let clippy ignore a specific rule for a specific code block by adding lines like the following:
#[allow(dead_code)]
But as the project continues, it can actually happen that you remove the problem, without actually removing the allowing of the clippy lint. So is there a way to check for allowed clippy warnings that are actually not being used anymore? So in this example I'd like to be informed when I #[allow(dead_code)] but there is actually no dead code to be found in the given code block.
The unstable feature (currently only usable using the nightly Rust compiler) lint_reasons includes the ability to use expect( instead of allow(, which allows the lint but warns if the lint is not detected.
#![feature(lint_reasons)]
#[expect(dead_code)]
fn foo() {}
fn main() {
foo();
}
Output:
warning: this lint expectation is unfulfilled
--> src/main.rs:3:10
|
3 | #[expect(dead_code)]
| ^^^^^^^^^
|
= note: `#[warn(unfulfilled_lint_expectations)]` on by default
There is no current schedule for this to make it to stable but at least people want to see it and there's an implementation.
You could try prefixing unused functions/variables/etc. with a _ (the compiler will also mention this.) if you do not want the warnings to appear. If you remove the any of the temporary/dead code containing the prefix, you won't have to worry about #![allow(dead_code)].
quick introduction, I came from python I have studied it by myself, and now I'm trying to learn Rust. I find it a bit confusing.
I have a main.rs file and other .rs files in the src directory just to have cleaner and organized code, as each of these other files do specific tasks and the main.rs just put all together with a simple CLI.
I just wanna test a single of these .rs file, or even a single fn inside to check if the result is what I am expecting.
How can I do that? It's simple, it's stupid, but I have read around and found nothing that could help me in the end.
I read this, where it talks about making a tests folder and then using cargo test, I've done it, but it still runs the src/main.rs instead of what I have put in tests. BTW I'm using CLion with the Rust plugin.
Sorry if this is somewhat a duplicate, I looked around but I didn't found an answer.
This funcitonality is not really part of Rust itself, but there are some crates that do it. The one I'm most familiar with is rust-script. It works with a hashbang like #!/usr/bin/env rust-script at the top of your script, then run it with ./script.rs. You can even specify dependencies in the script which get parsed out of some special comments.
Edit: Sorry yes - it looks like you're trying to write/run tests. The page you linked in the book should cover what you're trying to do. I'm not sure what you mean by "it still runs the src/main.rs instead of what I have put in tests". Do you have mod tests in main.rs as well?
you can compile any .rs file using rustc your_file.rs command as long as the file contains main() function. rustc will fail if there isn't main function:
error[E0601]: `main` function not found in crate `abc`
--> abc.rs:5:2
|
5 | }
| ^ consider adding a `main` function to `abc.rs`
error: aborting due to previous error
For more information about this error, try `rustc --explain E0601`.
but you can skip this by marking the file as library crate instead of bin:
rustc you_file.rs --crate-type=lib
I'm working on a Rust plugin that needs to access the absolute path of a trait bound. In practice, this means that for the following code, I want to resolve the full path of Debug as std::fmt::Debug.
use std::fmt::*;
#[foo]
trait Foo: Debug {}
My current approach consist of taking the Annotatable that MultiItemDecorator provides for me and pattern matching it to
Annotatable::Item, where I match .node to ItemKind::Trait. I then match .generic_bounds to a collection of GenericBound::Trait, where I retrieve .trait_ref.path.
This struct however only contains path(Debug), which is not enough information for me.
You can't.
The Rustc Driver:
[…] the main phases of the compiler are:
Parse Input: Initial crate parsing
Configure and Expand: Resolve #[cfg] attributes, name resolution, and expand macros
Run Analysis Passes: Run trait resolution, typechecking, region checking and other miscellaneous analysis passes on the crate
Translate to LLVM: Translate to the in-memory form of LLVM IR and turn it into an executable/object files
(emphasis is mine)
Macros are expanded before trait resolution is done, so at the time your plugin is run, nothing is known about this Debug except the name given in the source code.
I'm writing a program in Rust and I have some tests for it. I wrote a helper function for these tests, but whenever I build using cargo build it warns me that the function is never used:
warning: function is never used: ... #[warn(dead_code)] on by default
How I can mark this function as used so as not to get the warnings?
Specific question
How I can mark this function as used so as not to get the warnings?
The Rust compiler runs many lints to warn you about possible issues in your code and the dead_code lint is one of them. It can be very useful in pointing out mistakes when code is complete, but may also be a nuisance at earlier stages. Often, this can be solved by either deleting unused code, or by marking a public method. However, all lints can be turned off by allowing them, and your error message (#[warn(dead_code)] on by default) contains the name of the lint you could disable.
#[allow(dead_code)]
fn my_unused_function() {}
Alternative for testing
I wrote a helper function for these tests, but whenever I build using cargo build it warns me that the function is never used.
This happens to be a special case, which is that code that is only used for testing isn't needed in the real executable and should probably not be included.
In order to optionally disable compilation of test code, you can mark it accordingly using the cfg attribute with the test profile.
#[cfg(test)]
fn my_test_specific_function() {}
When marked in this way, the compiler knows to ignore the method during compilation. This is similar to commonly used ifdef usage in other languages like C or C++, where you are telling a preprocessor to ignore the enclosed code unless TESTING is defined.
#ifdef TESTING
...
#endif
For people getting this warning while making a rust library, you may get this if you don't have your modules set to pub in your lib.rs.
pub mod foo;
If something is only used in tests, it should be omitted altogether. This can be done with the #[cfg(test)] attribute.
dead_code is a lint, which means you can allow it on the thing that's causing it to trigger.
#[allow(dead_code)]
fn dummy() {}
fn main() {}
There is another situation where this can occur. If you have several helper functions in a module, e.g. in tests/utils/mod.rs and then several integration tests (tests/a.rs, tests/b.rs) each of which does
mod utils;
use utils::...;
then you will get dead code warnings if you do not use all of the code from all of the tests. For example if test a.rs only uses utils::foo and b.rs only uses utils::bar then you will get dead code warnings for both.
That is because each test is compiled as an independent crate. Here is the bug report for it. It looks difficult to solve so I wouldn't hold my breath.
You can disable specific lints for a whole project in Rust by going into your main.rs file and adding the following at the very top of the file:
#![allow(
dead_code,
unused_imports
)]
You max prefix the unused function name with an underscore:
fn _dummy() {}
fn main() {}
See: https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#dead-code
For some reason I found that setting the main function to public:
pub fn main()
and then copying my main.rs file to lib.rs
cp src/main.rs src/lib.rs
then recompiling fixed this.
No need to use a macro for it, although the macro should work for non main functions.
I am trying to use the Options struct in the getopts crate, which exists according to the Rust book.
The code I am running is this.
let mut opts = getopts::Options::new();
While building the project the compiler gives the error
let mut opts = getopts::Options::new();
^^^^^^^^^^^^^^^^^^^^^ Could not find `Options in `getopts`
How do I resolve this? I am using the nightly version of Rust.
You need to use the crates.io version instead. You can see here that the built-in version of getopts has been flagged as a compiler internal with rustc_private. The version on crates.io is basically the same crate. The compiler-internal version is just kept segregated for various reasons.