yard 0.2.1 → 0.2.2

data/bin/yri

@@ -1,4 +1,13 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
 require File.dirname(__FILE__) + '/../lib/yard'
-require File.dirname(__FILE__) + '/../lib/quick_doc'
-YARD::QuickDoc.new(ARGV[0])
+
+YARD::Registry.load
+
+object = YARD::Registry.at(ARGV[0])
+options = {
+  :format => :text, 
+  :template => :default, 
+  :serializer => YARD::Serializers::ProcessSerializer.new('less')
+}
+
+YARD::Generators::QuickDocGenerator.new(options).generate(object)

data/lib/yard.rb

@@ -1,8 +1,13 @@
 module YARD
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
+  ROOT = File.dirname(__FILE__)
+  TEMPLATE_ROOT = File.join(File.dirname(__FILE__), '..', 'templates')
+  
+  def self.parse(*args) Parser::SourceParser.parse(*args) end
 end
 
-require File.dirname(__FILE__) + '/extra'
-require File.dirname(__FILE__) + '/logger'
-require File.dirname(__FILE__) + '/namespace'
-require File.dirname(__FILE__) + '/source_parser'
+$:.unshift(YARD::ROOT)
+
+files  = ['yard/logging', 'yard/autoload']
+files += Dir.glob File.join(YARD::ROOT, 'yard/core_ext/*')
+files.each {|file| require file.gsub(/\.rb$/, '') }

data/lib/yard/autoload.rb

