yard 0.2.3.5 → 0.4.0

data/lib/rubygems_plugin.rb

@@ -14,7 +14,6 @@ class Gem::Specification
     @has_rdoc == 'yard'
   end
   
-  undef has_rdoc? # redefining
   def has_rdoc?
     @has_rdoc && @has_rdoc != 'yard'
   end
@@ -43,18 +42,16 @@ class Gem::DocManager
   rescue Errno::EACCES => e
     dirname = File.dirname e.message.split("-")[1].strip
     raise Gem::FilePermissionError.new(dirname)
-  rescue RuntimeError => ex
+  rescue => ex
     alert_error "While generating documentation for #{@spec.full_name}"
     ui.errs.puts "... MESSAGE:   #{ex}"
     ui.errs.puts "... YARDDOC args: #{args.join(' ')}"
-    ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if
-    Gem.configuration.backtrace
+    ui.errs.puts "\t#{ex.backtrace.join("\n\t")}" if Gem.configuration.backtrace
     ui.errs.puts "(continuing with the rest of the installation)"
   ensure
     Dir.chdir(old_pwd)
   end
 
-  undef setup_rdoc # redefining
   def setup_rdoc
     if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then
       raise Gem::FilePermissionError.new(@doc_dir)
@@ -75,21 +72,21 @@ class Gem::DocManager
     run_yardoc '-o', rdoc_dir
   end
 
-  def install_ri_yard
-    @@install_ri_yard_orig.bind(self).call if @spec.has_rdoc?
-  end
-  @@install_ri_yard_orig = instance_method(:install_ri)
-  undef install_ri # redefining
-  alias install_ri install_ri_yard
-  
-  def install_rdoc_yard
-    if @spec.has_rdoc?
-      @@install_rdoc_yard_orig.bind(self).call
-    elsif @spec.has_yardoc?
-      install_yardoc
+  unless instance_methods.include?(:install_ri_yard)
+    def install_ri_yard
+      install_ri_yard_orig if @spec.has_rdoc?
+    end
+    alias install_ri_yard_orig install_ri
+    alias install_ri install_ri_yard
+
+    def install_rdoc_yard
+      if @spec.has_rdoc?
+        install_rdoc_yard_orig
+      elsif @spec.has_yardoc?
+        install_yardoc
+      end
     end
+    alias install_rdoc_yard_orig install_rdoc
+    alias install_rdoc install_rdoc_yard
   end
-  @@install_rdoc_yard_orig = instance_method(:install_rdoc)
-  undef install_rdoc # redefining
-  alias install_rdoc install_rdoc_yard
 end

data/lib/yard.rb

@@ -1,10 +1,48 @@
 module YARD
-  VERSION = "0.2.3.5"
+  VERSION = "0.4.0"
   ROOT = File.dirname(__FILE__)
   TEMPLATE_ROOT = File.join(File.dirname(__FILE__), '..', 'templates')
+  CONFIG_DIR = File.expand_path('~/.yard')
   
+  # An alias to {Parser::SourceParser}'s parsing method
+  # 
+  # @example Parse a glob of files
+  #   YARD.parse('lib/**/*.rb')
+  # @see Parser::SourceParser.parse
   def self.parse(*args) Parser::SourceParser.parse(*args) end
+
+  # An alias to {Parser::SourceParser}'s parsing method
+  # 
+  # @example Parse a string of input
+  #   YARD.parse_string('class Foo; end')
+  # @see Parser::SourceParser.parse_string
   def self.parse_string(*args) Parser::SourceParser.parse_string(*args) end
+  
+  # Loads gems that match the name 'yard-*' (recommended) or 'yard_*' except
+  # those listed in +~/.yard/ignored_plugins+. This is called immediately 
+  # after YARD is loaded to allow plugin support.
+  # 
+  # @return [true] always returns true
+  def self.load_plugins
+    ignored_plugins_file = File.join(CONFIG_DIR, "ignored_plugins")
+    if File.file?(ignored_plugins_file)
+      ignored_plugins = IO.read(ignored_plugins_file).split(/\s+/)
+    else
+      ignored_plugins = []
+    end
+    
+    Gem.source_index.entries.each do |pkgname, gem|
+      begin
+        if gem.name =~ /^yard[-_]/ && !ignored_plugins.include?(gem.name)
+          log.debug "Loading plugin '#{gem.name}'..."
+          require gem.name 
+        end
+      rescue Gem::LoadError, LoadError
+        log.warn "Error loading plugin '#{gem.name}'"
+      end
+    end
+    true
+  end
 end
 
 # Ruby 1.9.2 removes '.' which is not exactly a good idea
