Cache File Overview

The Registry class is a simple, flat-namespace hash where:

• each key is the name (eg, object.path) of a code object
• each value is a code object

The YARD cache file, .yardoc, is basically just a marshalled version
of the Registry class.
It can be loaded by follow-on programs (eg, documentation generators), as:

require 'rubygems'
require 'yard'
require 'yaml'

# load() will accept a file name, but it also has some useful defaults.  For example,
# if no argument is given, it looks for a YARD::Registry::DEFAULT_YARDOC_FILE
# (eg, './.yardoc') file.  If that file is missing, YARD will parse the current directory,
# in order to create one!

YARD::Registry.load('.yardoc')

# Dump the Registry as YAML. (This isn't going to be pretty.)

File.open('.yardoc.yaml', 'w') do |f|
  f.write YARD::Registry.all.to_yaml
# f.write YARD::Registry.instance.to_yaml # preserve keys
end

# Get a sorted list of paths (ie, keys) and print out a few:

paths = YARD::Registry.paths.sort
puts "Found #{paths.size} keys."

paths.each_with_index do |path,ndx|
  obj = YARD::Registry.at(path)
  puts "\n>>> '#{path}'"
  puts "> inspect:    #{obj.inspect}'"
  puts "> dynamic:    #{obj.dynamic.inspect}"
  puts "> file:       #{obj.file}"
  puts "> line:       #{obj.line}"
  puts "> name:       #{obj.name}"
  puts "> namespace:  #{obj.namespace}"
  puts "> signature:  |#{obj.signature}|"
  puts "> type:       #{obj.type}"

  doc  = obj.docstring
  if (doc != '')
    puts "> docstring:"
    puts "'#{doc}'"
  end

  src  = obj.source
  if (src and src != '')
    puts "> source:"
    puts "'#{src}'"
  end

  tags = obj.tags
  if (tags.size > 0)
    puts '> tags:'
    tags.each {|tag| puts "#{tag}" }
  end
  break if (ndx == 1)
end

This will dump the Registry as YAML, then print something like:

Found 651 keys.

>>> '#P'
> inspect:    #<yardoc method #P>'
> dynamic:    nil
> file:       lib/yard/code_objects/proxy.rb
> line:       172
> name:       P
> namespace:  root
> signature:  |def P(namespace, name = nil)|
> type:       method
> docstring:
'Shortcut for creating a YARD::CodeObjects::Proxy 
via a path'
> source:
'def P(namespace, name = nil)
  namespace, name = nil, namespace if name.nil?
  YARD::Registry.resolve(namespace, name, true)
end'
> tags:
#<YARD::Tags::Tag:0x12115dc>
#<YARD::Tags::Tag:0x121158c>

>>> '#log'
> inspect:    #<yardoc method #log>'
> dynamic:    nil
> file:       lib/yard/logging.rb
> line:       27
> name:       log
> namespace:  root
> signature:  |def log|
> type:       method
> source:
'def log; YARD.logger end'

However, recursion is really the best way to walk the Registry.
Modules and classes are children of NamespaceObject,
which defines a tree-like structure, supported by parent and children methods.
If you want to traverse the object space parsed out by YARD,
you can get Registry.root (the root namespace) and traverse #children recursively:

require 'rubygems'
require 'yard'

include YARD

def traverse(node = Registry.root, indent = 0)
  # Print contents of node.
  if (node == Registry.root)
    puts 'root'
  else
    if (CodeObjects::MethodObject === node)
      name = node.name(true) # Get method name, with prefix.
    else
      name = node.name
    end
    puts ('| ' * (indent-1)) + '|-- ' + name.to_s +
         " (#{node.type}; #{node.file}:#{node.line})"
  end

  # Traverse children, if there are any.
  if node.respond_to?(:children)
    node.children.each {|child| traverse(child, indent + 1) }
  end
end

Registry.load
traverse

This will produce an indented tree of the form:

root
|-- YARD (module; lib/yard/autoload.rb:1)
| |-- CLI (module; lib/yard/autoload.rb:2)
| | |-- YardGraph (class; lib/yard/cli/yard_graph.rb:5)
| | | |-- #options (method; lib/yard/cli/yard_graph.rb:6)
| | | |-- #visibilities (method; lib/yard/cli/yard_graph.rb:6)
...