idea: new syntax

[sam0x17]

Yandros proposed a new syntax that looks like this:

#[docify::docify]
/// some comments some comments
/// @embed("examples/samples.rs", MyCoolStruct)
/// another example:
/// @embed("src/something.rs", MyThing)
/// some closing comments
pub struct Foo;

Originally mentioned here: https://github.com/paritytech/substrate/pull/14672#issuecomment-1659032003

If we were to go with this syntax, we would finally be able to limit expansion of docify embeds to only be attempted if the caller is #[cfg(doc)] which we currently lack the context information to be able to do, and which is currently impossible in #[doc = ..] position but is possible for an "outer attribute" approach like this.

[yjhmelody]

Is there any way to bootstrap? Use this crate to improve documentation for itself.

[sam0x17]

Yeah I'm planning to make use of the new features within docify as they get added. The tricky thing is it's not actually possible to use all of docify fully within docify at least on the macro side of the crate because you end up with a circular dependency. This is why most of the tests are hoisted to the top level of the crate.

[kianenigma]

similar issue https://github.com/mersinvald/aquamarine/issues/5

[sam0x17]

btw, yes it seems to be a fundamental issue in rust atm that you can't generate an inner attribute from a macro. If we could write custom inner attributes this would be different, but we cannot.

even if you put a macro like this in another crate:

macro_rules! my_macro {
    () => {
        //! hey 
    }
}

and then in the main crate call foo::my_macro!(); as the first line, it won't work because the macro invocation itself already puts us in item position, and there is no way to do custom inner attributes

update: MIGHT be possible if we remove the semi-colon and try to force the macro to not be item position

error: macro rhs must be delimited
 --> bar/src/lib.rs:3:11
  |
3 |     () => //! hey
  |           ^^^^^^^

error: could not document `bar`

so decl macros can't do it, will try proc

nope, totally impossible:

#[proc_macro]
pub fn my_macro(_: TokenStream) -> TokenStream {
    "//! hey".parse().unwrap()
}

bar::my_macro!()

bar::my_macro! {}

bar::my_macro!();

error[E0753]: expected outer doc comment
 --> src/lib.rs:1:1
  |
1 | bar::my_macro! {}
  | ^^^^^^^^^^^^^^^^^

error: macros that expand to items must be delimited with braces or followed by a semicolon
 --> src/lib.rs:1:15
  |
1 | bar::my_macro!()
  |               ^^

error: expected item after doc comment
 --> src/lib.rs:1:1
  |
1 | bar::my_macro!();
  | ^^^^^^^^^^^^^^^^ this doc comment doesn't document anything
  |
  = note: this error originates in the macro `bar::my_macro` (in Nightly builds, run with -Z macro-backtrace for more info)