title: Generating documentation in macros
body: <p>I have a couple of macros to reduce boilerplate when defining certain tuple-structs of the form:</p>
  
  <pre><code>macro_rules! new_type (($name:ident, $bytes:expr) =&gt; (
      pub struct $name(pub [u8; $bytes]);
      // some common operations on $name
  ));
  </code></pre>
  
  <p>However, I would also like to document these new structs. The best thing would be if I could write my documentation right before my macro invocation.</p>
  
  <pre><code>/// A certain type
  new_type!(CertainType, 42);
  </code></pre>
  
  <p>However, Rust won't generate documentation for <code>CertainType</code> when this happens.</p>
  
  <p>Another (not as flexible) alternative would be to do something like:</p>
  
  <pre><code>macro_rules! new_type (($name:ident, $bytes:expr) =&gt; (
      /// Some more generic documentation for $name 
      pub struct $name(pub [u8; $bytes]);
      // some common operations on $name
  ));
  </code></pre>
  
  <p>However, when doing that the Rust macro system doesn't expand the token <code>$name</code> in the documentation comment. The only alternative left is to write very generic documentation in the macro, but that would lead to my library being a lot worse documented than it could be.</p>
  
  <p>What are your recommendations for handling this? The best solution for me would be to be able to write specific documentation for each macro invocation, but if that's not possible I would be grateful for hints on how to expand tokens in documentation comments.</p>