@@ -21,3 +59,11 @@ end
 ['autoload', 'globals'].each do |file| 
   require File.join(YARD::ROOT, 'yard', file)
 end
+
+# Load any plugins
+begin
+  require 'rubygems'
+  YARD.load_plugins
+rescue LoadError
+  log.debug "RubyGems is not present, skipping plugin loading"
+end

data/lib/yard/autoload.rb

@@ -1,12 +1,17 @@
+# @private
 def __p(*path) File.join(YARD::ROOT, 'yard', *path) end
 
 module YARD
-  module CLI
+  module CLI # Namespace for command-line interface components
     autoload :YardGraph,  __p('cli/yard_graph')
     autoload :Yardoc,     __p('cli/yardoc')
   end
   
-  module CodeObjects
+  # A "code object" is defined as any entity in the Ruby language.
+  # Classes, modules, methods, class variables and constants are the
+  # major objects, but DSL languages can create their own by inheriting
+  # from {CodeObjects::Base}.
+  module CodeObjects 
     autoload :Base,                 __p('code_objects/base')
     autoload :CodeObjectList,       __p('code_objects/base')
     autoload :ClassObject,          __p('code_objects/class_object')
@@ -35,47 +40,13 @@ module YARD
     autoload :CSEP,                 __p('code_objects/base')
     autoload :CSEPQ,                __p('code_objects/base')
   end
-  
-  module Generators
-    module Helpers
-      autoload :BaseHelper,                 __p('generators/helpers/base_helper')
-      autoload :FilterHelper,               __p('generators/helpers/filter_helper')
-      autoload :HtmlHelper,                 __p('generators/helpers/html_helper')
-      autoload :HtmlSyntaxHighlightHelper,  __p('generators/helpers/html_syntax_highlight_helper')
-      autoload :MarkupHelper,               __p('generators/helpers/markup_helper')
-      autoload :MethodHelper,               __p('generators/helpers/method_helper')
-      autoload :UMLHelper,                  __p('generators/helpers/uml_helper')
-    end
-    
-    autoload :AttributesGenerator,      __p('generators/attributes_generator')
-    autoload :Base,                     __p('generators/base')
-    autoload :ClassGenerator,           __p('generators/class_generator')
-    autoload :ConstantsGenerator,       __p('generators/constants_generator')
-    autoload :ConstructorGenerator,     __p('generators/constructor_generator')
-    autoload :DeprecatedGenerator,      __p('generators/deprecated_generator')
-    autoload :DocstringGenerator,       __p('generators/docstring_generator')
-    autoload :FullDocGenerator,         __p('generators/full_doc_generator')
-    autoload :InheritanceGenerator,     __p('generators/inheritance_generator')
-    autoload :MethodGenerator,          __p('generators/method_generator')
-    autoload :MethodDetailsGenerator,   __p('generators/method_details_generator')
-    autoload :MethodListingGenerator,   __p('generators/method_listing_generator')
-    autoload :MethodMissingGenerator,   __p('generators/method_missing_generator')
-    autoload :MethodSignatureGenerator, __p('generators/method_signature_generator')
-    autoload :MethodSummaryGenerator,   __p('generators/method_summary_generator')
-    autoload :MixinsGenerator,          __p('generators/mixins_generator')
-    autoload :ModuleGenerator,          __p('generators/module_generator')
-    autoload :QuickDocGenerator,        __p('generators/quick_doc_generator')
-    autoload :RootGenerator,            __p('generators/root_generator')
-    autoload :SourceGenerator,          __p('generators/source_generator')
-    autoload :TagsGenerator,            __p('generators/tags_generator')
-    autoload :UMLGenerator,             __p('generators/uml_generator')
-    autoload :VisibilityGroupGenerator, __p('generators/visibility_group_generator')
-    autoload :OverloadsGenerator,       __p('generators/overloads_generator')
-  end
-  
+
+  # Handlers are called during the data processing part of YARD's
+  # parsing phase. This allows YARD as well as any custom extension to
+  # analyze source and generate {CodeObjects} to be stored for later use.
   module Handlers
