title: Documentation for architecture-specific Golang function
body: <p>I have a function that I would like to provide an assembly implementation for
  on <code>amd64</code> architecture. For the sake of discussion let's just suppose it's an
  <code>Add</code> function, but it's actually more complicated than this. I have the
  assembly version working but my question concerns getting the godoc to display
  correctly. I have a feeling this is currenty impossible, but I wanted to seek
  advice.</p>
  
  <p>Some more details:</p>
  
  <ul>
  <li>The assembly implementation of this function contains only a few
  instructions. In particular, the mere cost of calling the function is a
  significant part of the entire cost.</li>
  <li>It makes use of special instructions (<code>BMI2</code>) therefore can only be used
  following a <code>CPUID</code> capability check.</li>
  </ul>
  
  <p>The implementation is <a href="https://gist.github.com/mmcloughlin/bb80af98cdc45fa11b011db4c94a04a3" rel="nofollow noreferrer">structured like this gist</a>. At a high level:</p>
  
  <ul>
  <li>In the generic (non-<code>amd64</code> case) the function is defined by delegating to
  <code>addGeneric</code>.</li>
  <li>In the <code>amd64</code> case the function is actually a variable, initially set to
  <code>addGeneric</code> but replaced by <code>addAsm</code> in the <code>init</code> function if a <code>cpuid</code>
  check passes.</li>
  </ul>
  
  <p>This approach works. However the godoc output is crappy because in the
  <code>amd64</code> case the function is actually a variable. Note godoc appears to be
  picking up the same build tags as the machine it's running on. I'm not sure
  what <code>godoc.org</code> would do.</p>
  
  <p>Alternatives considered:</p>
  
  <ul>
  <li>The <code>Add</code> function delegates to <code>addImpl</code>. Then we pull some similar trick
  to replace <code>addImpl</code> in the <code>amd64</code> case. The problem with this is (in my
  experiments) Go doesn't seem to be able to inline the call, and the assembly
  is now wrapped in two function calls. Since the assembly is so small already
  this has a noticable impact on performance.</li>
  <li>In the <code>amd64</code> case we define a plain function <code>Add</code> that has the <code>useAsm</code>
  check inside it, and calls one of <code>addGeneric</code> and <code>addAsm</code> depending on the
  result. This would have an even worse impact on performance.</li>
  </ul>
  
  <p>So I guess the questions are:</p>
  
  <ol>
  <li>Is there a better way to structure the code to achieve the performance I
  want, and have it appear properly in documentation.</li>
  <li>If there is no alternative, is there some other way to "trick" godoc?</li>
  </ol>