yard 0.5.5 → 0.5.6

data/docs/WhatsNew.md

@@ -170,6 +170,19 @@ You can now access the "Class List", "Method List" and "File List" with the
 'c', 'm' and 'f' keyboard shortcuts in the default HTML template, allowing
 for keyboard-only navigation around YARD documentation.
 
+API for registering custom parsers (0.5.6)
+------------------------------------------
+
+You can now register parsers for custom source languages by calling the
+following method:
+
+    SourceParser.register_parser_type(:java, MyJavaParser, 'java')
+    
+The parser class MyJavaParser should be a subclass of {YARD::Parser::Base},
+and the last argument is a set of extensions (string, array or regexp). You
+can read more about registering parsers at the {YARD::Parser::SourceParser}
+class documentation.
+
 
 What's New in 0.4.x?
 ====================

data/lib/rubygems_plugin.rb

@@ -1,28 +1,28 @@
 require 'rubygems/specification'
 require 'rubygems/doc_manager'
 
-class Gem::Specification
-  # has_rdoc should not be ignored!
-  overwrite_accessor(:has_rdoc) { @has_rdoc }
-  overwrite_accessor(:has_rdoc=) {|v| @has_rdoc = v }
+unless defined? Gem::DocManager.load_yardoc
+  class Gem::Specification
+    # has_rdoc should not be ignored!
+    overwrite_accessor(:has_rdoc) { @has_rdoc }
+    overwrite_accessor(:has_rdoc=) {|v| @has_rdoc = v }
   
-  def has_yardoc=(value)
-    @has_rdoc = 'yard'
-  end
+    def has_yardoc=(value)
+      @has_rdoc = 'yard'
+    end
   
-  def has_yardoc
-    @has_rdoc == 'yard'
-  end
+    def has_yardoc
+      @has_rdoc == 'yard'
+    end
   
-  undef has_rdoc?
-  def has_rdoc?
-    @has_rdoc && @has_rdoc != 'yard'
-  end
+    undef has_rdoc?
+    def has_rdoc?
+      @has_rdoc && @has_rdoc != 'yard'
+    end
   
-  alias has_yardoc? has_yardoc
-end
+    alias has_yardoc? has_yardoc
+  end
 
-unless defined? Gem::DocManager.load_yardoc
   class Gem::DocManager
     def self.load_yardoc
       require File.dirname(__FILE__) + '/yard'
@@ -76,6 +76,7 @@ unless defined? Gem::DocManager.load_yardoc
 
     def install_ri_yard
       install_ri_yard_orig if @spec.has_rdoc?
+      return if @spec.has_rdoc? == false
       return if @spec.has_yardoc?
       
       self.class.load_yardoc

data/lib/yard.rb

@@ -1,5 +1,5 @@
 module YARD
-  VERSION = "0.5.5"
+  VERSION = "0.5.6"
   ROOT = File.expand_path(File.dirname(__FILE__))
   TEMPLATE_ROOT = File.join(ROOT, '..', 'templates')
   CONFIG_DIR = File.expand_path('~/.yard')

data/lib/yard/autoload.rb

@@ -82,6 +82,7 @@ module YARD
       autoload :MixinHandler,            __p('handlers/ruby/mixin_handler')
       autoload :ModuleHandler,           __p('handlers/ruby/module_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')
     end
@@ -95,6 +96,8 @@ module YARD
   module Parser
     module Ruby # Ruby parsing components.
       module Legacy # Handles Ruby parsing in Ruby 1.8.
+        autoload :RipperParser,   __p('parser/ruby/legacy/ruby_parser')
+        autoload :RubyParser,     __p('parser/ruby/legacy/ruby_parser')
         autoload :RubyToken,      __p('parser/ruby/legacy/ruby_lex')
         autoload :Statement,      __p('parser/ruby/legacy/statement')
         autoload :StatementList,  __p('parser/ruby/legacy/statement_list')
@@ -105,6 +108,7 @@ module YARD
       autoload :RubyParser,        __p('parser/ruby/ruby_parser')
     end
 
+    autoload :Base,                __p('parser/base')
     autoload :CParser,             __p('parser/c_parser')
     autoload :ParserSyntaxError,   __p('parser/source_parser')
     autoload :SourceParser,        __p('parser/source_parser')

data/lib/yard/cli/yardoc.rb

@@ -70,7 +70,8 @@ module YARD
       # @return [void] 
       def run(*args)
         args += support_rdoc_document_file!
-        optparse(*(yardopts + args))
+        optparse(*yardopts)
+        optparse(*args)
         
         if use_cache
           Registry.load
@@ -104,7 +105,7 @@ module YARD
       # Parses the .yardopts file for default yard options
       # @return [void] 
       def yardopts
