Closed frehberg closed 1 year ago
I was not able to reproduce this based on that description.
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() {}
Quote is behaving correctly as far as I can tell. That #[aquamarine::aquamarine]
must be doing something incorrect.
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 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?