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).
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.
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?
If I have multiple .rs files in the src directory of a Cargo package, what are the rules for visibility, importing, etc.?
Currently, any extra (i.e. not the file that is explicitly identified as the source for the executable in Cargo.toml) files are ignored.
What do I need to do to fix this?
There is nothing special about Cargo at all in this way. It’s all the perfectly normal Rust module system. If Cargo will be compiling src/lib.rs, that’s more or less equivalent to having executed rustc --crate-type lib src/lib.rs (there are more command line arguments in practice, but that’s the basics of it).
Other files are then used with mod, use and so forth. Files are not automatically imported or anything like that. This part is not documented very clearly yet; a couple of things that show briefly how to achieve things are http://rustbyexample.com/mod/split.html and http://doc.rust-lang.org/reference.html#modules, but any non-trivial code base will use them and so you can pick just about any code base to look at for examples.
It's hard to say what you're getting tripped up on from the info you shared. Here are three seemingly trivial things that I still had to refer to the documentaton to figure out:
First of all,
mod foo;
looks like a declaration, but it without arguments it is actually something like an include. So you use the same keyword both for declaring and including modules, i.e. there is no using:: keyword.
Second, modules themselves can be public or private. If you didn't add a pub keyword both on the function in question AND on the containing module, that may be tripping you up.
pub mod foo {pub fn bar();}
Third, there seems to be an implicit module added at the top of every file. This is confusing; the reference manual talks about a strict separation between file paths and names, and the module paths in your code, but that abstraction seems to be leaky here.
Note, Rust is still pre-1.0 (0.12) at the time of writing, at the module system and file paths are relatively high level, so don't be surprised if what I said may already wrong by the time you read this.
Files are implicitly included from your rust code.
For instance, if a file src/foo.rs pointed by path in a [lib] or [[bin]] section of your Cargo.toml contains:
mod bar;
It tells cargo to build src/bar.rs too, and include it.
I'm working on a cross platform project that uses STL. The other compiler includes STL support by default, but in VS2005 I need to add the following before the class definitions that use STL items:
#include <cstdlib>
using namespace std;
Is there a VS2005 option that would set this automatically? It's just a bit tedious to work around. I'm just trying to avoid lots of #ifdefs in the source -
EDIT: The other compiler is the IAR workbench for the ARM 926x family. Perhaps I should get them to explicitly do the includes?
Also - is "std::map<>" preferred over "using namespace std; map<>" ?
All compilers should require you to include those lines. If they don't, then they're just encouraging you to write non-portable code because you're relying on certain headers to be included automatically and you're relying on certain names to be in scope implicitly.
I don't mean to say that those two lines should always be required, though. I only mean that if the rest of your code is written to use things declared in the cstdlib header and in the std namespace, then those two lines need to appear first, and the compiler shouldn't act as though they are there when they really aren't.
Check whether your other compiler has some settings to disable this implicit code. If it doesn't, then it's probably a very, very old compiler, and you should consider not using it and not supporting it anymore.
Try refering to STL components by their namespace-qualified name (i.e. std::vector).
Doing a global 'using namespace std' is usually a bad idea.
Or maybe I'm not understanding the question.
The IAR compiler does not support the std namespace (I'm not sure why, because it does support namespaces in general if I remember right).
If you look in the runtime headers for IAR you'll see that they do some macro gymnastics to work around that (the runtime is licensed from Dinkumware, who provide runtimes for quite a few compilers).
You may need to do something similar if you want your stuff to work in multiple environments. A possible cleaner alternative is to just include the "using namespace std;" directive. I might be wrong, but I think the IAR compiler essentially ignored it (it didn't mind that you were using a namespace it didn't know about). A lot of people will think that's ugly, but sometimes you gotta do what the compiler you have wants you to do.
In general you should avoid "using namespace X", especially in header files (because everyone who includes your header gets that namespace too whether they want it or not), and especially for namespace std (because it's so big and the potential for name collisions is big).
Instead, in header files refer to names by their fully qualified form, e.g.:
// for plain functions
void foo(std::map<int> intMap);
// for classes
class person {
std::string name_;
public:
person(std::string name);
// ...
};
Then, in code files, you can do "using", but prefer using specific items in the namespace rather than pulling in the entire namespace. e.g.:
using std::map;
using std::string;
void foo(map<int> intMap) { ... };
person::person(string name) : name_(name) { ... };
etc. This way you avoid impacting others including your headers, and you avoid pulling in potentially zillions of names that might cause a collision with other stuff.