Re-architect around a YARD parser

Start building a YARD parser. Parsing and comment extraction has been moved out
of the yardoc face and into the new `Puppetx::Yardoc::YARD::PuppetParser`
class. The old `Commentor` class from the Util module has been renamed to
`Puppetx::Yardoc::Pops::YARDTransformer`.

`puppet yardoc` is still capable of extracting docstrings for node, class and
type definitions from a single manifest file.

lib/puppet/face/yardoc.rb

@@ -1,5 +1,5 @@
 require 'puppet/face'
-require 'puppetx/yardoc/util'
+require 'puppetx/yardoc/yard/parser'
 
 Puppet::Face.define(:yardoc, '0.0.1') do
 
@@ -18,12 +18,10 @@ Puppet::Face.define(:yardoc, '0.0.1') do
         raise RuntimeError, "The 'rgen' gem must be installed in order to use this face."
       end
 
-      parser = Puppet::Pops::Parser::Parser.new()
+      parser = Puppetx::Yardoc::YARD::PuppetParser.new(File.read(manifest), manifest)
-      parse_result = parser.parse_file(manifest)
+      parser.parse
 
-      commentor = Puppetx::Yardoc::Commentor.new()
+      return parser.enumerator
-
-      return commentor.get_comments(parse_result)
     end
   end
 end

lib/puppetx/yardoc.rb

@@ -0,0 +1,13 @@
+require 'puppetx'
+
+# Nothing to see here except forward declarations.
+module Puppetx::Yardoc
+  # This submodule contains bits that interface with the YARD plugin system.
+  module YARD
+  end
+
+  # This submodule contains bits that operate on the Pops module produced by
+  # the Future parser.
+  module Pops
+  end
+end

lib/puppetx/yardoc/pops/yard_transformer.rb

@@ -1,45 +1,45 @@
-require 'puppetx'
+require 'puppetx/yardoc'
+
 require 'puppet/pops'
 
-# TODO: A catch-all module for now. Everything in here should eventually move
+module Puppetx::Yardoc::Pops
-# to a designated home.
+  # Loosely based on the TreeDumper classes in Pops::Model. The responsibility of
-module Puppetx::Yardoc
+  # this class is to walk a Pops::Model and output objects that can be consumed
-  # Loosly based on the TreeDumper classes in Pops::Model.
+  # by YARD handlers.
-  class Puppetx::Yardoc::Commentor
+  class YARDTransformer
     def initialize
-      @docstring_visitor = Puppet::Pops::Visitor.new(self,'docstring')
+      @transform_visitor = Puppet::Pops::Visitor.new(self, 'transform')
     end
 
-    def get_comments(parse_result)
+    def transform(o)
-      @docstring_visitor.visit(parse_result)
+      @transform_visitor.visit(o)
     end
 
     private
 
-    COMMENT_PATTERN = /^\s*#.*\n/
+    def transform_Factory(o)
-
+      transform(o.current)
-    def comments(o)
-      @docstring_visitor.visit(o)
     end
 
-    def docstring_Factory(o)
+    def transform_Program(o)
-      comments(o.current)
+      # FIXME: Uuuuuughhhhhhhhh.... This should be extracted some other way.
-    end
+      # Perhaps using a SourcePosAdapter?
-
-    def docstring_Program(o)
       @source_text = o.source_text.lines.to_a
       @locator = o.locator
 
-      o.definitions.map{|d| comments(d)}
+      o.definitions.map{|d| transform(d)}
     end
 
     # Extract comments from "Definition" objects. That is: nodes definitions,
     # type definitions and class definitions.
-    def docstring_Definition(o)
+    def transform_Definition(o)
       line = @locator.line_for_offset(o.offset)
       comments_before(line)
     end
 
+    # TODO: This stuff should probably be part of a separate class/adapter.
+    COMMENT_PATTERN = /^\s*#.*\n/
+
     def comments_before(line)
       comments = []
 

lib/puppetx/yardoc/yard/parser.rb

@@ -0,0 +1,29 @@
+require 'puppetx/yardoc'
+
+require 'yard'
+require 'puppet/pops'
+require 'puppetx/yardoc/pops/yard_transformer'
+
+module Puppetx::Yardoc::YARD
+  class PuppetParser < YARD::Parser::Base
+    attr_reader :file, :source
+
+    def initialize(source, filename)
+      @source = source
+      @file = filename
+
+      @parser = Puppet::Pops::Parser::Parser.new()
+      @transformer = Puppetx::Yardoc::Pops::YARDTransformer.new()
+    end
+
+    def parse
+      @parse_result ||= @parser.parse_string(source)
+      self
+    end
+
+    def enumerator
+      @transformer.transform(@parse_result)
+    end
+
+  end
+end