@@ -0,0 +1,116 @@
+module YARD
+  module CLI
+    autoload :YardGraph,  'yard/cli/yard_graph.rb'
+    autoload :Yardoc,     'yard/cli/yardoc.rb'
+  end
+  
+  module CodeObjects
+    autoload :Base,                 'yard/code_objects/base'
+    autoload :CodeObjectList,       'yard/code_objects/base'
+    autoload :ClassObject,          'yard/code_objects/class_object'
+    autoload :ClassVariableObject,  'yard/code_objects/class_variable_object'
+    autoload :ConstantObject,       'yard/code_objects/constant_object'
+    autoload :MethodObject,         'yard/code_objects/method_object'
+    autoload :ModuleObject,         'yard/code_objects/module_object'
+    autoload :NamespaceObject,      'yard/code_objects/namespace_object'
+    autoload :Proxy,                'yard/code_objects/proxy'
+    autoload :ProxyMethodError,     'yard/code_objects/proxy'
+    autoload :RootObject,           'yard/code_objects/root_object'
+    
+    autoload :BUILTIN_ALL,          'yard/code_objects/base'
+    autoload :BUILTIN_CLASSES,      'yard/code_objects/base'
+    autoload :BUILTIN_MODULES,      'yard/code_objects/base'
+    autoload :BUILTIN_EXCEPTIONS,   'yard/code_objects/base'
+    autoload :CONSTANTMATCH,        'yard/code_objects/base'
+    autoload :ISEP,                 'yard/code_objects/base'
+    autoload :METHODMATCH,          'yard/code_objects/base'
+    autoload :METHODNAMEMATCH,      'yard/code_objects/base'
+    autoload :NAMESPACEMATCH,       'yard/code_objects/base'
+    autoload :NSEP,                 'yard/code_objects/base'
+  end
+  
+  module Generators
+    module Helpers
+      autoload :BaseHelper,             'yard/generators/helpers/base_helper'
+      autoload :FilterHelper,           'yard/generators/helpers/filter_helper'
+      autoload :HtmlHelper,             'yard/generators/helpers/html_helper'
+      autoload :MethodHelper,           'yard/generators/helpers/method_helper'
+      autoload :UMLHelper,              'yard/generators/helpers/uml_helper'
+    end
+    
+    autoload :AttributesGenerator,      'yard/generators/attributes_generator'
+    autoload :Base,                     'yard/generators/base'
+    autoload :ClassGenerator,           'yard/generators/class_generator'
+    autoload :ConstantsGenerator,       'yard/generators/constants_generator'
+    autoload :ConstructorGenerator,     'yard/generators/constructor_generator'
+    autoload :DeprecatedGenerator,      'yard/generators/deprecated_generator'
+    autoload :DocstringGenerator,       'yard/generators/docstring_generator'
+    autoload :FullDocGenerator,         'yard/generators/full_doc_generator'
+    autoload :InheritanceGenerator,     'yard/generators/inheritance_generator'
+    autoload :MethodGenerator,          'yard/generators/method_generator'
+    autoload :MethodDetailsGenerator,   'yard/generators/method_details_generator'
+    autoload :MethodListingGenerator,   'yard/generators/method_listing_generator'
+    autoload :MethodMissingGenerator,   'yard/generators/method_missing_generator'
+    autoload :MethodSignatureGenerator, 'yard/generators/method_signature_generator'
+    autoload :MethodSummaryGenerator,   'yard/generators/method_summary_generator'
+    autoload :MixinsGenerator,          'yard/generators/mixins_generator'
+    autoload :ModuleGenerator,          'yard/generators/module_generator'
+    autoload :QuickDocGenerator,        'yard/generators/quick_doc_generator'
+    autoload :SourceGenerator,          'yard/generators/source_generator'
+    autoload :TagsGenerator,            'yard/generators/tags_generator'
+    autoload :UMLGenerator,             'yard/generators/uml_generator'
+    autoload :VisibilityGroupGenerator, 'yard/generators/visibility_group_generator'
+  end
+  
+  module Handlers
+    autoload :AliasHandler,         'yard/handlers/alias_handler'
+    autoload :AttributeHandler,     'yard/handlers/attribute_handler'
+    autoload :Base,                 'yard/handlers/base'
+    autoload :ClassHandler,         'yard/handlers/class_handler'
+    autoload :ClassVariableHandler, 'yard/handlers/class_variable_handler'
+    autoload :ConstantHandler,      'yard/handlers/constant_handler'
+    autoload :ExceptionHandler,     'yard/handlers/exception_handler'
+    autoload :MethodHandler,        'yard/handlers/method_handler'
+    autoload :MixinHandler,         'yard/handlers/mixin_handler'
+    autoload :ModuleHandler,        'yard/handlers/module_handler'
+    autoload :VisibilityHandler,    'yard/handlers/visibility_handler'
+    autoload :UndocumentableError,  'yard/handlers/base'
+    autoload :YieldHandler,         'yard/handlers/yield_handler'
+  end
+
+  module Parser
+    module RubyToken
+      require 'yard/parser/ruby_lex' # Too much to include manually
+    end
+    
+    autoload :SourceParser,   'yard/parser/source_parser'
+    autoload :Statement,      'yard/parser/statement'
+    autoload :StatementList,  'yard/parser/statement_list'
+    autoload :TokenList,      'yard/parser/token_list'
+  end
+  
+  module Rake
+    autoload :YardocTask, 'yard/rake/yardoc_task'
+  end
+  
+  module Serializers
+    autoload :Base,                 'yard/serializers/base'
+    autoload :FileSystemSerializer, 'yard/serializers/file_system_serializer'
+    autoload :ProcessSerializer,    'yard/serializers/process_serializer'
+    autoload :StdoutSerializer,     'yard/serializers/stdout_serializer'
+  end
+  
+  module Tags
+    autoload :DefaultFactory, 'yard/tags/default_factory'
+    autoload :Library,        'yard/tags/library'
+    autoload :Tag,            'yard/tags/tag'
+  end
+
+  autoload :Registry, 'yard/registry'
+end
+
+# Load handlers immediately
+YARD::Handlers.constants.each {|c| YARD::Handlers.const_get(c) }
+
+# P() needs to be loaded right away
+YARD::CodeObjects::Proxy

data/lib/yard/cli/yard_graph.rb

