Unable to write documentation for similar ending routes

[Kaiden42]

Hello, I'm trying to write some documentation for my project and noticed, that I'm unable to write documentation for routes that have a similar ending. For example: /user/add and /survey/add. Both routes are in different modules.

• Rocket version: Master branch
• Rust version: rustc 1.46.0-nightly (346aec9b0 2020-07-11)
• Os: Linux Mint 20 Cinnamon Edition (beta)

Here is a small working example of my code:

#![feature(proc_macro_hygiene, decl_macro)]

#[macro_use] extern crate rocket;
use tokio::runtime;

mod survey {
    #[get("/survey/add")]
    pub fn add() {

    }
}

mod user {
    #[get("/user/add")]
    pub fn add() {

    }
}

fn main() {
    let mut rb = runtime::Builder::new()
        .basic_scheduler().enable_all().build().unwrap();

    rb.block_on(rocket::ignite()
        .mount("/", routes![survey::add, user::add])
        .launch()).unwrap();
}

Everything works fine until I start to add some documentation like this:

    ...

    /// Route to add a survey.
    #[get("/survey/add")]
    pub fn add() {

    ...

    /// Route to add a user.
    #[get("/user/add")]
    pub fn add() {

    ...

I'm able to document the first route but after the second one I get the following error message from the compiler:

error[E0428]: the name `rocket_uri_macro_add9134641248968336068` is defined multiple times
  --> src/main.rs:16:5
   |
8  |     #[get("/survey/add")]
   |     --------------------- previous definition of the macro `rocket_uri_macro_add9134641248968336068` here
...
16 |     #[get("/user/add")]
   |     ^^^^^^^^^^^^^^^^^^^ `rocket_uri_macro_add9134641248968336068` redefined here
   |
   = note: `rocket_uri_macro_add9134641248968336068` must be defined only once in the macro namespace of this module
   = note: this error originates in an attribute macro (in Nightly builds, run with -Z macro-backtrace for more info)

This only happens if the routes end similarly. It should be possible to document routes of this type.

[jebrosen]

This is a limitation introduced by #964, when we removed the usage of the decl_macro feature. In particular, each route generates a corresponding macro in the crate's global namespace. Since the names must be unique, they are disambiguated by hashing the file_name, line, and column of the function - this should provide a unique hash, and usually does...

until you add documentation with ///. It looks like this causes rust-lang/rust#43081, and one of the effects of that bug is that both routes appear to be at line 1, column 0 of the file and hash the same.

Some workarounds that you can use today:

• Put the routes in different files. file_name is also part of the hash and it appears to be unaffected by the rustc bug.
• Use #[doc = ""] instead of the /// syntax sugar, which also seems to avoid the bug. This is very ugly, even for a workaround.
• Name the routes differently, e.g. add_survey and add_user. The name of the route is part of the macro name, so this will make them unambiguous.

One really awkward workaround rocket might be able to do is to hash more, such as the function contents. Another awkward workaround in rocket would be to randomly generate the disambiguator instead of deriving it from the input.

[igalic]

is there no way to include the namespaces / module in the hash?

[Kaiden42]

Thank you very much for your answer. I will probably choose the #[doc =""] variant, even if it is a little bit ugly. I'd like to avoid renaming the routes, if it's really only about documentation ;-)

In my actual project, the two modules survey and user are already designed in separate files. The problem also occurs when I adapt the sample code accordingly.

survey.rs

/// This is a comment
#[get("/survey/add")]
pub fn add() {

}

user.rs

/// This too
#[post("/user/add")]
pub fn add() {

}

main.rs

#![feature(proc_macro_hygiene, decl_macro)]

#[macro_use] extern crate rocket;
use tokio::runtime;

mod survey;
mod user;

fn main() {
    let mut rb = runtime::Builder::new()
        .basic_scheduler().enable_all().build().unwrap();

    rb.block_on(rocket::ignite()
        .mount("/", routes![survey::add, user::add])
        .launch()).unwrap();
}

Thus, it seems that swapping out to different files is also affected by the rustc bug.

error[E0428]: the name `rocket_uri_macro_add9134641248968336068` is defined multiple times
 --> src/user.rs:3:1
  |
3 | #[post("/user/add")]
  | ^^^^^^^^^^^^^^^^^^^^ `rocket_uri_macro_add9134641248968336068` redefined here
  |
 ::: src/survey.rs:3:1
  |
3 | #[get("/survey/add")]
  | --------------------- previous definition of the macro `rocket_uri_macro_add9134641248968336068` here
  |
  = note: `rocket_uri_macro_add9134641248968336068` must be defined only once in the macro namespace of this module
  = note: this error originates in an attribute macro (in Nightly builds, run with -Z macro-backtrace for more info)

[jebrosen]

@Kaiden42 can you try again after a cargo update, now that the issue was fixed in rocket_codegen?

[Kaiden42]

I can confirm that after a cargo update the problem has now been fixed. Thank you very much! :)