-        IO.read(options_file).shell_split
+        File.read_binary(options_file).shell_split
       rescue Errno::ENOENT
         []
       end
@@ -325,7 +326,7 @@ module YARD
         end
         
         opts.on('--files FILE1,FILE2,...', 'Any extra comma separated static files to be included (eg. FAQ)') do |files|
-          add_extra_files *files.split(",")
+          add_extra_files(*files.split(","))
         end
 
         opts.on('-m', '--markup MARKUP', 
@@ -344,7 +345,7 @@ module YARD
           serialopts[:basepath] = dir
         end
         
-        opts.on('--charset ENC', 'Character set to use for HTML output (default is utf-8)') do |encoding|
+        opts.on('--charset ENC', 'Character set to use for HTML output (default is system locale)') do |encoding|
           begin
             Encoding.default_external = encoding
           rescue ArgumentError => e

data/lib/yard/cli/yri.rb

@@ -1,3 +1,5 @@
+require 'rbconfig'
+
 module YARD
   module CLI
     # A tool to view documentation in the console like `ri`
@@ -27,9 +29,16 @@ module YARD
       def run(*args)
         optparse(*args)
         
-        @serializer ||= YARD::Serializers::ProcessSerializer.new('less')
+        if Config::CONFIG['host_os'] =~ /mingw|win32/
+          @serializer ||= YARD::Serializers::StdoutSerializer.new
+        else
+          @serializer ||= YARD::Serializers::ProcessSerializer.new('less')
+        end
         
-        if object = find_object(@name)
+        if @name.nil? || @name.strip.empty?
+          print_usage
+          exit(1)
+        elsif object = find_object(@name)
           print_object(object)
         else
           STDERR.puts "No documentation for `#{@name}'"
@@ -39,6 +48,11 @@ module YARD
       
       protected
       
+      def print_usage
+        puts "Usage: yri [options] <Path to object>"
+        puts "See yri --help for more options."
+      end
+      
       def cache_object(name, path)
         return if path == Registry.yardoc_file
         @cache[name] = path
@@ -112,7 +126,8 @@ module YARD
       # @param [Array<String>] args each tokenized argument
       def optparse(*args)
         opts = OptionParser.new
-
+        opts.banner = "Usage: yri [options] <Path to object>"
+        opts.separator "Example: yri String#gsub"
         opts.separator ""
         opts.separator "General Options:"
 

data/lib/yard/code_objects/base.rb

@@ -93,11 +93,11 @@ module YARD
       # The namespace the object is defined in. If the object is in the
       # top level namespace, this is {Registry#root}
       # @return [NamespaceObject] the namespace object
-      attr_accessor :namespace
+      attr_reader :namespace
       
       # The source code associated with the object
       # @return [String, nil] source, if present, or nil
-      attr_accessor :source
+      attr_reader :source
       
       # Language of the source code associated with the object. Defaults to
       # +:ruby+.
@@ -114,7 +114,7 @@ module YARD
       
       # The documentation string associated with the object
       # @return [Docstring] the documentation string
-      attr_accessor :docstring
+      attr_reader :docstring
       
       # Marks whether or not the method is conditionally defined at runtime
       # @return [Boolean] true if the method is conditionally defined at runtime
@@ -194,6 +194,7 @@ module YARD
         @source_type = :ruby
         @tags = []
         @docstring = Docstring.new('', self)
+        @namespace = nil
         self.namespace = namespace
         yield(self) if block_given?
       end
@@ -262,7 +263,7 @@ module YARD
       def [](key)
         if respond_to?(key)
           send(key)
-        else
+        elsif instance_variable_defined?("@#{key}")
           instance_variable_get("@#{key}")
         end
       end

data/lib/yard/code_objects/class_object.rb

@@ -2,7 +2,7 @@ module YARD::CodeObjects
   class ClassObject < NamespaceObject
     # The {ClassObject} that this class object inherits from in Ruby source.
     # @return [ClassObject] a class object that is the superclass of this one
-    attr_accessor :superclass
+    attr_reader :superclass
     
     # Creates a new class object in +namespace+ with +name+
     # 

data/lib/yard/code_objects/constant_object.rb

@@ -4,7 +4,7 @@ module YARD::CodeObjects
   class ConstantObject < Base
     # The source code representing the constant's value
     # @return [String] the value the constant is set to
-    attr_accessor :value
+    attr_reader :value
     
     def value=(value)
       @value = format_source(value)

data/lib/yard/code_objects/method_object.rb

@@ -4,12 +4,12 @@ module YARD::CodeObjects
     # The visibility of the method (+:public:+, +:protected+, +:private+)
     # 
     # @return [Symbol] the method visibility
-    attr_accessor :visibility
+    attr_reader :visibility
     
     # The scope of the method (+:class+ or +:instance+)
     # 
     # @return [Symbol] the scope
-    attr_accessor :scope
+    attr_reader :scope
     
     # Whether the object is explicitly defined in source or whether it was
     # inferred by a handler. For instance, attribute methods are generally
@@ -32,6 +32,7 @@ module YARD::CodeObjects
     # @param [String, Symbol] name the method name
     # @param [Symbol] scope +:instance+ or +:class+
     def initialize(namespace, name, scope = :instance) 
+      @scope = nil
       self.visibility = :public
       self.scope = scope
       self.parameters = []

data/lib/yard/code_objects/namespace_object.rb

@@ -3,9 +3,9 @@ module YARD::CodeObjects
   # The two main Ruby objects that can act as namespaces are modules 
   # ({ModuleObject}) and classes ({ClassObject}).
   class NamespaceObject < Base
-    attr_reader :constants, :meths, :cvars, :mixins, :child
-    attr_reader :class_attributes, :instance_attributes
-    attr_reader :included_constants, :included_meths
+    attr_writer :constants, :cvars, :mixins, :child, :meths
+    attr_writer :class_attributes, :instance_attributes
+    attr_writer :included_constants, :included_meths
 
     # The list of objects defined in this namespace
     # @return [Array<Base>] a list of objects

data/lib/yard/code_objects/proxy.rb

@@ -38,10 +38,14 @@ module YARD
           @imethod = true if name.include? ISEP
           namespace = Proxy.new(namespace, $`) unless $`.empty?
           name = $1
+        else
+          @orignamespace, @origname, @imethod = nil, nil, nil
         end 
         
         @name = name.to_sym
         @namespace = namespace
+        @obj = nil
+        @imethod ||= nil
         
         unless @namespace.is_a?(NamespaceObject) or @namespace.is_a?(Proxy)
           raise ArgumentError, "Invalid namespace object: #{namespace}"

data/lib/yard/docstring.rb

@@ -23,7 +23,7 @@ module YARD
     attr_accessor :line_range
     
     # @return [String] the raw documentation (including raw tag text)
-    attr_accessor :all
+    attr_reader :all
 
     # Matches a tag at the start of a comment line
     META_MATCH = /^@([a-z_]+)(?:\s+(.*))?$/i
@@ -40,6 +40,7 @@ module YARD
     #   with.
     def initialize(content = '', object = nil)
       @object = object
+      @summary = nil
       
       self.all = content
     end
@@ -166,7 +167,7 @@ module YARD
       tag_factory = Tags::Library.instance
       tag_method = "#{tag_name}_tag"
       if tag_name && tag_factory.respond_to?(tag_method)
-        add_tag *tag_factory.send(tag_method, tag_buf)
+        add_tag(*tag_factory.send(tag_method, tag_buf))
       else
         log.warn "Unknown tag @#{tag_name}" + (object ? " in file `#{object.file}` near line #{object.line}" : "")
       end

data/lib/yard/handlers/base.rb

@@ -201,7 +201,7 @@ module YARD
         end
         
         def namespace_only?
-          @namespace_only ? true : false
+          (@namespace_only ||= false) ? true : false
         end
         
         # Generates a +process+ method, equivalent to +def process; ... end+.

data/lib/yard/handlers/ruby/class_condition_handler.rb

@@ -43,7 +43,11 @@ class YARD::Handlers::Ruby::ClassConditionHandler < YARD::Handlers::Ruby::Base
       # *too* dangerous here since code is not actually executed.
       name = statement.condition[0].source
       obj = YARD::Registry.resolve(namespace, name, true)
-      condition = true if obj || Object.instance_eval("defined? #{name}")
+      begin
+        condition = true if obj || Object.instance_eval("defined? #{name}")
+      rescue SyntaxError, NameError
+        condition = false
+      end
     when :var_ref
       var = statement.condition[0]
       if var == s(:kw, "true")

data/lib/yard/handlers/ruby/class_handler.rb

@@ -1,4 +1,5 @@
 class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
+  include YARD::Handlers::Ruby::StructHandlerMethods
   namespace_only
   handles :class, :sclass
   
@@ -6,12 +7,17 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
     if statement.type == :class
       classname = statement[0].source
       superclass = parse_superclass(statement[1])
+      if superclass == "Struct"
+        is_a_struct = true
+        superclass = struct_superclass_name(statement[1]) # refine the superclass if possible
+        create_struct_superclass(superclass, statement[1])
+      end
       undocsuper = statement[1] && superclass.nil?
-
       klass = register ClassObject.new(namespace, classname) do |o|
         o.superclass = superclass if superclass
         o.superclass.type = :class if o.superclass.is_a?(Proxy)
       end
+      parse_struct_superclass(klass, statement[1]) if is_a_struct
       parse_block(statement[2], namespace: klass)
        
       if undocsuper
@@ -48,6 +54,40 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
   
   private
   
+  # Extract the parameters from the Struct.new AST node, returning them as a list
+  # of strings
+  #
+  # @param [MethodCallNode] superclass the AST node for the Struct.new call
+  # @return [Array<String>] the member names to generate methods for
+  def extract_parameters(superclass)
+    members = superclass.parameters.select {|x| x && x.type == :symbol_literal}
+    members.map! {|x| x.source.strip[1..-1]}
+    members
+  end
+  
+  def create_struct_superclass(superclass, superclass_def)
+    return if superclass == "Struct"
+    the_super = register ClassObject.new(P("Struct"), superclass[8..-1]) do |o|
+      o.superclass = "Struct"
+    end
+    parse_struct_superclass(the_super, superclass_def)
+    the_super
+  end
+  
+  def struct_superclass_name(superclass)
+    first = superclass.parameters.first
+    if first.type == :string_literal && first[0].type == :string_content && first[0].size == 1
+      return "Struct::#{first[0][0][0]}"
+    end
+    "Struct"
+  end
+  
+  def parse_struct_superclass(klass, superclass)
+    return unless superclass.parameters
+    members = extract_parameters(superclass)
+    create_attributes(klass, members)
+  end
+  
   def parse_superclass(superclass)
     return nil unless superclass
     

data/lib/yard/handlers/ruby/legacy/class_condition_handler.rb

@@ -43,7 +43,11 @@ class YARD::Handlers::Ruby::Legacy::ClassConditionHandler < YARD::Handlers::Ruby
       # *too* dangerous here since code is not actually executed.
       name = $1
       obj = YARD::Registry.resolve(namespace, name, true)
-      condition = true if obj || Object.instance_eval("defined? #{name}")
+      begin
+        condition = true if obj || Object.instance_eval("defined? #{name}")
+      rescue SyntaxError, NameError
+        condition = false
+      end
     when "true"
       condition = true
     when "false"

data/lib/yard/handlers/ruby/legacy/class_handler.rb

@@ -1,16 +1,24 @@
 class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy::Base
+  include YARD::Handlers::Ruby::StructHandlerMethods
   handles TkCLASS
   
   process do
     if statement.tokens.to_s =~ /^class\s+(#{NAMESPACEMATCH})\s*(?:<\s*(.+)|\Z)/m
       classname = $1
+      superclass_def = $2
       superclass = parse_superclass($2)
+      if superclass == "Struct"
+        is_a_struct = true
+        superclass = struct_superclass_name(superclass_def)
+        create_struct_superclass(superclass, superclass_def)
+      end
       undocsuper = $2 && superclass.nil?
 
       klass = register ClassObject.new(namespace, classname) do |o|
         o.superclass = superclass if superclass
         o.superclass.type = :class if o.superclass.is_a?(Proxy)
       end
+      parse_struct_subclass(klass, superclass_def) if is_a_struct
       parse_block(:namespace => klass)
        
       if undocsuper
@@ -44,6 +52,42 @@ class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy:
   
   private
   
+  # Extracts the parameter list from the Struct.new declaration and returns it
+  # formatted as a list of member names. Expects the user will have used symbols
+  # to define the struct member names
+  #
+  # @param [String] superstring the string declaring the superclass
+  # @return [Array<String>] a list of member names
+  def extract_parameters(superstring)
+    paramstring = superstring.match(/\A(O?Struct)\.new\((.*?)\)/)[2]
+    paramstring.split(",").select {|x| x.strip[0,1] == ":"}.map {|x| x.strip[1..-1] } # the 1..-1 chops the leading :
+  end
+  
+  def create_struct_superclass(superclass, superclass_def)
+    return if superclass == "Struct"
+    the_super = register ClassObject.new(P("Struct"), superclass[8..-1]) do |o|
+      o.superclass = "Struct"
+    end
+    parse_struct_subclass(the_super, superclass_def)
+    the_super
+  end
+  
+  def struct_superclass_name(superclass)
+    paramstring = superclass.match(/\A(Struct)\.new\((.*?)\)/)[2].split(",")
+    first = paramstring.first.strip
+    if first[0,1] =~ /['"]/ && first[-1,1] =~ /['"]/ && first !~ /\#\{/
+      return "Struct::#{first[1..-2]}"
+    end
+    "Struct"
+  end
+  
+  def parse_struct_subclass(klass, superclass_def)
+    # Bounce if there's no parens
+    return unless superclass_def =~ /O?Struct\.new\((.*?)\)/
+    members = extract_parameters(superclass_def)
+    create_attributes(klass, members)
+  end
+  
   def parse_superclass(superclass)
     case superclass
     when /\A(#{NAMESPACEMATCH})(?:\s|\Z)/,