-% Comments [FIXME: needs RFC]
+% Comments [RFC #505]
### Avoid block comments.
### Code snippets
-> **[FIXME]**
+Only use inner doc comments `//!` to write crate and module-level documentation,
+nothing else. When using `mod` blocks, prefer `///` outside of the block:
+
+```rust
+/// This module contains tests
+mod test {
+ // ...
+}
+```
+
+over
+
+```rust
+mod test {
+ //! This module contains tests
+
+ // ...
+}
+```
### Avoid inner doc comments.
//! `0`.
//!
//! The value for the width can also be provided as a `usize` in the list of
-//! parameters by using the `2$` syntax indicating that the second argument is a
-//! `usize` specifying the width.
+//! parameters by using the dollar syntax indicating that the second argument is
+//! a `usize` specifying the width, for example:
+//!
+//! ```
+//! // All of these print "Hello x !"
+//! println!("Hello {:5}!", "x");
+//! println!("Hello {:1$}!", "x", 5);
+//! println!("Hello {1:0$}!", 5, "x");
+//! ```
+//!
+//! Referring to an argument with the dollar syntax does not affect the "next
+//! argument" counter, so it's usually a good idea to refer to all arguments by
+//! their position explicitly.
//!
//! ## Precision
//!
}
let sub_span = self.span
- .sub_span_of_token(path.span, token::BinOp(token::Star));
- if !self.span.filter_generated(sub_span, path.span) {
+ .sub_span_of_token(item.span, token::BinOp(token::Star));
+ if !self.span.filter_generated(sub_span, item.span) {
self.dumper.use_glob(UseGlobData {
span: sub_span.expect("No span found for use glob"),
id: item.id,