@@ -0,0 +1,86 @@
+require 'optparse'
+
+module YARD
+  module CLI
+    class YardGraph
+      attr_reader :options, :visibilities
+      
+      def self.run(*args) new.run(*args) end
+        
+      def initialize
+        @options = SymbolHash[
+          :format => :dot, 
+          :template => :default, 
+          :serializer => YARD::Serializers::StdoutSerializer.new,
+          :visibility => [:public]
+        ]
+      end
+      
+      def run(*args)
+        optparse(*args)
+        Registry.load
+        Generators::UMLGenerator.new(options).generate Registry.root
+      end
+      
+      private
+      
+      def optparse(*args)
+        opts = OptionParser.new
+
+        opts.separator ""
+        opts.separator "General Options:"
+
+        opts.on('-b', '--db FILE', 'Use a specified .yardoc db to load from or save to. (defaults to .yardoc)') do |yfile|
+          YARD::Registry.yardoc_file = yfile
+        end
+
+        opts.on('--full', 'Full class diagrams (show methods and attributes).') do
+          options[:full] = true
+        end
+
+        opts.on('-d', '--dependencies', 'Show mixins in dependency graph.') do
+          options[:dependencies] = true
+        end
+        
+        opts.on('--no-public', "Don't show public methods. (default shows public)") do 
+          options[:visibility].delete(:public)
+        end
+
+        opts.on('--protected', "Show or don't show protected methods. (default hides protected)") do
+          options[:visibility].push(:protected)
+        end
+
+        opts.on('--private', "Show or don't show private methods. (default hides private)") do 
+          options[:visibility].push(:private) 
+        end
+
+        opts.separator ""
+        opts.separator "Output options:"
+
+        opts.on('--dot [OPTIONS]', 'Send the results direclty to `dot` with optional arguments.') do |dotopts|
+          options[:serializer] = Serializers::ProcessSerializer.new('dot ' + dotopts.to_s)
+        end
+        
+        opts.on('-f', '--file [FILE]', 'Writes output to a file instead of stdout.') do |file|
+          options[:serializer] = Serializers::FileSystemSerializer.new(:basepath => '.', :extension => nil)
+          options[:serializer].instance_eval "def serialized_path(object) #{file.inspect} end"
+        end
+        
+        opts.separator ""
+        opts.separator "Other options:"
+        opts.on_tail('-q', '--quiet', 'Show no warnings') { log.level = Logger::ERROR }
+        opts.on_tail('--verbose', 'Show debugging information') { log.level = Logger::DEBUG }
+        opts.on_tail('-v', '--version', 'Show version.') { puts "yard #{YARD::VERSION}"; exit }
+        opts.on_tail('-h', '--help', 'Show this help.')  { puts opts; exit }
+
+        begin
+          opts.parse!(args)
+        rescue => e
+          STDERR.puts e.message
+          STDERR << "\n" << opts
+          exit
+        end
+      end
+    end
+  end
+end

data/lib/yard/cli/yardoc.rb

