<p dir="auto">A (personal) user experience:</p>
<p dir="auto">While looking for matching functionality on <code class="notranslate">str</code>, I went to the following link:</p>
<ul dir="auto">
<li><code class="notranslate">mod str</code>: <a href="https://doc.rust-lang.org/std/str/index.html" rel="nofollow">https://doc.rust-lang.org/std/str/index.html</a></li>
<li>note that this is distinct from primitive <code class="notranslate">str</code>: <a href="https://doc.rust-lang.org/std/primitive.str.html" rel="nofollow">https://doc.rust-lang.org/std/primitive.str.html</a>
<ul dir="auto">
<li>you may not realize that at first glance; see further commentary below</li>
</ul>
</li>
<li>note also that the mod str link occurs first in the search results (primitive second): <a href="https://doc.rust-lang.org/std/str/?search=str" rel="nofollow">https://doc.rust-lang.org/std/str/?search=str</a></li>
</ul>
<p dir="auto">The mod str documentation, at first blush, seems promising; it describes the <code class="notranslate">str</code> type quickly, shows examples of <code class="notranslate">&amp;str</code> and discusses its representation.  It then lists a bunch of structs that seem promising.  Things like <code class="notranslate">struct Matches</code> "created with the method <code class="notranslate">.matches()</code>"</p>
<p dir="auto">But then I see no method list.  And the text "created with the method <code class="notranslate">.matches()</code>" does not have a hyperlink to that method.  Following the link to the page for <code class="notranslate">struct Matches</code> does not help.  (I can imagine reasons why we would not want to flood the embedded identifiers with hyperlinks; I'm just pointing out that one reasonable guess at how to find this method does not work out.)</p>
<p dir="auto">Anyway, perhaps a lot of this confusion would be reduced if, at the very beginning of the documentation for <code class="notranslate">mod str</code>, we included a prominent link to the primitive <code class="notranslate">str</code> documentation page, which <em>does</em> have all of these methods.</p>
<hr>
<p dir="auto">But, there is a twist (which perhaps should be a different bug).</p>
<ul dir="auto">
<li><code class="notranslate">mod str</code>: <a href="https://doc.rust-lang.org/std/str/index.html" rel="nofollow">https://doc.rust-lang.org/std/str/index.html</a></li>
<li>note that this is distinct from primitive <code class="notranslate">str</code>: <a href="https://doc.rust-lang.org/std/primitive.str.html" rel="nofollow">https://doc.rust-lang.org/std/primitive.str.html</a></li>
</ul>
<p dir="auto">Both of these pages start off with the exact same text.  Apart from the respective titles ("Module std::str" versus "Primitive Type str"), there is no visible difference in my web browser which is filling its vertical space on my laptop, because the differences only start after the "Representation" section, and I need to scroll to see that.</p>
<p dir="auto">This is not great, because someone who is following links trying to find the right page after starting from the <code class="notranslate">mod str</code> docs might reasonably think that this link took them <em>back to</em> the <code class="notranslate">mod str</code> docs.</p>
<p dir="auto">There are a number of problems with our current quote_expr!, quote_tokens!, etc. macros. The first one is that they're cloaking/unhygienic. Fixing this is easy--just change the macro definition so that you have to supply an identifier as the first argument.</p>
<p dir="auto">The second problem is that they really shouldn't work in the way that they do.</p>
<p dir="auto">Specifically, these macros currently expand into ASTs that represent calls to the parser, thereby generating an AST. This discards all context/hygiene information, and is also inefficient, since you already <em>have</em> the AST that you're trying to protect.</p>
<p dir="auto">Languages such as Racket just provide a language primitive called "quote-syntax" whose evaluation rule is <em>literally</em> the trivial one--a use of quote-syntax simply evaluates to the AST on the right hand side of the call.</p>
<p dir="auto">What would it take to add this to Rust?</p>
<ol dir="auto">
<li>You'd need a new AST node called (say) quote_expr.</li>
<li>The typechecker would have to know that any quote_ast node trivially has the type ast::expr -- no checking required.</li>
</ol>
<p dir="auto">This should be less than a day of work for someone who really understands the system well. One question is whether you want to duplicate this work for each of the quote_... thingies, or make one that covers them all, with some kind of simple enum.</p>
<p dir="auto">It appears to me that it would also allow us to throw out a huge amount of code--all of the quoting stuff that's in there currently.</p>