-    module Ruby
-      module Legacy
+    module Ruby # All Ruby handlers
+      module Legacy # Handlers for old Ruby 1.8 parser
         autoload :Base,                 __p('handlers/ruby/legacy/base')
 
         autoload :AliasHandler,         __p('handlers/ruby/legacy/alias_handler')
@@ -114,9 +85,11 @@ module YARD
     autoload :Processor,                __p('handlers/processor')
   end
 
+  # The parser namespace holds all parsing engines used by YARD. 
+  # Currently only Ruby parsers are implemented with support planned for C.
   module Parser
-    module Ruby
-      module Legacy
+    module Ruby # Ruby parsing components.
+      module Legacy # Handles Ruby parsing in Ruby 1.8.
         autoload :RubyToken,      __p('parser/ruby/legacy/ruby_lex')
         autoload :Statement,      __p('parser/ruby/legacy/statement')
         autoload :StatementList,  __p('parser/ruby/legacy/statement_list')
@@ -132,18 +105,18 @@ module YARD
     autoload :UndocumentableError, __p('parser/source_parser')
   end
   
-  module Rake
+  module Rake # Holds Rake tasks used by YARD
     autoload :YardocTask, __p('rake/yardoc_task')
   end
   
-  module Serializers
+  module Serializers # Namespace for components that serialize to various endpoints
     autoload :Base,                 __p('serializers/base')
     autoload :FileSystemSerializer, __p('serializers/file_system_serializer')
     autoload :ProcessSerializer,    __p('serializers/process_serializer')
     autoload :StdoutSerializer,     __p('serializers/stdout_serializer')
   end
   
-  module Tags
+  module Tags # Namespace for Tag components
     autoload :DefaultFactory, __p('tags/default_factory')
     autoload :DefaultTag,     __p('tags/default_tag')
     autoload :Library,        __p('tags/library')
@@ -154,10 +127,28 @@ module YARD
     autoload :Tag,            __p('tags/tag')
     autoload :TagFormatError, __p('tags/tag_format_error')
   end
+  
+  module Templates # Namespace for templating system
+    module Helpers # Namespace for template helpers
+      autoload :BaseHelper,                 __p('templates/helpers/base_helper')
+      autoload :FilterHelper,               __p('templates/helpers/filter_helper')
+      autoload :HtmlHelper,                 __p('templates/helpers/html_helper')
+      autoload :HtmlSyntaxHighlightHelper,  __p('templates/helpers/html_syntax_highlight_helper' + (RUBY18 ? '18' : ''))
+      autoload :MarkupHelper,               __p('templates/helpers/markup_helper')
+      autoload :MethodHelper,               __p('templates/helpers/method_helper')
+      autoload :ModuleHelper,               __p('templates/helpers/module_helper')
+      autoload :TextHelper,                 __p('templates/helpers/text_helper')
+      autoload :UMLHelper,                  __p('templates/helpers/uml_helper')
+    end
+
+    autoload :Engine,   __p('templates/engine')
+    autoload :Template, __p('templates/template')
+  end
 
   autoload :Docstring, __p('docstring')
   autoload :Logger,    __p('logging')
   autoload :Registry,  __p('registry')
+  autoload :Verifier,  __p('verifier')
 end
 
 undef __p

data/lib/yard/cli/yard_graph.rb

@@ -2,29 +2,52 @@ require 'optparse'
 
 module YARD
   module CLI
+    # A command-line utility to generate Graphviz graphs from
+    # a set of objects
+    # 
+    # @see YardGraph#run
     class YardGraph
-      attr_reader :options, :visibilities
-      attr_reader :objects
+      # The options parsed out of the commandline.
+      # Default options are:
+      #   :format => :dot,
+      #   :visibilities => [:public]
+      attr_reader :options
       
