Understanding Rust Error E0753: Invalid Inner Doc Comment Usage

Introduction to Rust Error E0753

Rust Error E0753 occurs when an inner doc comment is used in an invalid context. In this article, we will illustrate the correct usage of inner doc comments and provide examples of erroneous code that triggers this error.

Erroneous Code Example

fn foo() {}
//! foo
// ^ error!
fn main() {}

In the example above, the inner doc comment is used after the function 'foo', which is an invalid context. Inner doc comments should be used before items.

Correct Usage of Inner Doc Comments

Inner doc comments are commonly used to document modules and functions. Here's an example of the correct usage of inner doc comments:

//! A working comment applied to the module!
fn foo() {
    //! Another working comment!
}
fn main() {}

In this example, the inner doc comment is used before the 'foo' function. This comment applies to the entire module.

Using Outer Doc Comments

If you wish to document the item following the doc comment, you should use an outer doc comment. Here's an example demonstrating how to use outer doc comments:

#![allow(unused)]
fn main() {
/// I am an outer doc comment
#[doc = "I am also an outer doc comment!"]
fn foo() {
    // ...
}
}

In this example, the outer doc comment is used before the 'foo' function and two different syntax options are shown. Both comments apply to the 'foo' function.