@@ -0,0 +1,131 @@
+require 'optparse'
+
+module YARD
+  module CLI
+    class Yardoc
+      attr_reader :options, :visibilities
+      attr_accessor :files, :reload, :generate
+      
+      def self.run(*args) new.run(*args) end
+        
+      def initialize
+        @options = SymbolHash[
+          :format => :html, 
+          :template => :default, 
+          :serializer => YARD::Serializers::FileSystemSerializer.new, 
+          :readme => ['README', 'README.txt'],
+          :verifier => lambda do |gen, obj| 
+            return false if gen.respond_to?(:visibility) && !visibilities.include?(gen.visibility) 
+          end
+        ]
+        @visibilities = [:public]
+        @reload = true
+        @generate = true
+        @files = ['lib/**/*.rb']
+      end
+      
+      def run(*args)
+        optparse(*args)
+        Registry.load(files, reload)
+        
+        if generate
+          Generators::FullDocGenerator.new(options).generate Registry.all(:module, :class)
+        end
+      end
+      
+      private
+      
+      def optparse(*args)
+        serialopts = SymbolHash.new
+        
+        opts = OptionParser.new
+        opts.banner = "Usage: yardoc [options] [source files]"
+
+        opts.separator "(if a list of source files is omitted, lib/**/*.rb is used.)"
+        opts.separator ""
+        opts.separator "General Options:"
+
+        opts.on('-c', '--use-cache [FILE]', 
+                'Use the cached .yardoc db to generate documentation. (defaults to no cache)') do |file|
+          YARD::Registry.yardoc_file = file if file
+          self.reload = false
+        end
+        
+        opts.on('-b', '--db FILE', 'Use a specified .yardoc db to load from or save to. (defaults to .yardoc)') do |yfile|
+          YARD::Registry.yardoc_file = yfile
+        end
+        
+        opts.on('-n', '--no-output', 'Only generate .yardoc database, no documentation.') do
+          self.generate = false
+        end
+        
+        opts.on('-e', '--load FILE', 'A Ruby script to load before the source tree is parsed.') do |file|
+          if !require(file.gsub(/\.rb$/, ''))
+            log.error "The file `#{file}' was already loaded, perhaps you need to specify the absolute path to avoid name collisions."
+            exit
+          end
+        end
+
+        opts.separator ""
+        opts.separator "Output options:"
+  
+        opts.on('--no-public', "Don't show public methods. (default shows public)") do 
+          visibilities.delete(:public)
+        end
+
+        opts.on('--protected', "Show or don't show protected methods. (default hides protected)") do
+          visibilities.push(:protected)
+        end
+
+        opts.on('--private', "Show or don't show private methods. (default hides private)") do 
+          visibilities.push(:private) 
+        end
+        
+        opts.on('-r', '--readme FILE', 'The readme file used as the title page of documentation.') do |readme|
+          options[:readme] = readme
+        end
+        
+        opts.on('-d', '--output-dir PATH', 
+                'The output directory. (defaults to ./doc)') do |dir|
+          serialopts[:basepath] = dir
+        end
+
+        opts.on('-t', '--template TEMPLATE', 
+                'The template to use. (defaults to "default")') do |template|
+          options[:template] = template.to_sym
+        end
+
+        opts.on('-p', '--template-path PATH', 
+                'The template path to look for templates in. (used with -t).') do |path|
+          YARD::Generator::Base.register_template_path(path)
+        end
+        
+        opts.on('-f', '--format FORMAT', 
+                'The output format for the template. (defaults to html)') do |format|
+          options[:format] = format
+        end
+
+        opts.separator ""
+        opts.separator "Other options:"
+        opts.on_tail('-q', '--quiet', 'Show no warnings.') { log.level = Logger::ERROR }
+        opts.on_tail('--verbose', 'Show debugging information.') { log.level = Logger::DEBUG }
+        opts.on_tail('-v', '--version', 'Show version.') { puts "yard #{YARD::VERSION}"; exit }
+        opts.on_tail('-h', '--help', 'Show this help.')  { puts opts; exit }
+        
+        begin
+          opts.parse!(args)
+        rescue OptionParser::InvalidOption => e
+          STDERR.puts e.message
+          STDERR << "\n" << opts
+          exit
+        end
+        
+        # Last minute modifications
+        self.files = args unless args.empty?
+        self.reload = false if self.files.empty?
+        visibilities.uniq!
+        options[:serializer] = Serializers::FileSystemSerializer.new(serialopts)
+      end
+    end
+  end
+end

data/lib/yard/code_objects/base.rb

