title: Documenting methods in top-level namespace with YARD
body: <p>I documented some Ruby code using YARD and I am having trouble getting the YARD
  documentation I created for some methods in top-level name space to show up in
  yardoc's HTML output.</p>
  
  <p>My documentation looks essentially the same as the YARD gem's own in
  lib/yard/globals.rb,  with the addition of an <code>@api</code> tag. I did try removing it,
  and ran <code>yardoc</code> without the <code>--api</code> parameter but that didn't help matters.</p>
  
  <p>This is an example:</p>
  
  <pre><code>#!/usr/bin/ruby
  
  # @group PIP Negotiation: Backend and helper methods
  #
  # Deserializes a topology graph in YAML format into the database.
  #
  # @api pip-negotiate
  # @param [String] graph A FleRD graph in YAML format
  # @return [Boolean] status True if graph was deserialized successfully, False otherwise.
  # @return [Integer] gl_id The database ID of the deserialized GraphLabel (nil if deserialization failed).
  # @return [Array] output Standard output channel of flerd-deserialize.rb(1)
  # @return [Array] output Standard error channel of flerd-deserialize.rb(1)
  
  def insert_graph(graph)
    return [ true, 1, ["1"], [""] ]  # Not the actual method body.
  end
  
  # @endgroup
  </code></pre>
  
  <p>When I run <code>yardoc</code> to generate the HTML documentation everything looks fine
  at first:</p>
  
  <pre><code>% yardoc -o pip-negotiate --api pip-negotiate '**/*.rb'                  
  Files:           1
  Modules:         0 (    0 undocumented)
  Classes:         0 (    0 undocumented)
  Constants:       0 (    0 undocumented)
  Methods:         1 (    0 undocumented)
   100.00% documented
  %
  </code></pre>
  
  <p>The generated HTML does not contain any of my documentation though. All it
  contains is a list of methods with the <code>pip-negotiate</code> API tag. You can see for
  yourself here:</p>
  
  <p><a href="http://btw23.de/tmp/pip-negotiate/api/method_list.html" rel="nofollow">http://btw23.de/tmp/pip-negotiate/api/method_list.html</a></p>
  
  <p>What I expected instead was something more like YARD's own documentation on
  top-level methods:</p>
  
  <p><a href="http://rubydoc.info/gems/yard/toplevel" rel="nofollow">http://rubydoc.info/gems/yard/toplevel</a></p>
  
  <p>Is there perhaps any special magic I am missing in my <code>yardoc</code> invocation?</p>
  
  <p>My yardoc version is 0.8.6.2, running on Ruby 1.8.7 (2012-06-29 patchlevel 370) [x86_64-linux]</p>