Document implementation breaking footnotes in rustdocs

[frehberg]

working with a macro generating rustdoc, it is using macro quote!{ #[doc= ...]) to produce the corresponding tokenstream.

Looking at the result using "cargo expand" the generated block is added to rustdoc as block comment using "/* ..../", the following is a minimalistic example, the quoted doc-fragment using block-quote instead of surrounding line-quotes:

/// This is a comment.
///
/// This is a diagram[^1]:
/**
 <script> const x = 1;</script>
*/
/// [^1]: This is a footnote.
pub fn example_with_footnote() {}

This is causing a switch between line-comment style and block-comment-style. The footnote feature is loosing the context and footnote references are not placed correctly.

Instead of

Is there a way to tell quote!{ #[doc=..] } to produce line-comments?

[dtolnay]

I was not able to reproduce this based on that description.

[frehberg]

Many thanks for your time, I am a bit puzzled, you are right, the minimalized example does not show the issue with the block-comment (manually added), but still I can reproduce the issuel with the proc-macro "aquamarine::aquamarine" using quote!

I am not sure now, it might be a rustdoc issue, maybe you can tell me. If the footnote feature is able to cope with the combination of line-comments and block-comments, what might be the issue?

I set up a demonstrator, please execute the following two steps:

git clone https://github.com/frehberg/aquamarine-demo.git; cd aquamarine-demo/; cargo doc

firefox ./target/doc/aquamarine_demo_crate/fn.example_fail_with_aquamarine.html

The browser will show this, the footnote at bottom should not be empty

This issue is related to https://github.com/mersinvald/aquamarine/issues/23

The rustdoc-sources are looking like

#[aquamarine::aquamarine]
/// A function showcasing aquamarine defaults
///
/// This is a diagram[^1]:
/// 
/// ```mermaid
/// graph LR
///     s([Source]) --> a[[aquamarine]]
///     r[[rustdoc]] --> f([Docs w/ Mermaid!])
///     subgraph rustc[Rust Compiler]
///     a -. inject mermaid.js .-> r
///     end
/// ```
/// [^1]: This is a footnote.
pub fn example_fail_with_aquamarine() {}

The macro expansion looks like this

/// A function showcasing aquamarine defaults
///
/// This is a diagram[^1]:
///
///
///<script>window.mermaid || document.write('<script src="../mermaid.min.js"><\/script>')</script>
///<script>window.mermaid || document.write('<script src="../../mermaid.min.js"><\/script>')</script>
///<script>window.mermaid || document.write('<script src="../../../mermaid.min.js"><\/script>')</script>
///<script>window.mermaid || document.write('<script src="../../../../mermaid.min.js"><\/script>')</script>
///<script>window.mermaid || document.write('<script src="../../../../../mermaid.min.js"><\/script>')</script>
///<script>window.mermaid || document.write('<script src="https://unpkg.com/mermaid@9.3.0/dist/mermaid.min.js" crossorigin="anonymous"><\/script>')</script>
/**<script>
    var amrn_mermaid_theme = 'default';
    if(typeof currentTheme !== 'undefined') {
        let docs_theme = currentTheme.href;
        let is_dark = /.*(dark|ayu).*\.css/.test(docs_theme)
        if(is_dark) {
            amrn_mermaid_theme = 'dark'
        }
    } else {
        console.log("currentTheme is undefined, are we not inside rustdoc?");
    }
    mermaid.initialize({'startOnLoad':'true', 'theme': amrn_mermaid_theme, 'logLevel': 3 });
</script>*/
/**<div class="mermaid">
 graph LR
     s([Source]) --> a[[aquamarine]]
     r[[rustdoc]] --> f([Docs w/ Mermaid!])
     subgraph rustc[Rust Compiler]
     a -. inject mermaid.js .-> r
     end
</div>*/
/// [^1]: This is a footnote.
pub fn example_fail_with_aquamarine() {}

[dtolnay]

Quote is behaving correctly as far as I can tell. That #[aquamarine::aquamarine] must be doing something incorrect.