yard 0.6.8 → 0.7.0

data/lib/yard.rb

@@ -1,29 +1,29 @@
 module YARD
-  VERSION = "0.6.8"
-  
+  VERSION = "0.7.0"
+
   # The root path for YARD source libraries
   ROOT = File.expand_path(File.dirname(__FILE__))
-  
+
   # The root path for YARD builtin templates
   TEMPLATE_ROOT = File.join(ROOT, '..', 'templates')
-  
+
   # @deprecated Use {Config::CONFIG_DIR}
   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
-  
+
   # (see YARD::Config.load_plugins)
   # @deprecated Use {Config.load_plugins}
   def self.load_plugins; YARD::Config.load_plugins end
@@ -37,7 +37,7 @@ begin
   begin; require 'continuation'; rescue LoadError; end
   cc = callcc {|cc| cc }; cc.call if cc
   CONTINUATIONS_SUPPORTED = true
-rescue
+rescue Exception
   CONTINUATIONS_SUPPORTED = false
 end
 
@@ -46,7 +46,10 @@ Dir.glob(File.join(YARD::ROOT, 'yard', 'core_ext', '*.rb')).each do |file|
   require file
 end
 
-['autoload', 'globals'].each do |file| 
+# Backport RubyGems SourceIndex and other classes
+require File.join(YARD::ROOT, 'yard', 'rubygems', 'backports')
+
+['autoload', 'globals'].each do |file|
   require File.join(YARD::ROOT, 'yard', file)
 end
 

data/lib/yard/autoload.rb

@@ -10,30 +10,33 @@ module YARD
     autoload :Gems,           __p('cli/gems')
     autoload :Graph,          __p('cli/graph')
     autoload :Help,           __p('cli/help')
+    autoload :List,           __p('cli/list')
     autoload :Server,         __p('cli/server')
     autoload :Stats,          __p('cli/stats')
     autoload :Yardoc,         __p('cli/yardoc')
     autoload :YRI,            __p('cli/yri')
   end
-  
+
   # 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 
+  module CodeObjects
     autoload :Base,                 __p('code_objects/base')
     autoload :CodeObjectList,       __p('code_objects/base')
     autoload :ClassObject,          __p('code_objects/class_object')
     autoload :ClassVariableObject,  __p('code_objects/class_variable_object')
     autoload :ConstantObject,       __p('code_objects/constant_object')
     autoload :ExtendedMethodObject, __p('code_objects/extended_method_object')
+    autoload :ExtraFileObject,      __p('code_objects/extra_file_object')
+    autoload :MacroObject,          __p('code_objects/macro_object')
     autoload :MethodObject,         __p('code_objects/method_object')
     autoload :ModuleObject,         __p('code_objects/module_object')
     autoload :NamespaceObject,      __p('code_objects/namespace_object')
     autoload :Proxy,                __p('code_objects/proxy')
     autoload :ProxyMethodError,     __p('code_objects/proxy')
     autoload :RootObject,           __p('code_objects/root_object')
-    
+
     autoload :BUILTIN_ALL,          __p('code_objects/base')
     autoload :BUILTIN_CLASSES,      __p('code_objects/base')
     autoload :BUILTIN_MODULES,      __p('code_objects/base')
@@ -66,11 +69,11 @@ module YARD
         autoload :ConstantHandler,        __p('handlers/ruby/legacy/constant_handler')
         autoload :ExceptionHandler,       __p('handlers/ruby/legacy/exception_handler')
         autoload :ExtendHandler,          __p('handlers/ruby/legacy/extend_handler')
+        autoload :MacroHandler,           __p('handlers/ruby/legacy/macro_handler')
         autoload :MethodHandler,          __p('handlers/ruby/legacy/method_handler')
         autoload :MixinHandler,           __p('handlers/ruby/legacy/mixin_handler')
         autoload :ModuleHandler,          __p('handlers/ruby/legacy/module_handler')
         autoload :PrivateConstantHandler, __p('handlers/ruby/legacy/private_constant_handler')
-        autoload :ProcessHandler,         __p('handlers/ruby/legacy/process_handler')
         autoload :VisibilityHandler,      __p('handlers/ruby/legacy/visibility_handler')
         autoload :YieldHandler,           __p('handlers/ruby/legacy/yield_handler')
       end