+      # The set of objects to include in the graph.
+      attr_reader :objects
+
+      # Helper method to run the utility on an instance.
+      # @see #run
       def self.run(*args) new.run(*args) end
         
+      # Creates a new instance of the command-line utility
       def initialize
+        @serializer = YARD::Serializers::StdoutSerializer.new
         @options = SymbolHash[
-          :format => :dot, 
-          :template => :default, 
-          :serializer => YARD::Serializers::StdoutSerializer.new,
-          :visibility => [:public]
+          :format => :dot,
+          :visibilities => [:public]
         ]
       end
       
+      # Runs the command-line utility.
+      # 
+      # @example
+      #   grapher = YardGraph.new
+      #   grapher.run('--private')
+      # @param [Array<String>] args each tokenized argument
       def run(*args)
         Registry.load
         optparse(*args)
-        Generators::UMLGenerator.new(options).generate(*objects)
+        
+        contents = objects.map {|o| o.format(options) }.join("\n")
+        Templates::Engine.render(:format => :dot, :type => :layout, 
+          :serializer => @serializer, :contents => contents) 
       end
       
       private
       
+      # Parses commandline options.
+      # @param [Array<String>] args each tokenized argument
       def optparse(*args)
         opts = OptionParser.new
 
@@ -44,27 +67,27 @@ module YARD
         end
         
         opts.on('--no-public', "Don't show public methods. (default shows public)") do 
-          options[:visibility].delete(:public)
+          options[:visibilities].delete(:public)
         end
 
         opts.on('--protected', "Show or don't show protected methods. (default hides protected)") do
-          options[:visibility].push(:protected)
+          options[:visibilities].push(:protected)
         end
 
         opts.on('--private', "Show or don't show private methods. (default hides private)") do 
-          options[:visibility].push(:private) 
+          options[:visibilities].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)
+          @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"
+          @serializer = Serializers::FileSystemSerializer.new(:basepath => '.', :extension => nil)
+          @serializer.instance_eval "def serialized_path(object) #{file.inspect} end"
         end
         
         opts.separator ""

data/lib/yard/cli/yardoc.rb

@@ -3,31 +3,53 @@ require 'optparse'
 module YARD
   module CLI
     class Yardoc
+      # The configuration filename to load extra options from
       DEFAULT_YARDOPTS_FILE = ".yardopts"
       
-      attr_reader :options, :visibilities
-      attr_accessor :files, :reload, :generate
+      # @return [Hash] the hash of options passed to the template.
+      # @see Templates::Engine#render
+      attr_reader :options
+      
+      # @return [Array<String>] list of Ruby source files to process
+      attr_accessor :files
+      
+      # @return [Boolean] whether to reparse the source files even if the 
+      #   .yardoc already exists.
+      attr_accessor :reload
+      
+      # @return [Boolean] whether to generate output
+      attr_accessor :generate
+      
+      # The options file name (defaults to {DEFAULT_YARDOPTS_FILE})
+      # @return [String] the filename to load extra options from
       attr_accessor :options_file
       
+      # Helper method to create an instance and run the utility
+      # @see #run
       def self.run(*args) new.run(*args) end
         
+      # Creates a new instance of the commandline utility
       def initialize
         @options = SymbolHash[
           :format => :html, 
           :template => :default, 
+          :markup => :rdoc,
           :serializer => YARD::Serializers::FileSystemSerializer.new, 
           :files => [],
-          :verifier => lambda do |gen, obj| 
-            return false if gen.respond_to?(:visibility) && !visibilities.include?(gen.visibility) 
-          end
+          :visibilities => [:public],
+          :verifier => nil
         ]
         @files = []
-        @visibilities = [:public]
         @reload = true
         @generate = true
         @options_file = DEFAULT_YARDOPTS_FILE
       end
       
+      # Runs the commandline utility, parsing arguments and generating
+      # output if set.
+      # 
+      # @param [Array<String>] args the list of arguments
+      # @return [nil] 
       def run(*args)
         args += support_rdoc_document_file!
         optparse(*yardopts)
@@ -35,14 +57,22 @@ module YARD
         Registry.load(files, reload)
         
         if generate
