warning: use of deprecated associated function `std::error::Error::description`: use the Display impl or to_string()
error::Error::description(self)
Does this justify the whole Display impl boilerplate or can I can away with the simpler to_string(). What was in description that's now deprecated (and I will miss dearly because of its simplicity)?
Add the Display implementation; that's how errors are done, now.
You can minimize boilerplate by using the thiserror derive macro library to generate one for you, using strings you annotate your error type with.
Related
I am writing a Rust project and I want to use multiple mods. The src directory has files:main.rs, default.rs, difficult.rs.
The default.rs has:
pub struct Info {...}
pub fn f(...) {...}
and adding mod default, I can directly use default::Info and default::f.
But I want to use Info in difficult.rs and I add mod default into difficult.rs, then it gets error which says that default is not found.
How should I fix this?
How should I fix this?
You might want to read the book? The solution is at section 7.4. Rust is not a language which is easy to learn, and learning rust by osmosis or random walking tends to be a frustrating and unsuccessful endeavour.
I would very strongly recommend reading the book cover to cover at least once.
Anyway use is how you "import" things into the local scope.
mod is how you declare a module. If you use mod multiple times for the same file, you're essentially creating copies of the modules, which the compiler will see as two unrelated modules with unrelated types.
Is it possible to run rust analyzer to not just display but outright inject variable types on variable declarations?
Say in this case
The linter is displaying the type, I would like it to inject the characters instead of just showing them.
It can't, because it's out of scope. Adding the type would mean changing the file, and that's not rust-analyzer's job. rust-analyzer extracts the necessary type information, and whatever editor/IDE you use has to provide the feature of actually adding it.
Here's an example of me using Helix's source-actions menu (Space+a) to add the type:
(Conceptually, rather than rust-analyzer, it'd be cargo clippy --fix that could be used for changing files, but I haven't found a lint like that and suspect it's not implemented.)
This section of the Rust book seems to imply that it is possible to keep Rust documentation in separate .md files, but it does not say how these .md files can then be included back. How does this work?
The syntax for putting Rust module documentation in separate Markdown files is:
#![doc = include_str!("path/to/some-documentation.md")]
/* content of the module */
This is supported since stable Rust 1.54.0.
On old nightly compilers from 1.50.0-nightly through 1.53.0-nightly, an unstable feature is required in order for the above to be available.
#![feature(extended_key_value_attributes)]
#![doc = include_str!("path/to/some-documentation.md")]
On nightly compilers 1.24.0-nightly through 1.53.0-nightly, the following alternative syntax is available, but has since been removed.
#![feature(external_doc)]
#![doc(include = "path/to/some-documentation.md")]
It doesn't. That section on describing the functionality of rustdoc is saying that it can process individual .md files. The third paragraph touches on this:
Documentation can be generated in two ways: from source code, and from standalone Markdown files.
Insofar as I am aware, there is no extant way to put code documentation in external files. It would be theoretically possible to do so using a procedural derive macro, but I'm not aware of any crate that actually does this.
In stable Rust, you can mimic the unstable external-doc feature through clever macros.
An easy way to do this is to use the doc-comment crate:
#[macro_use]
extern crate doc_comment;
// If you want to test examples in your README file.
doctest!("../README.md");
// If you want to document an item:
doc_comment!(include_str!("another_file.md"), pub struct Foo {});
You can see a complicated version of this in my crate SNAFU, where I use it for the user's guide.
The "by-hand" version involves passing the thing to be documented along with the included markdown:
macro_rules! inner {
($text:expr, $($rest: tt)*) => {
#[doc = $text]
$($rest)*
};
}
inner! {
include_str!("/etc/hosts"),
mod dummy {}
}
See also:
Is it possible to emit Rust attributes from within macros?
How to embed a Rust macro variable into documentation?
Generating documentation in macros
While improving clippy lints, I was asked if it's possible to tell if a lint's suggestion can be spliced into the code directly ("change X to Y"), or if it is incomplete / informal and should be implemented manually ("consider renaming this variable").
Currently, clippy uses span_suggestion(Span, &str), but I don't see a way to inform the compiler about the type of suggestion being made. Is there some (planned) API to do this?
I notice that compiler plugins frequently provide macros that the documentation wont even mention. They're registered and created programmatically rather than being defined in a syntax rustdoc recognizes. Naturally, no documentation can be shown.
I'm looking for a way to get around that, some way of generating documentation for a macro that doesn't exist in the crate at compile time.
I notice the syntax crate could benefit from such a thing as well. quote_item, for instance, is completely undocumented. I can't even find the code that registers it.
One possibility is to do what the compiler does: create an empty macro_rules! macro and attach documentation to that. E.g. if a crate defines foo that takes a single expression, then write something like
/// Documentation
#[macro_export]
macro_rules! foo {
($e: expr) => ({ /* syntax extension */ })
}
I notice the syntax crate could benefit from such a thing as well. quote_item, for instance, is completely undocumented. I can't even find the code that registers it.
You can search the Rust source for quote_item, which is helpful for two reasons: it gives some examples, and also allows you to track down the definition. The latter is easier using Rust's DXR instance which can search for things with quotes (i.e. can find strings), and includes various source code navigation tricks (like jump-to-definition).