@@ -85,12 +88,13 @@ module YARD
       autoload :ConstantHandler,          __p('handlers/ruby/constant_handler')
       autoload :ExceptionHandler,         __p('handlers/ruby/exception_handler')
       autoload :ExtendHandler,            __p('handlers/ruby/extend_handler')
+      autoload :MacroHandler,             __p('handlers/ruby/macro_handler')
+      autoload :MacroHandlerMethods,      __p('handlers/ruby/macro_handler_methods')
       autoload :MethodHandler,            __p('handlers/ruby/method_handler')
       autoload :MethodConditionHandler,   __p('handlers/ruby/method_condition_handler')
       autoload :MixinHandler,             __p('handlers/ruby/mixin_handler')
       autoload :ModuleHandler,            __p('handlers/ruby/module_handler')
       autoload :PrivateConstantHandler,   __p('handlers/ruby/private_constant_handler')
-      autoload :ProcessHandler,           __p('handlers/ruby/process_handler')
       autoload :StructHandlerMethods,     __p('handlers/ruby/struct_handler_methods')
       autoload :VisibilityHandler,        __p('handlers/ruby/visibility_handler')
       autoload :YieldHandler,             __p('handlers/ruby/yield_handler')
@@ -100,8 +104,8 @@ 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.
+  # The parser namespace holds all parsing engines used by YARD.
+  # Currently only Ruby and C (Ruby) parsers are implemented.
   module Parser
     module Ruby # Ruby parsing components.
       module Legacy # Handles Ruby parsing in Ruby 1.8.
@@ -123,11 +127,11 @@ module YARD
     autoload :SourceParser,        __p('parser/source_parser')
     autoload :UndocumentableError, __p('parser/source_parser')
   end
-  
+
   module Rake # Holds Rake tasks used by YARD
     autoload :YardocTask, __p('rake/yardoc_task')
   end
-  
+
   module Serializers # Namespace for components that serialize to various endpoints
     autoload :Base,                 __p('serializers/base')
     autoload :FileSystemSerializer, __p('serializers/file_system_serializer')
@@ -135,16 +139,16 @@ module YARD
     autoload :StdoutSerializer,     __p('serializers/stdout_serializer')
     autoload :YardocSerializer,     __p('serializers/yardoc_serializer')
   end
-  
+
   # Namespace for classes and modules that handle serving documentation over HTTP
-  # 
+  #
   # == Implementing a Custom Server
-  # To customize the YARD server, see the {Adapter} and {Router} classes. 
-  # 
+  # To customize the YARD server, see the {Adapter} and {Router} classes.
+  #
   # == Rack Middleware
   # If you want to use the YARD server as a Rack middleware, see the documentation
   # in {RackMiddleware}.
-  # 
+  #
   # @since 0.6.0
   module Server
     require __p('server')
@@ -165,7 +169,7 @@ module YARD
       autoload :SearchCommand,        __p('server/commands/search_command')
       autoload :StaticFileCommand,    __p('server/commands/static_file_command')
     end
-    
+
     autoload :Adapter,                __p('server/adapter')
     autoload :DocServerSerializer,    __p('server/doc_server_serializer')
     autoload :DocServerHelper,        __p('server/doc_server_helper')
@@ -179,7 +183,7 @@ module YARD
     autoload :WebrickAdapter,         __p('server/webrick_adapter')
     autoload :WebrickServlet,         __p('server/webrick_adapter')
   end
-  
+
   module Tags # Namespace for Tag components
     autoload :DefaultFactory, __p('tags/default_factory')
     autoload :DefaultTag,     __p('tags/default_tag')
@@ -191,14 +195,14 @@ module YARD
     autoload :Tag,            __p('tags/tag')
     autoload :TagFormatError, __p('tags/tag_format_error')
   end
-  
+
   # Namespace for templating system
   module Templates
     module Helpers # Namespace for template helpers
       module Markup # Namespace for markup providers
         autoload :RDocMarkup,               __p('templates/helpers/markup/rdoc_markup')
       end