@@ -0,0 +1,321 @@
+module YARD
+  module CodeObjects
+    class CodeObjectList < Array
+      def initialize(owner = Registry.root)
+        @owner = owner
+      end
+      
+      def push(value)
+        value = Proxy.new(@owner, value) if value.is_a?(String) || value.is_a?(Symbol)
+        if value.is_a?(CodeObjects::Base) || value.is_a?(Proxy)
+          super(value) unless include?(value)
+        else
+          raise ArgumentError, "#{value.class} is not a valid CodeObject"
+        end
+        self
+      end
+      alias_method :<<, :push
+    end
+    
+    NSEP = '::'
+    ISEP = '#'
+    CONSTANTMATCH = /[A-Z]\w*/
+    NAMESPACEMATCH = /(?:(?:#{Regexp.quote NSEP})?#{CONSTANTMATCH})+/
+    METHODNAMEMATCH = /[a-zA-Z_]\w*[!?]?|[-+~]\@|<<|>>|=~|===?|[<>]=?|\*\*|[-\/+%^&*~`|]|\[\]=?/
+    METHODMATCH = /(?:(?:#{NAMESPACEMATCH}|self)\s*(?:\.|#{Regexp.quote NSEP})\s*)?#{METHODNAMEMATCH}/
+    
+    BUILTIN_EXCEPTIONS = ["SecurityError", "Exception", "NoMethodError", "FloatDomainError", 
+      "IOError", "TypeError", "NotImplementedError", "SystemExit", "Interrupt", "SyntaxError", 
+      "RangeError", "NoMemoryError", "ArgumentError", "ThreadError", "EOFError", "RuntimeError", 
+      "ZeroDivisionError", "StandardError", "LoadError", "NameError", "LocalJumpError", "SystemCallError", 
+      "SignalException", "ScriptError", "SystemStackError", "RegexpError", "IndexError"]
+    BUILTIN_CLASSES = ["TrueClass", "Array", "Dir", "Struct", "UnboundMethod", "Object", "Fixnum", "Float", 
+      "ThreadGroup", "MatchData", "Proc", "Binding", "Class", "Time", "Bignum", "NilClass", "Symbol", 
+      "Numeric", "String", "Data", "MatchingData", "Regexp", "Integer", "File", "IO", "Range", "FalseClass", 
+      "Method", "Continuation", "Thread", "Hash", "Module"] + BUILTIN_EXCEPTIONS
+    BUILTIN_MODULES = ["ObjectSpace", "Signal", "Marshal", "Kernel", "Process", "GC", "FileTest", "Enumerable", 
+      "Comparable", "Errno", "Precision", "Math", "DTracer"]
+    BUILTIN_ALL = BUILTIN_CLASSES + BUILTIN_MODULES
+    
+    BUILTIN_EXCEPTIONS_HASH = BUILTIN_EXCEPTIONS.inject({}) {|h,n| h.update(n => true) }
+    
+    class Base  
+      attr_reader :name
+      attr_accessor :namespace
+      attr_accessor :source, :signature, :file, :line, :docstring, :dynamic
+      
+      def dynamic?; @dynamic end
+      
+      class << self
+        def new(namespace, name, *args, &block)
+          if name =~ /(?:#{NSEP}|#{ISEP})([^#{NSEP}#{ISEP}]+)$/
+            return new(Proxy.new(namespace, $`), $1, *args, &block)
+          end
+          
+          keyname = namespace && namespace.respond_to?(:path) ? namespace.path : ''
+          if self == RootObject
+            keyname = :root
+          elsif keyname.empty?
+            keyname = name.to_s
+          elsif self == MethodObject
+            keyname += (!args.first || args.first.to_sym == :instance ? ISEP : NSEP) + name.to_s
+          else
+            keyname += NSEP + name.to_s
+          end
+          
+          if self != RootObject && obj = Registry[keyname]
+            yield(obj) if block_given?
+            obj
+          else
+            Registry.objects[keyname] = super(namespace, name, *args, &block)
+          end
+        end
+      end
+          
+      def initialize(namespace, name, *args)
+        if namespace && namespace != :root && 
+            !namespace.is_a?(NamespaceObject) && !namespace.is_a?(Proxy)
+          raise ArgumentError, "Invalid namespace object: #{namespace}"
+        end
+
+        @name = name.to_sym
+        @tags = []
+        @docstring = ""
+        self.namespace = namespace
+        yield(self) if block_given?
+      end
+      
+      def ==(other)
+        if other.is_a?(Proxy)
+          path == other.path
+        else
+          super
+        end
+      end
+      
+      def [](key)
+        if respond_to?(key)
+          send(key)
+        else
+          instance_variable_get("@#{key}")
+        end
+      end
+      
+      def []=(key, value)
+        if respond_to?("#{key}=")
+          send("#{key}=", value)
+        else
+          instance_variable_set("@#{key}", value)
+        end
+      end
+      
+      def method_missing(meth, *args, &block)
+        if meth.to_s =~ /=$/
+          self[meth.to_s[0..-2]] = *args
+        elsif instance_variable_get("@#{meth}")
+          self[meth]
+        else
+          super
+        end
+      end
+
+      ##
+      # Attaches source code to a code object with an optional file location
+      #
+      # @param [Parser::Statement, String] statement 
+      #   the +Parser::Statement+ holding the source code or the raw source 
+      #   as a +String+ for the definition of the code object only (not the block)
+      def source=(statement)
+        if statement.is_a? Parser::Statement
+          src = statement.tokens.to_s
+          blk = statement.block ? statement.block.to_s : ""
+          if src =~ /^def\s.*[^\)]$/ && blk[0,1] !~ /\r|\n/
+            blk = ";" + blk
+          end
+          
+          @source = format_source(src + blk)
+          self.line = statement.tokens.first.line_no
+          self.signature = src
+        else
+          @source = format_source(statement.to_s)
+        end
+      end
+
+      ##
+      # Attaches a docstring to a code oject by parsing the comments attached to the statement
+      # and filling the {#tags} and {#docstring} methods with the parsed information.
+      #
+      # @param [String, Array<String>] comments 
+      #   the comments attached to the code object to be parsed 
+      #   into a docstring and meta tags.
+      def docstring=(comments)
+        @short_docstring = nil
+        parse_comments(comments) if comments
+      end
+      
+      ##
+      # Gets the first line of a docstring to the period or the first paragraph.
+      # 
+      # @return [String] The first line or paragraph of the docstring; always ends with a period.
+      def short_docstring
+        @short_docstring ||= (docstring.split(/\.|\r?\n\r?\n/).first || '')
+        @short_docstring += '.' unless @short_docstring.empty?
+        @short_docstring
+      end
+
+      ##
+      # Default type is the lowercase class name without the "Object" suffix
+      # 
+      # Override this method to provide a custom object type 
+      # 
+      # @return [Symbol] the type of code object this represents
+      def type
+        self.class.name.split(/#{NSEP}/).last.gsub(/Object$/, '').downcase.to_sym
+      end
+    
+      def path
+        if parent && parent != Registry.root
+          [parent.path, name.to_s].join(sep)
+        else
+          name.to_s
+        end
+      end
+      alias_method :to_s, :path
+      
+      def inspect
+        "#<yardoc #{type} #{path}>"
+      end
+    
+      def namespace=(obj)
+        if @namespace
+          @namespace.children.delete(self) 
+          Registry.delete(self)
+        end
+        
+        @namespace = (obj == :root ? Registry.root : obj)
+      
+        if @namespace
+          @namespace.children << self unless @namespace.is_a?(Proxy)
+          Registry.register(self)
+        end
+      end
+    
+      alias_method :parent, :namespace
+      alias_method :parent=, :namespace=
+
+      ## 
+      # Convenience method to return the first tag
+      # object in the list of tag objects of that name
+      #
+      # Example:
+      #   doc = YARD::Documentation.new("@return zero when nil")
+      #   doc.tag("return").text  # => "zero when nil"
+      #
+      # @param [#to_s] name the tag name to return data for
+      # @return [Tags::Tag] the first tag in the list of {#tags}
+      def tag(name)
+        @tags.find {|tag| tag.tag_name.to_s == name.to_s }
+      end
+
+      ##
+      # Returns a list of tags specified by +name+ or all tags if +name+ is not specified.
+      #
+      # @param name the tag name to return data for, or nil for all tags
+      # @return [Array<Tags::Tag>] the list of tags by the specified tag name
+      def tags(name = nil)
+        return @tags if name.nil?
+        @tags.select {|tag| tag.tag_name.to_s == name.to_s }
+      end
+
+      ##
+      # Returns true if at least one tag by the name +name+ was declared
+      #
+      # @param [String] name the tag name to search for
+      # @return [Boolean] whether or not the tag +name+ was declared
+      def has_tag?(name)
+        @tags.any? {|tag| tag.tag_name.to_s == name.to_s }
+      end
+
+      protected
+    
+      def sep; NSEP end
+
+      private
+
+      ##
+      # Parses out comments split by newlines into a new code object
+      #
+      # @param [Array<String>, String] comments 
+      #   the newline delimited array of comments. If the comments
+      #   are passed as a String, they will be split by newlines. 
+      def parse_comments(comments)
+        return if comments.empty?
+        meta_match = /^@(\S+)\s*(.*)/
+        comments = comments.split(/\r?\n/) if comments.is_a? String
+        @tags, @docstring = [], ""
+
+        indent, last_indent = comments.first[/^\s*/].length, 0
+        orig_indent = 0
+        last_line = ""
+        tag_name, tag_klass, tag_buf, raw_buf = nil, nil, "", []
+
+        (comments+['']).each_with_index do |line, index|
+          indent = line[/^\s*/].length 
+          empty = (line =~ /^\s*$/ ? true : false)
+          done = comments.size == index
+
+          if tag_name && (((indent < orig_indent && !empty) || done) || 
+              (indent <= last_indent && line =~ meta_match))
+            tagfactory = Tags::Library.new
+            tag_method = "#{tag_name}_tag"
+            if tag_name && tagfactory.respond_to?(tag_method)
+              if tagfactory.method(tag_method).arity == 2
+                @tags << tagfactory.send(tag_method, tag_buf, raw_buf.join("\n"))
+              else
+                @tags << tagfactory.send(tag_method, tag_buf) 
+              end
+            else
+              log.warn "Unknown tag @#{tag_name} in documentation for `#{path}`"
+            end
+            tag_name, tag_buf, raw_buf = nil, '', []
+            orig_indent = 0
+          end
+
+          # Found a meta tag
+          if line =~ meta_match
+            orig_indent = indent
+            tag_name, tag_buf = $1, $2 
+            raw_buf = [tag_buf.dup]
+          elsif tag_name && indent >= orig_indent && !empty
+            # Extra data added to the tag on the next line
+            last_empty = last_line =~ /^[ \t]*$/ ? true : false
+            
+            if last_empty
+              tag_buf << "\n\n" 
+              raw_buf << ''
+            end
+            
+            tag_buf << line.gsub(/^[ \t]{#{indent}}/, last_empty ? '' : ' ')
+            raw_buf << line.gsub(/^[ \t]{#{orig_indent}}/, '')
+          elsif !tag_name
+            # Regular docstring text
+            @docstring << line << "\n" 
+          end
+
+          last_indent = indent
+          last_line = line
+        end
+
+        # Remove trailing/leading whitespace / newlines
+        @docstring.gsub!(/\A[\r\n\s]+|[\r\n\s]+\Z/, '')
+      end      
+      
+      # Formats source code by removing leading indentation
+      def format_source(source)
+        source.chomp!
+        indent = source.split(/\r?\n/).last[/^([ \t]*)/, 1].length
+        source.gsub(/^[ \t]{#{indent}}/, '')
+      end
+    end
+  end
+end