From c8d318b161f74fd9e1222988df068236f495a3c0 Mon Sep 17 00:00:00 2001
From: Charlie Sharpsteen <source@sharpsteen.net>
Date: Thu, 22 May 2014 21:02:35 -0700
Subject: [PATCH] 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                     | 10 ++---
 lib/puppetx/yardoc.rb                         | 13 ++++++
 .../{util.rb => pops/yard_transformer.rb}     | 40 +++++++++----------
 lib/puppetx/yardoc/yard/parser.rb             | 29 ++++++++++++++
 4 files changed, 66 insertions(+), 26 deletions(-)
 create mode 100644 lib/puppetx/yardoc.rb
 rename lib/puppetx/yardoc/{util.rb => pops/yard_transformer.rb} (55%)
 create mode 100644 lib/puppetx/yardoc/yard/parser.rb

diff --git a/lib/puppet/face/yardoc.rb b/lib/puppet/face/yardoc.rb
index 5884d17..40e812b 100644
--- a/lib/puppet/face/yardoc.rb
+++ b/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()
-      parse_result = parser.parse_file(manifest)
+      parser = Puppetx::Yardoc::YARD::PuppetParser.new(File.read(manifest), manifest)
+      parser.parse
 
-      commentor = Puppetx::Yardoc::Commentor.new()
-
-      return commentor.get_comments(parse_result)
+      return parser.enumerator
     end
   end
 end
diff --git a/lib/puppetx/yardoc.rb b/lib/puppetx/yardoc.rb
new file mode 100644
index 0000000..2f6d2af
--- /dev/null
+++ b/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
diff --git a/lib/puppetx/yardoc/util.rb b/lib/puppetx/yardoc/pops/yard_transformer.rb
similarity index 55%
rename from lib/puppetx/yardoc/util.rb
rename to lib/puppetx/yardoc/pops/yard_transformer.rb
index ecdc9c2..783be9d 100644
--- a/lib/puppetx/yardoc/util.rb
+++ b/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
-# to a designated home.
-module Puppetx::Yardoc
-  # Loosly based on the TreeDumper classes in Pops::Model.
-  class Puppetx::Yardoc::Commentor
+module Puppetx::Yardoc::Pops
+  # Loosely based on the TreeDumper classes in Pops::Model. The responsibility of
+  # this class is to walk a Pops::Model and output objects that can be consumed
+  # by YARD handlers.
+  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)
-      @docstring_visitor.visit(parse_result)
+    def transform(o)
+      @transform_visitor.visit(o)
     end
 
     private
 
-    COMMENT_PATTERN = /^\s*#.*\n/
-
-    def comments(o)
-      @docstring_visitor.visit(o)
+    def transform_Factory(o)
+      transform(o.current)
     end
 
-    def docstring_Factory(o)
-      comments(o.current)
-    end
-
-    def docstring_Program(o)
+    def transform_Program(o)
+      # FIXME: Uuuuuughhhhhhhhh.... This should be extracted some other way.
+      # Perhaps using a SourcePosAdapter?
       @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 = []
 
diff --git a/lib/puppetx/yardoc/yard/parser.rb b/lib/puppetx/yardoc/yard/parser.rb
new file mode 100644
index 0000000..7b7d367
--- /dev/null
+++ b/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