-      
+
       autoload :BaseHelper,                 __p('templates/helpers/base_helper')
       autoload :FilterHelper,               __p('templates/helpers/filter_helper')
       autoload :HtmlHelper,                 __p('templates/helpers/html_helper')

data/lib/yard/cli/command.rb

@@ -4,33 +4,34 @@ module YARD
   module CLI
     # Abstract base class for CLI utilities. Provides some helper methods for
     # the option parser
-    # 
+    #
     # @abstract
     # @since 0.6.0
     class Command
       # Helper method to run the utility on an instance.
       # @see #run
       def self.run(*args) new.run(*args) end
-        
+
       def description; '' end
-          
+
       protected
 
       # Adds a set of common options to the tail of the OptionParser
-      # 
+      #
       # @param [OptionParser] opts the option parser object
       # @return [void]
       def common_options(opts)
         opts.separator ""
         opts.separator "Other options:"
-        opts.on('-e', '--load FILE', 'A Ruby script to load before the source tree is parsed.') do |file|
+        opts.on('-e', '--load FILE', 'A Ruby script to load before running command.') do |file|
           load_script(file)
         end
         opts.on('--plugin PLUGIN', 'Load a YARD plugin (gem with `yard-\' prefix)') do |name|
           # Not actually necessary to load here, this is done at boot in YARD::Config.load_plugins
           # YARD::Config.load_plugin(name)
         end
-        opts.on('--legacy', 'Use old style Ruby parser and handlers. Always on in 1.8.x.') do
+        opts.on('--legacy', 'Use old style Ruby parser and handlers. ',
+                            '  Always on in 1.8.x.') do
           YARD::Parser::SourceParser.parser_type = :ruby18
         end
         opts.on_tail('-q', '--quiet', 'Show no warnings.') { log.level = Logger::ERROR }
@@ -40,9 +41,9 @@ module YARD
         opts.on_tail('-v', '--version', 'Show version.') { puts "yard #{YARD::VERSION}"; exit }
         opts.on_tail('-h', '--help', 'Show this help.')  { puts opts; exit }
       end
-    
+
       # Parses the option and gracefully handles invalid switches
-      # 
+      #
       # @param [OptionParser] opts the option parser object
       # @param [Array<String>] args the arguments passed from input. This
       #   array will be modified.
@@ -52,17 +53,17 @@ module YARD
       rescue OptionParser::InvalidOption => e
         log.warn "Unrecognized/#{e.message}"
       end
-      
+
       # Loads a Ruby script. If +Config.options[:safe_mode]+ is enabled,
       # this method will do nothing.
-      # 
+      #
       # @param [String] file the path to the script to load
       # @since 0.6.2
       def load_script(file)
         return if YARD::Config.options[:safe_mode]
         require(file.gsub(/\.rb$/, ''))
-      rescue LoadError
-        log.error "The file `#{file}' could not be loaded, check the path and try again."
+      rescue LoadError => load_exception
+        log.error "The file `#{file}' could not be loaded:\n#{load_exception}"
         exit
       end
     end

data/lib/yard/cli/command_parser.rb

@@ -2,20 +2,20 @@ module YARD
   module CLI
     # This class parses a command name out of the +yard+ CLI command and calls
     # that command in the form:
-    # 
+    #
     #   $ yard command_name [options]
-    # 
+    #
     # If no command or arguments are specified, or if the arguments immediately
-    # begin with a +--opt+ (not +--help+), the {default_command} will be used 
+    # begin with a +--opt+ (not +--help+), the {default_command} will be used
     # (which itself defaults to +:doc+).
-    # 
+    #
     # == Adding a Command
-    # 
-    # To add a custom command via plugin, create a mapping in {commands} from 
-    # the Symbolic command name to the {Command} class that implements the 
+    #
+    # To add a custom command via plugin, create a mapping in {commands} from
+    # the Symbolic command name to the {Command} class that implements the
     # command. To implement a command, see the documentation for the {Command}
     # class.
-    # 
+    #
     # @see Command
     # @see commands
     # @see default_command
@@ -24,12 +24,12 @@ module YARD
         # @return [Hash{Symbol => Command}] the mapping of command names to
         #   command classes to parse the user command.
         attr_accessor :commands
-        
+
         # @return [Symbol] the default command name to use when no options