-          Generators::FullDocGenerator.new(options).generate(all_objects)
+          Templates::Engine.generate(all_objects, options)
         end
+        
+        true
       end
 
+      # The list of all objects to process. Override this method to change
+      # which objects YARD should generate documentation for.
+      # 
+      # @return [Array<CodeObjects::Base>] a list of code objects to process
       def all_objects
         Registry.all(:root, :module, :class)
       end
       
+      # Parses the .yardopts file for default yard options
+      # @return [nil] 
       def yardopts
         IO.read(options_file).split(/\s+/)
       rescue Errno::ENOENT
@@ -51,12 +81,16 @@ module YARD
       
       private
       
+      # Reads a .document file in the directory to get source file globs
+      # @return [nil] 
       def support_rdoc_document_file!
         IO.read(".document").split(/\s+/)
       rescue Errno::ENOENT
         []
       end
       
+      # Adds a set of extra documentation files to be processed
+      # @param [Array<String>] files the set of documentation files
       def add_extra_files(*files)
         files.map! {|f| f.include?("*") ? Dir.glob(f) : f }.flatten!
         files.each do |file|
@@ -65,6 +99,15 @@ module YARD
         end
       end
       
+      # Parses the file arguments into Ruby files and extra files, which are
+      # separated by a '-' element.
+      # 
+      # @example Parses a set of Ruby source files
+      #   parse_files %w(file1 file2 file3)
+      # @example Parses a set of Ruby files with a separator and extra files
+      #   parse_files %w(file1 file2 - extrafile1 extrafile2)
+      # @param [Array<String>] files the list of files to parse
+      # @return [nil] 
       def parse_files(*files)
         self.files = []
         seen_extra_files_marker = false
@@ -83,7 +126,16 @@ module YARD
         end
       end
       
+      # @param [Array<String>] expressions a list of query expressions to
+      #   turn into a proc
+      def add_verifier(*expressions)
+        
+      end
+      
+      # Parses commandline options.
+      # @param [Array<String>] args each tokenized argument
       def optparse(*args)
+        query_expressions = []
         serialopts = SymbolHash.new
         
         opts = OptionParser.new
@@ -131,21 +183,29 @@ module YARD
         opts.separator "Output options:"
   
         opts.on('--no-public', "Don't show public methods. (default shows public)") do 
-          visibilities.delete(:public)
+          options[:visibilities].delete(:public)
         end
 
         opts.on('--protected', "Show or don't show protected methods. (default hides protected)") do
-          visibilities.push(:protected)
+          options[:visibilities].push(:protected)
         end
 
         opts.on('--private', "Show or don't show private methods. (default hides private)") do 
-          visibilities.push(:private) 
+          options[:visibilities].push(:private) 
+        end
+        
+        opts.on('--no-private', "Hide objects with @private tag") do
+          query_expressions << '!@private'
         end
 
         opts.on('--no-highlight', "Don't highlight code in docs as Ruby.") do 
           options[:no_highlight] = true
         end
         
+        opts.on('--query QUERY', "Only show objects that match a specific query") do |query|
+          query_expressions << query.taint
+        end
+        
         opts.on('--title TITLE', 'Add a specific title to HTML documents') do |title|
           options[:title] = title
         end
@@ -182,7 +242,7 @@ module YARD
 
         opts.on('-p', '--template-path PATH', 
                 'The template path to look for templates in. (used with -t).') do |path|
-          YARD::Generators::Base.register_template_path(path)
+          YARD::Templates::Engine.register_template_path(path)
         end
         
         opts.on('-f', '--format FORMAT', 
@@ -208,8 +268,10 @@ module YARD
         # Last minute modifications
         parse_files(*args) unless args.empty?
         self.files = ['lib/**/*.rb'] if self.files.empty?
-        self.visibilities.uniq!
+        options[:verifier] = Verifier.new(*query_expressions) unless query_expressions.empty?
+        options[:visibilities].uniq!
         options[:serializer] ||= Serializers::FileSystemSerializer.new(serialopts)
+        options[:readme] ||= Dir.glob('README*').first
       end
     end
   end