Is there a way to create inner attributes (`#![doc(…)]`)?

[shepmaster]

I’d like to include module-level documentation.

[GuillaumeGomez]

I need to extend the macro a bit to allow this.

[Hexilee]

Is there some progress?

[GuillaumeGomez]

I didn't work on it at all, sorry. I'll try to go back on it this week-end.

[GuillaumeGomez]

So from my experiments, I don't think this is possible:

#[macro_export]
macro_rules! parent_doc_comment {
    ($x:expr) => (
        #![doc = $x]
    )
}

pub fn foo() {
    parent_doc_comment!("foo!")
}

fn main() {}

gives the error:

error: an inner attribute is not permitted in this context
 --> src/main.rs:4:9
  |
4 |         #![doc = $x]
  |         ^^^^^^^^^^^^
...
9 |     parent_doc_comment!("foo!")
  |     --------------------------- in this macro invocation
  |
  = note: inner attributes, like `#![no_std]`, annotate the item enclosing them, and are usually found at the beginning of source files. Outer attributes, like `#[test]`, annotate the item following them.

error: macro expansion ends with an incomplete expression: expected expression
 --> src/main.rs:4:21
  |
4 |         #![doc = $x]
  |                     ^ expected expression

error: aborting due to 2 previous errors

[Hexilee]

Maybe we can implement it by proc-macro.

[GuillaumeGomez]

We could, but I have to admit that I'm curious about this: in which case do you need to it? You can always document modules when they're imported/reexported. The only exception is the crate-level doc.

[Hexilee]

Actually, I would like to include README as crate-level doc.

[GuillaumeGomez]

For this specifically, you can take a look here. But unfortunately, it's an unstable API... Not really an issue when publishing on docs.rs, but it might for end users. You can put it behind a features enabled only when running on docs.rs though (and to do that, you can take a look here).

[Hexilee]

Get it! thank you very much

[shepmaster]

And for what it’s worth, I was able to reorganize my code so I no longer need this functionality.

[GuillaumeGomez]

So I made the switch to proc-macro in #21 and it's not possible for the moment to use them as inner attributes either... But at least it extended the initial one, which is nice.