-        #   are specified or 
+        #   are specified or
         attr_accessor :default_command
       end
-      
+
       self.commands = SymbolHash[
         :config => Config,
         :diff   => Diff,
@@ -37,24 +37,25 @@ module YARD
         :gems   => Gems,
         :graph  => Graph,
         :help   => Help,
+        :list   => List,
         :ri     => YRI,
         :server => Server,
         :stats  => Stats
       ]
-      
+
       self.default_command = :doc
-      
+
       # Convenience method to create a new CommandParser and call {#run}
       # @return (see #run)
       def self.run(*args) new.run(*args) end
-        
+
       def initialize
         log.show_backtraces = false
       end
-           
+
       # Runs the {Command} object matching the command name of the first
       # argument.
-      # @return [void] 
+      # @return [void]
       def run(*args)
         unless args == ['--help']
           if args.size == 0 || args.first =~ /^-/
@@ -69,18 +70,18 @@ module YARD
         end
         list_commands
       end
-      
+
       private
 
       def commands; self.class.commands end
-      
+
       def list_commands
         puts "Usage: yard <command> [options]"
         puts
         puts "Commands:"
         commands.keys.sort_by {|k| k.to_s }.each do |command_name|
           command = commands[command_name].new
-          puts "%-8s %s" % [command_name, command.description] 
+          puts "%-8s %s" % [command_name, command.description]
         end
       end
     end

data/lib/yard/cli/config.rb

@@ -5,19 +5,19 @@ module YARD
     class Config < Command
       # @return [Symbol, nil] the key to view/edit, if any
       attr_accessor :key
-      
+
       # @return [Array, nil] the list of values to set (or single value), if modifying
       attr_accessor :values
-      
+
       # @return [Boolean] whether to reset the {#key}
       attr_accessor :reset
-      
+
       # @return [Boolean] whether the value being set should be inside a list
       attr_accessor :as_list
-      
+
       # @return [Boolean] whether to append values to existing key
       attr_accessor :append
-      
+
       def initialize
         super
         self.key = nil
@@ -26,11 +26,11 @@ module YARD
         self.append = false
         self.as_list = false
       end
-      
+
       def description
         'Views or edits current global configuration'
       end
-      
+
       def run(*args)
         optparse(*args)
         if key
@@ -43,9 +43,9 @@ module YARD
           list_configuration
         end
       end
-      
+
       private
-      
+
       def modify_item
         if reset
           log.debug "Resetting #{key}"
@@ -58,18 +58,18 @@ module YARD
         end
         YARD::Config.save
       end
-      
+
       def view_item
         log.debug "Viewing #{key}"
         puts YARD::Config.options[key].inspect
       end
-      
+
       def list_configuration
         log.debug "Listing configuration"
         require 'yaml'
         puts YAML.dump(YARD::Config.options).sub(/\A--.*\n/, '').gsub(/\n\n/, "\n")
       end
-      
+
       def encode_values
         if values.size == 1 && !as_list
           encode_value(values.first)
@@ -77,7 +77,7 @@ module YARD
           values.map {|v| encode_value(v) }
         end
       end
-      
+
       def encode_value(value)
         case value
         when /^-?\d+/; value.to_i
@@ -86,7 +86,7 @@ module YARD
         else value
         end
       end
-      
+
       def optparse(*args)
         list = false
         self.as_list = false
@@ -105,24 +105,24 @@ module YARD
         opts.separator "Note that `true` and `false` are reserved words."
         opts.separator ""
         opts.separator "General options:"
-        
+
         opts.on('-l', '--list', 'List current configuration') do
           list = true
         end
         opts.on('-r', '--reset', 'Resets the specific item to default') do
           self.reset = true
         end
-        
+
         opts.separator ""
         opts.separator "Modifying keys:"
-        
+
         opts.on('-a', '--append', 'Appends items to existing key values') do
           self.append = true
         end
         opts.on('--as-list', 'Forces the value(s) to be wrapped in an array') do
           self.as_list = true
         end
-        
+
         common_options(opts)
         parse_options(opts, args)
         args = [] if list
@@ -130,7 +130,7 @@ module YARD
         self.values = args if args.size >= 1
         args
       end
-      
+
     end
   end
 end