yard 0.5.6 → 0.5.7

data/ChangeLog

@@ -1,3 +1,116 @@
+2010-06-21  Loren Segal <lsegal@soen.ca>
+
+  * ChangeLog, README.md, lib/yard.rb, yard.gemspec: Bump to version 0.5.7
+
+2010-06-17  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/cli/yardoc.rb, lib/yard/serializers/file_system_serializer.rb,
+  spec/cli/yardoc_spec.rb: Clean up parsing of yardoc options and handle
+  .document files more effectively
+
+  * README.md: Add special installation instructions for some Ubuntu/Debian
+  installations. It is impossible to add rdoc as a dependency, since this will
+  force the RDoc gem to be installed rather than the Ruby stdlib package. It is
+  therefore preferable to install rdoc locally with apt-get on such an OS. 
+  Closes gh-109
+
+2010-06-16  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/parser/ruby/ruby_parser.rb: Don't undef 'on_bodystmt'
+
+  * lib/yard/cli/yardoc.rb: Add Yardoc#parse_arguments method to perform all
+  argument parsing (from CLI,.yardopts,.document) at once
+
+  * lib/yard/registry_store.rb, lib/yard/serializers/yardoc_serializer.rb:
+  Improve StubProxy to implement #hash which removes need for TemporaryObject
+  hack
+
+  * spec/verifier_spec.rb: Add spec for Verifier
+
+  * lib/yard/verifier.rb: Force updating of Verifier
+
+  * templates/default/module/html/item_summary.erb: Show full method name with
+  "=" suffix in method summary listing
+
+  * lib/yard/parser/source_parser.rb: Add documentation for
+  SourceParser.parser_types
+
+  * docs/Parser.md, docs/images/parser-class-diagram.png: Update Parser
+  Architecture documentation  Closes gh-137
+
+  * lib/yard/registry.rb: Update Registry documentation  Closes gh-136
+
+  * lib/yard/parser/source_parser.rb, spec/parser/source_parser_spec.rb:
+  Support list of regex in registered file extensions for parser type (instead
+  of a single Regexp)
+
+  * lib/yard/parser/source_parser.rb: Document parser_type_extensions as
+  @private attr
+
+2010-06-15  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/cli/yardoc.rb, spec/cli/yardoc_spec.rb: Hide methods inside a
+  @private class if --no-private is used.
+
+  * templates/default/tags/text/example.erb: Don't wrap example code in yri.
+  Wrapping would just cause confusion.  Closes gh-71
+
+  * lib/yard/cli/yardoc.rb, lib/yard/verifier.rb, spec/cli/yardoc_spec.rb,
+  spec/verifier_spec.rb: Fix --private and other visibility flags when
+  specified in .yardopts file.  The following changes were made to make this
+  possible: - Generate verifier for visibilities after option parsing is
+  finished. - Add Verifier#add_expressions and Verifier#expressions to allow
+  manipulation of Verifier expressions after it is created. Modifying
+  expressions will recompile the verifier object.  Closes gh-142
+
+  * lib/yard/cli/yard_graph.rb: Update default options documentation for
+  YardGraph
+
+  * lib/yard/code_objects/base.rb, lib/yard/code_objects/proxy.rb,
+  lib/yard/code_objects/root_object.rb, lib/yard/registry_store.rb,
+  spec/registry_spec.rb, spec/serializers/data/serialized_yardoc/checksums,
+  .../data/serialized_yardoc/objects/Foo.dat,
+  .../data/serialized_yardoc/objects/Foo/bar_i.dat,
+  .../data/serialized_yardoc/objects/Foo/baz_i.dat,
+  .../data/serialized_yardoc/objects/root.dat,
+  .../serializers/data/serialized_yardoc/proxy_types,
+  spec/serializers/yardoc_serializer_spec.rb: Improve equality checking on
+  CodeObjects and add #hash/#equal? methods  Closes gh-119
+
+  * lib/yard/registry.rb, spec/registry_spec.rb: Fix "cannot resolve link"
+  warnings for --incremental  Closes gh-70
+
+2010-06-13  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/tags/overload_tag.rb: Only override #to_a in 1.9.x
+
+  * lib/yard/tags/overload_tag.rb: 1.9.2 compatibility fix: add #to_ary and
+  #to_a implementations for splatting a delegate class
+
+  * lib/yard/code_objects/proxy.rb: 1.9.2 compatibility fix: re-implement fix
+  for #to_ary in Proxy in a cleaner way
+
+  * spec/parser/c_parser_spec.rb: 1.9.2 compatibility fix: require
+  'continuation' for CParser spec, since it is not required anywhere else
+
+  * spec/handlers/ruby/legacy/base_spec.rb: 1.9.2 compatibility fix: workaround
+  for RSpec not removing metaprogrammed class after test
+
+  * lib/yard/code_objects/proxy.rb: 1.9.2 compatibility fix: add #to_str as
+  alias for #path
+
+  * lib/yard/code_objects/proxy.rb: 1.9.2 compatibility fix: handle #to_ary
+  calls on Proxy class for #flatten in 1.9.2
+
+  * spec/handlers/ruby/base_spec.rb: 1.9.2 compatibility fix: name resolution
+  behaves differently
+
+  * lib/yard/templates/helpers/html_helper.rb: Fix handling of "!!!lang" code
+  block prefix for RDoc markup
+
+  * lib/yard/parser/c_parser.rb: Fix parsing of call-seq in .c files  Closes
+  gh-135
+
 2010-06-12  Loren Segal <lsegal@soen.ca>
 
   * ChangeLog, README.md, docs/WhatsNew.md, lib/yard.rb, yard.gemspec: Release

data/README.md

@@ -5,12 +5,12 @@ YARD: Yay! A Ruby Documentation Tool
 **IRC**:          [irc://irc.freenode.net/yard](irc.freenode.net / #yard)    
 **Git**:          [http://github.com/lsegal/yard](http://github.com/lsegal/yard)   
 **Author**:       Loren Segal  
-**Contributors**: Nathan Weizenbaum, Yehuda Katz, Denis Defreyne, Postmodern, 
-Michael Edgar    
+**Contributors**: Nathan Weizenbaum, Dann Kubb, Yehuda Katz, Denis Defreyne,    
+Postmodern, Michael Edgar    
 **Copyright**:    2007-2010    
 **License**:      MIT License    
-**Latest Version**: 0.5.6 (codename "The Longest")    
-**Release Date**: May 22nd 2010    
+**Latest Version**: 0.5.7 (codename "The Longest")    
+**Release Date**: June 21st 2010    
 
 Synopsis
 --------
@@ -95,6 +95,25 @@ who would like to reap the benefits of YARD's processing in other forms, such
 as throwing all the documentation into a database. Another useful way of

 exploiting this raw data format would be to write tools that can auto generate
 test cases, for example, or show possible unhandled exceptions in code.

+
+
+Installing
+----------
+
+To install YARD, use the following command:
+
+    $ gem install yard
+    
+(Add `sudo` if you're installing under a POSIX system as root)
+    
+Alternatively, if you've checked the source out directly, you can call 
+`rake install` from the root project directory.
+
+**Important Note for Debian/Ubuntu users:** there's a possible chance your Ruby
+install lacks RDoc, which is occasionally used by YARD to convert markup to HTML. 
+If running `which rdoc` turns up empty, install RDoc by issuing:
+
+    $ sudo apt-get install rdoc
                                                                               
 
 Usage
@@ -224,6 +243,13 @@ More options can be seen by typing `yard-graph --help`, but here is an example:
 Changelog
 ---------
 
+- **June.21.10**: 0.5.7 release
+    - Fixed visibility flag parsing in `yardoc`
+    - Updated Parser Architecture documentation with new SourceParser API
+    - Improved Registry documentation for new load commands
+    - Fix loading of .yardoc file as cache (and preserving aliases)
+    - Fix "lib" directory missing when running YARD on installed gems
+
 - **June.12.10**: 0.5.6 release
     - Bug fixes for RubyGems plugin, `has_rdoc=false` should now work
     - New API for registering custom parsers. See {file:WhatsNew.md}

data/docs/Parser.md

@@ -17,9 +17,11 @@ SourceParser
 ------------
 
 The main class {YARD::Parser::SourceParser} acts as a factory class, instantiating
-the correct parser class given the source type being parsed. This usually involves
-a file extension check, though this can be overriden. Currently, only a Ruby source
-parser is implemented, though future plans include a C parser for Ruby extensions.
+the correct parser class, an implementation of {YARD::Parser::Base}. The selected parser
+is chosen based on either the file extension or by selecting it explicitly (as an argument
+to parsing methods). YARD supports Ruby and C source files, but custom parsers can
+be implemented and registered for various other languages by subclassing `Parser::Base`
+and registering the parser with {YARD::Parser::SourceParser.register_parser_type}.
 
 This factory class should always be used when parsing source files rather than 
 the individual parser classes since it initiates the pipeline that runs the
@@ -46,11 +48,29 @@ used:
 
     YARD::Parser::SourceParser.parse_string("def method(a, b) end")
     
-Because no filename information is given, this method allows the setting of the
-parser type as an argument:
+You can also provide the parser type explicitly as the second argument:
 
-    # Parses a string of C (not implemented)
+    # Parses a string of C
     YARD::Parser::SourceParser.parse_string("int main() { }", :c)
+    
+Note that these two methods are aliased as {YARD.parse} and {YARD.parse_string} for 
+convenience.
+    
+Implementing and Registering a Custom Parser
+--------------------------------------------
+
+To implement a custom parser, subclass {YARD::Parser::Base}. Documentation on which
+abstract methods should be implemented are documented in that class. After the class
+is implemented, it is registered with the {YARD::Parser::SourceParser} factory class
+to be called when a file of the right extension needs to be parsed, or when a user
+selects that parser type explicitly. To register your new parser class, call the 
+method {YARD::Parser::SourceParser.register_parser_type}:
+
+    SourceParser.register_parser_type(:my_parser, MyParser, 'my_parser_ext')
+    
+The last argument can be a single extension, a list of extensions (Array), a single Regexp, or a
+list of Regexps. Do not include the '.' in the extension.
+
 
 The Two Ruby Parser Types
 -------------------------

data/lib/yard.rb

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

data/lib/yard/cli/yard_graph.rb

@@ -7,8 +7,7 @@ module YARD
     class YardGraph < Base
       # The options parsed out of the commandline.
       # Default options are:
-      #   :format => :dot,
-      #   :visibilities => [:public]
+      #   :format => :dot
       attr_reader :options
       
       # The set of objects to include in the graph.

data/lib/yard/cli/yardoc.rb

@@ -36,6 +36,13 @@ module YARD
       # @return [String] the filename to load extra options from
       attr_accessor :options_file
       
+      # Keep track of which visibilities are to be shown
+      # @return [Array<Symbol>] a list of visibilities
+      attr_accessor :visibilities
+      
+      # @return [Boolean] whether to build or rebuild gems
+      attr_accessor :build_gems, :rebuild_gems
+      
       # Helper method to create an instance and run the utility
       # @see #run
       def self.run(*args) new.run(*args) end
@@ -53,11 +60,14 @@ module YARD
           :hide_void_return => false,
           :no_highlight => false, 
           :files => [],
-          :verifier => nil
+          :verifier => Verifier.new
         )
+        @visibilities = [:public]
         @excluded = []
         @files = []
         @use_cache = false
+        @build_gems = false
+        @rebuild_gems = false
         @generate = true
         @incremental = false
         @options_file = DEFAULT_YARDOPTS_FILE
@@ -69,9 +79,7 @@ module YARD
       # @param [Array<String>] args the list of arguments
       # @return [void] 
       def run(*args)
-        args += support_rdoc_document_file!
-        optparse(*yardopts)
-        optparse(*args)
+        parse_arguments(*args)
         
         if use_cache
           Registry.load
@@ -80,7 +88,10 @@ module YARD
         YARD.parse(files, excluded)
         Registry.save(use_cache)
         
-        if generate
+        
+        if build_gems
+          do_build_gems(rebuild_gems)
+        elsif generate
           if incremental
             generate_with_cache(checksums)
           else
@@ -94,6 +105,20 @@ module YARD
         true
       end
       
+      # Parses commandline arguments
+      # @param [Array<String>] args the list of arguments
+      # @return [void]
+      def parse_arguments(*args)
+        optparse(*support_rdoc_document_file!)
+        optparse(*yardopts)
+        optparse(*args)
+
+        # Last minute modifications
+        self.files = ['lib/**/*.rb', 'ext/**/*.c'] if self.files.empty?
+        options[:readme] ||= Dir.glob('README*').first
+        add_visibility_verifier
+      end
+      
       # The list of all objects to process. Override this method to change
       # which objects YARD should generate documentation for.
       # 
@@ -153,8 +178,11 @@ module YARD
       def add_extra_files(*files)
         files.map! {|f| f.include?("*") ? Dir.glob(f) : f }.flatten!
         files.each do |file|
-          raise Errno::ENOENT, "Could not find extra file: #{file}" unless File.file?(file)
-          options[:files] << file
+          if File.file?(file)
+            options[:files] << file
+          else
+            log.warn "Could not find extra file: #{file}"
+          end
         end
       end
       
@@ -168,7 +196,6 @@ module YARD
       # @param [Array<String>] files the list of files to parse
       # @return [void] 
       def parse_files(*files)
-        self.files = []
         seen_extra_files_marker = false
         
         files.each do |file|
@@ -187,7 +214,7 @@ module YARD
       
       # Builds .yardoc files for all non-existing gems
       # @param [Boolean] rebuild Forces rebuild of all gems
-      def build_gems(rebuild = false)
+      def do_build_gems(rebuild = false)
         require 'rubygems'
         Gem.source_index.find_name('').each do |spec|
           reload = true
@@ -207,15 +234,16 @@ module YARD
         exit(0)
       end
       
+      # Adds verifier rule for visibilities
+      # @return [void]
+      def add_visibility_verifier
+        vis_expr = "object.type != :method || #{visibilities.uniq.inspect}.include?(object.visibility)"
+        options[:verifier].add_expressions(vis_expr)
+      end
+      
       # Parses commandline options.
       # @param [Array<String>] args each tokenized argument
       def optparse(*args)
-        excluded = []
-        query_expressions = []
-        visibilities = [:public]
-        do_build_gems, do_rebuild_gems = false, false
-        serialopts = SymbolHash.new
-        
         opts = OptionParser.new
         opts.banner = "Usage: yardoc [options] [source_files [- extra_files]]"
 
@@ -268,12 +296,12 @@ module YARD
         end
         
         opts.on('--build-gems', 'Builds .yardoc files for all gems (implies -n)') do
-          do_build_gems = true
+          self.build_gems = true
         end
 
         opts.on('--re-build-gems', 'Forces building .yardoc files for all gems (implies -n)') do
-          do_build_gems = true
-          do_rebuild_gems = true
+          self.build_gems = true
+          self.rebuild_gems = true
         end
 
         opts.separator ""
@@ -292,7 +320,7 @@ module YARD
         end
         
         opts.on('--no-private', "Hide objects with @private tag") do
-          query_expressions << '!@private'
+          options[:verifier].add_expressions '!object.tag(:private) && !object.namespace.tag(:private)'
         end
 
         opts.on('--no-highlight', "Don't highlight code in docs as Ruby.") do 
@@ -308,7 +336,7 @@ module YARD
         end
         
         opts.on('--query QUERY', "Only show objects that match a specific query") do |query|
-          query_expressions << query.taint
+          options[:verifier].add_expressions(query.taint)
         end
 
         opts.on('--list', 'List objects to standard out (implies -n)') do |format|
@@ -321,8 +349,11 @@ module YARD
         end
 
         opts.on('-r', '--readme FILE', '--main FILE', 'The readme file used as the title page of documentation.') do |readme|
-          raise Errno::ENOENT, readme unless File.file?(readme)
-          options[:readme] = readme
+          if File.file?(readme)
+            options[:readme] = readme
+          else 
+            log.warn "Could not find readme file: #{readme}"
+          end
         end
         
         opts.on('--files FILE1,FILE2,...', 'Any extra comma separated static files to be included (eg. FAQ)') do |files|
@@ -341,8 +372,7 @@ module YARD
         
         opts.on('-o', '--output-dir PATH', 
                 'The output directory. (defaults to ./doc)') do |dir|
-          options[:serializer] = nil
-          serialopts[:basepath] = dir
+          options[:serializer].basepath = dir
         end
         
         opts.on('--charset ENC', 'Character set to use for HTML output (default is system locale)') do |encoding|
@@ -370,15 +400,7 @@ module YARD
 
         common_options(opts)
         parse_options(opts, args)
-        
-        # Last minute modifications
-        build_gems(do_rebuild_gems) if do_build_gems
         parse_files(*args) unless args.empty?
-        self.files = ['lib/**/*.rb', 'ext/**/*.c'] if self.files.empty?
-        query_expressions << "object.type != :method || #{visibilities.uniq.inspect}.include?(object.visibility)"
-        options[:verifier] = Verifier.new(*query_expressions) unless query_expressions.empty?
-        options[:serializer] ||= Serializers::FileSystemSerializer.new(serialopts)
-        options[:readme] ||= Dir.glob('README*').first
       end
     end
   end

data/lib/yard/code_objects/base.rb

@@ -248,13 +248,18 @@ module YARD
       # @param [Base, Proxy] other if other is a {Proxy}, tests if
       #   the paths are equal
       # @return [Boolean] whether or not the objects are considered the same
-      def ==(other)
-        if other.is_a?(Proxy)
+      def equal?(other)
+        if other.is_a?(Base) || other.is_a?(Proxy)
           path == other.path
         else
           super
         end
       end
+      alias == equal?
+      alias eql? equal?
+      
+      # @return [Integer] the object's hash value (for equality checking)
+      def hash; path.hash end
 
       # Accesses a custom attribute on the object
       # @param [#to_s] key the name of the custom attribute

data/lib/yard/code_objects/proxy.rb

@@ -95,6 +95,7 @@ module YARD
         end
       end
       alias to_s path
+      alias to_str path
     
       # @return [Boolean] 
       def is_a?(klass)
@@ -124,13 +125,17 @@ module YARD
       end
       
       # @return [Boolean] 
-      def ==(other)
+      def equal?(other)
         if other.respond_to? :path
           path == other.path
         else
           false
         end
       end
+      alias == equal?
+      
+      # @return [Integer] the object's hash value (for equality checking)
+      def hash; path.hash end
 
       # Returns the class name of the object the proxy is mimicking, if
       # resolved. Otherwise returns +Proxy+. 
@@ -179,7 +184,7 @@ module YARD
           super
         end
       end
-
+      
       # Dispatches the method to the resolved object.
       # 
       # @raise [ProxyMethodError] if the proxy cannot find the real object
@@ -189,7 +194,7 @@ module YARD
         else
           log.warn "Load Order / Name Resolution Problem on #{path}:"
           log.warn "-"
-          log.warn "Something is trying to access the object #{path} before it has been recognized."
+          log.warn "Something is trying to call #{meth} on object #{path} before it has been recognized."
           log.warn "This error usually means that you need to modify the order in which you parse files"
           log.warn "so that #{path} is parsed before methods or other objects attempt to access it."
           log.warn "-"
@@ -208,6 +213,9 @@ module YARD
       def root?; false end
     
       private
+
+      # @note this method fixes a bug in 1.9.2: http://gist.github.com/437136
+      def to_ary; nil end
     
       # Attempts to find the object that this unresolved object
       # references by checking if any objects by this name are

data/lib/yard/code_objects/root_object.rb

@@ -6,6 +6,11 @@ module YARD
       def path; "" end
       def inspect; "#<yardoc root>" end
       def root?; true end
+      def equal?(other)
+        other == :root ? true : super(other)
+      end
+      
+      def hash; :root.hash end
     end
   end
 end

data/lib/yard/parser/c_parser.rb

@@ -199,9 +199,12 @@ module YARD
           comments.shift
         end
         overloads = []
+        seen_data = false
         while comments.first =~ /^\s+(\S.+)/ || comments.first =~ /^\s*$/
           line = comments.shift.strip
+          break if line.empty? && seen_data
           next if line.empty?
+          seen_data = true
           line.sub!(/^\w+[\.#]/, '')
           signature, types = *line.split(/ [-=]> /)
           types = parse_types(object, types)
@@ -221,7 +224,7 @@ module YARD
           when /^\w+\s+(#{CodeObjects::METHODMATCH})\s+(\w+)/
             signature = "#{$1}(#{$2})"
           end
-          next unless signature =~ /^#{CodeObjects::METHODNAMEMATCH}/
+          break unless signature =~ /^#{CodeObjects::METHODNAMEMATCH}/
           signature = signature.rstrip
           overloads << "@overload #{signature}"
           overloads << "  @yield [#{blkparams}]" if blk

data/lib/yard/parser/ruby/ruby_parser.rb

@@ -222,7 +222,6 @@ module YARD
         end
 
         undef on_program
-        undef on_bodystmt
         undef on_assoc_new
         undef on_hash
         undef on_bare_assoc_hash

data/lib/yard/parser/source_parser.rb

@@ -102,10 +102,16 @@ module YARD
         end
         
         # @return [Hash{Symbol=>Object}] a list of registered parser types
+        # @private
+        attr_reader :parser_types
+        undef parser_types
         def parser_types; @@parser_types ||= {} end
         def parser_types=(value) @@parser_types = value end
         
         # @return [Hash] a list of registered parser type extensions
+        # @private
+        attr_reader :parser_type_extensions
+        undef parser_type_extensions
         def parser_type_extensions; @@parser_type_extensions ||= {} end
         def parser_type_extensions=(value) @@parser_type_extensions = value end
 
@@ -115,13 +121,7 @@ module YARD
         # @return [Symbol] the parser type to be used for the extension
         def parser_type_for_extension(extension)
           type = parser_type_extensions.find do |t, exts|
-            if exts.is_a?(Array)
-              exts.include?(extension)
-            elsif exts.is_a?(String)
-              exts == extension
-            elsif exts.is_a?(Regexp)
-              extension =~ exts
-            end
+            [exts].flatten.any? {|ext| ext === extension }
           end
           validated_parser_type(type ? type.first : :ruby)
         end
@@ -131,6 +131,7 @@ module YARD
         # 
         # @param [Symbol] type the parser type to set
         # @return [Symbol] the validated parser type
+        # @private
         def validated_parser_type(type)
           RUBY18 && type == :ruby ? :ruby18 : type
         end

data/lib/yard/registry.rb

@@ -143,11 +143,26 @@ module YARD
       @store.load(file)
     end
     
+    # Loads a yardoc file and forces all objects cached on disk into
+    # memory. Equivalent to calling {#load_yardoc} followed by {#load_all}
+    # 
+    # @param [String] file the yardoc file to load
+    # @return [void]
+    # @see #load_yardoc
+    # @see #load_all
     def load!(file = yardoc_file)
       clear
       @store.load!(file)
     end
     
+    # Forces all objects cached on disk into memory
+    # 
+    # @example Loads all objects from disk
+    #   Registry.load
+    #   Registry.all.count #=> 0
+    #   Registry.load_all
+    #   Registry.all.count #=> 17
+    # @return [void]
     def load_all
       @store.load_all
     end
@@ -160,14 +175,19 @@ module YARD
       @store.save(merge, file)
     end
     
+    # @return [Hash{String => String}] a set of checksums for files
     def checksums
       @store.checksums
     end
     
+    # @param [String] data data to checksum
+    # @return [String] the SHA1 checksum for data
     def checksum_for(data)
       Digest::SHA1.hexdigest(data)
     end
     
+    # Deletes the yardoc file from disk
+    # @return [void]
     def delete_from_disk
       @store.destroy
     end
@@ -302,12 +322,6 @@ module YARD
           end
           namespace = namespace.parent
         end
-
-        # Look for ::name or #name in the root space
-        [CodeObjects::ISEP, CodeObjects::NSEP].each do |s|
-          found = at(s + name)
-          return found if found
-        end
       end
       proxy_fallback ? CodeObjects::Proxy.new(orignamespace, name) : nil
     end
@@ -326,6 +340,7 @@ module YARD
     # @param [CodeObjects::NamespaceObject] namespace the starting namespace
     # @param [String] name the name to look for
     def partial_resolve(namespace, name)
+      return at(name) || at('#' + name) if namespace.root?
       [CodeObjects::NSEP, CodeObjects::CSEP, ''].each do |s|
         next if s.empty? && name =~ /^\w/
         path = name

data/lib/yard/registry_store.rb

@@ -48,6 +48,7 @@ module YARD
       if key == ''
         @store[:root] = value
       else
+        @notfound.delete(key.to_sym)
         @store[key.to_sym] = value 
       end
     end

data/lib/yard/serializers/file_system_serializer.rb

@@ -5,11 +5,19 @@ module YARD
       # @return [String] a base path
       attr_reader :basepath
       
+      def basepath=(value)
+        @basepath = options[:basepath] = value
+      end
+      
       # The extension of the filename (defaults to +html+)
       # 
       # @return [String] the extension of the file. Empty string for no extension.
       attr_reader :extension
       
+      def extension=(value)
+        @extension = options[:extension] = value
+      end
+      
       # Creates a new FileSystemSerializer with options
       # 
       # @option opts [String] :basepath ('doc') the base path to write data to

data/lib/yard/serializers/yardoc_serializer.rb

@@ -1,9 +1,13 @@
 module YARD
+  # Stubs marshal dumps and acts a delegate class for an object by path
+  # 
+  # @private
   class StubProxy
     instance_methods.each {|m| undef_method(m) unless m.to_s =~ /^__|^object_id$/ }
 
     def _dump(depth) @path end
     def self._load(str) new(str) end
+    def hash; @path.hash end
     
     def initialize(path, transient = false) 
       @path = path

data/lib/yard/tags/overload_tag.rb

@@ -35,8 +35,13 @@ module YARD
         object.is_a?(other) || self.class >= other.class || false
       end
       alias kind_of? is_a?
-
+      
       private
+
+      if RUBY19
+        def to_a; nil end 
+        def to_ary; nil end
+      end
       
       def parse_tag(text)
         @signature, text = *text.split(/\r?\n/, 2)

data/lib/yard/templates/helpers/html_helper.rb

@@ -333,7 +333,7 @@ module YARD
         return h(source) if options[:no_highlight]
         
         # handle !!!LANG prefix to send to html_syntax_highlight_LANG
-        if source =~ /\A[ \t]*!!!([\w.+-]+)[ \t]*\r?\n/
+        if source =~ /\A(?:[ \t]*\r?\n)?[ \t]*!!!([\w.+-]+)[ \t]*\r?\n/
           type, source = $1, $'
           source = $'
         end

data/lib/yard/verifier.rb

@@ -31,12 +31,29 @@ module YARD
   #   # Equivalent to:
   #   Verifier.new('@return && @param && @yield')
   class Verifier
+    # @return [Array<String>] a list of all expressions the verifier checks for
+    attr_reader :expressions
+    
+    def expressions=(value)
+      @expressions = value
+      create_method_from_expressions
+    end
+    
     # Creates a verifier from a set of expressions
     # 
     # @param [Array<String>] expressions a list of Ruby expressions to
     #   parse.
     def initialize(*expressions)
-      create_method_from_expressions(expressions.flatten)
+      @expressions = []
+      add_expressions(*expressions)
+    end
+    
+    # Adds a set of expressions and recompiles the verifier
+    # 
+    # @param [Array<String>] expressions a list of expressions
+    # @return [void]
+    def add_expressions(*expressions)
+      self.expressions += expressions.flatten
     end
     
     # Passes any method calls to the object from the {#call}
@@ -87,8 +104,8 @@ module YARD
     # Creates the +__execute+ method by evaluating the expressions
     # as Ruby code
     # @return [void] 
-    def create_method_from_expressions(exprs)
-      expr = exprs.flatten.map {|e| "(#{parse_expression(e)})" }.join(" && ")
+    def create_method_from_expressions
+      expr = expressions.map {|e| "(#{parse_expression(e)})" }.join(" && ")
       
       instance_eval(<<-eof, __FILE__, __LINE__ + 1)
         def __execute; #{expr}; end

data/spec/cli/yardoc_spec.rb

@@ -35,9 +35,18 @@ describe YARD::CLI::Yardoc do
     @yardoc.stub!(:support_rdoc_document_file!).and_return([])
     @yardoc.options_file = "test"
     @yardoc.run
-    @yardoc.options[:serializer].options[:basepath].should == :MYPATH
+    @yardoc.options[:serializer].options[:basepath].should == "MYPATH"
     @yardoc.files.should == ["FILE1", "FILE2"]
   end
+  
+  it "should setup visibility rules as verifier" do
+    methobj = CodeObjects::MethodObject.new(:root, :test) {|o| o.visibility = :private }
+    File.should_receive(:read_binary).with("test").and_return("--private")
+    @yardoc.stub!(:support_rdoc_document_file!).and_return([])
+    @yardoc.options_file = "test"
+    @yardoc.run
+    @yardoc.options[:verifier].call(methobj).should be_true
+  end
 
   it "should use String#shell_split to split .yardopts tokens" do
     optsdata = "foo bar"
@@ -60,7 +69,7 @@ describe YARD::CLI::Yardoc do
     File.should_receive(:read_binary).with(".yardopts").and_return("-o NOTMYPATH")
     @yardoc.stub!(:support_rdoc_document_file!).and_return([])
     @yardoc.run("-o", "MYPATH", "FILE")
-    @yardoc.options[:serializer].options[:basepath].should == :MYPATH
+    @yardoc.options[:serializer].options[:basepath].should == "MYPATH"
     @yardoc.files.should == ["FILE"]
   end
   
@@ -68,8 +77,8 @@ describe YARD::CLI::Yardoc do
     File.should_receive(:read_binary).with(".yardopts").and_return("-o NOTMYPATH")
     @yardoc.stub!(:support_rdoc_document_file!).and_return(["FILE2", "FILE3"])
     @yardoc.run("-o", "MYPATH", "FILE1")
-    @yardoc.options[:serializer].options[:basepath].should == :MYPATH
-    @yardoc.files.should == ["FILE1", "FILE2", "FILE3"]
+    @yardoc.options[:serializer].options[:basepath].should == "MYPATH"
+    @yardoc.files.should == ["FILE2", "FILE3", "FILE1"]
   end
   
   it "should accept extra files if specified after '-' with source files" do
@@ -81,23 +90,29 @@ describe YARD::CLI::Yardoc do
   end
   
   it "should accept files section only containing extra files" do
-    @yardoc.optparse *%w( - LICENSE )
+    @yardoc.stub!(:support_rdoc_document_file!).and_return([])
+    @yardoc.stub!(:yardopts).and_return([])
+    @yardoc.parse_arguments *%w( - LICENSE )
     @yardoc.files.should == %w( lib/**/*.rb ext/**/*.c )
     @yardoc.options[:files].should == %w( LICENSE )
   end
 
   it "should accept globs as extra files" do
+    @yardoc.stub!(:support_rdoc_document_file!).and_return([])
+    @yardoc.stub!(:yardopts).and_return([])
     Dir.should_receive(:glob).with('README*').and_return []
     Dir.should_receive(:glob).with('*.txt').and_return ['a.txt', 'b.txt']
     File.should_receive(:file?).with('a.txt').and_return(true)
     File.should_receive(:file?).with('b.txt').and_return(true)
-    @yardoc.optparse *%w( file1 file2 - *.txt )
+    @yardoc.parse_arguments *%w( file1 file2 - *.txt )
     @yardoc.files.should == %w( file1 file2 )
     @yardoc.options[:files].should == %w( a.txt b.txt )
   end
   
   it "should accept no params and parse lib/**/*.rb ext/**/*.c" do
-    @yardoc.optparse
+    @yardoc.stub!(:support_rdoc_document_file!).and_return([])
+    @yardoc.stub!(:yardopts).and_return([])
+    @yardoc.parse_arguments
     @yardoc.files.should == %w( lib/**/*.rb ext/**/*.c )
   end
   
@@ -117,11 +132,24 @@ describe YARD::CLI::Yardoc do
   
   it "should accept --no-private" do
     obj = mock(:object)
-    obj.should_receive(:tag).ordered.with('private').and_return(true)
+    obj.should_receive(:tag).ordered.with(:private).and_return(true)
     @yardoc.optparse *%w( --no-private )
     @yardoc.options[:verifier].call(obj).should == false
   end
   
+  it "should hide methods inside a 'private' class/module with --no-private" do
+    Registry.clear
+    YARD.parse_string <<-eof
+      # @private
+      class A
+        def foo; end
+      end
+    eof
+    @yardoc.optparse *%w( --no-private )
+    @yardoc.options[:verifier].call(Registry.at('A')).should be_false
+    @yardoc.options[:verifier].call(Registry.at('A#foo')).should be_false
+  end
+  
   it "should accept --default-return" do
     @yardoc.optparse *%w( --default-return XYZ )
     @yardoc.options[:default_return].should == "XYZ"
@@ -151,4 +179,14 @@ describe YARD::CLI::Yardoc do
     @yardoc.use_cache.should == true
     @yardoc.generate.should == true
   end
+  
+  it "should warn if extra file is not found" do
+    log.should_receive(:warn).with(/Could not find extra file: UNKNOWN/)
+    @yardoc.optparse *%w( - UNKNOWN )
+  end
+  
+  it "should warn if readme file is not found" do
+    log.should_receive(:warn).with(/Could not find readme file: UNKNOWN/)
+    @yardoc.optparse *%w( -r UNKNOWN )
+  end
 end

data/spec/handlers/ruby/base_spec.rb

@@ -1,7 +1,7 @@
 require File.dirname(__FILE__) + '/../spec_helper'
 
 describe YARD::Handlers::Ruby::Base, '#valid_handler?' do
-  include YARD::Parser::Ruby; AstNode
+  include YARD::Parser::Ruby; YARD::Parser::Ruby::AstNode
 
   before do
     Handlers::Ruby::Base.stub!(:inherited)

data/spec/handlers/ruby/legacy/base_spec.rb

@@ -17,11 +17,11 @@ describe YARD::Handlers::Ruby::Legacy::Base, "#handles and inheritance" do
     class IgnoredHandler < Handlers::Base
       handles "hello"
     end
-    class NotIgnoredHandler < Handlers::Ruby::Legacy::Base
+    class NotIgnoredHandlerLegacy < Handlers::Ruby::Legacy::Base
       handles "hello"
     end
-    Handlers::Base.stub!(:subclasses).and_return [IgnoredHandler, NotIgnoredHandler]
-    @processor.find_handlers(stmt("hello world")).should == [NotIgnoredHandler]
+    Handlers::Base.stub!(:subclasses).and_return [IgnoredHandler, NotIgnoredHandlerLegacy]
+    @processor.find_handlers(stmt("hello world")).should == [NotIgnoredHandlerLegacy]
   end
 
   it "should handle a string input" do

data/spec/parser/c_parser_spec.rb

@@ -1,4 +1,5 @@
 require File.join(File.dirname(__FILE__), '..', 'spec_helper')
+require 'continuation' unless RUBY18
 
 describe YARD::Parser::CParser do
   before(:all) do

data/spec/parser/source_parser_spec.rb

@@ -50,6 +50,12 @@ describe YARD::Parser::SourceParser do
       Parser::SourceParser.parser_type_for_extension('dabcd').should_not == :my_parser
     end
     
+    it "should find an extension in a list of Regexps" do
+      Parser::SourceParser.register_parser_type(:my_parser, MyParser, [/ab$/, /abc$/])
+      Parser::SourceParser.parser_type_for_extension('dabc').should == :my_parser
+      Parser::SourceParser.parser_type_for_extension('dabcd').should_not == :my_parser
+    end
+    
     it "should find an extension in a String" do
       Parser::SourceParser.register_parser_type(:my_parser, MyParser, "abc")
       Parser::SourceParser.parser_type_for_extension('abc').should == :my_parser

data/spec/registry_spec.rb

@@ -137,6 +137,17 @@ describe YARD::Registry do
       Registry.resolve(yard, "class_hello", false).should be_nil
       Registry.resolve(yard, "class_hello", true).should == cmeth
     end
+    
+    it "should only check 'Path' in lookup on root namespace" do
+      Registry.instance.should_receive(:at).once.with('Test').and_return(true)
+      Registry.resolve(Registry.root, "Test")
+    end
+    
+    it "should not perform lookup by joining namespace and name without separator" do
+      yard = ClassObject.new(:root, :YARD)
+      Registry.instance.should_not_receive(:at).with('YARDB')
+      Registry.resolve(yard, 'B')
+    end
   end
   
   describe '#all' do
@@ -173,15 +184,20 @@ describe YARD::Registry do
   end
   
   describe '#load_yardoc' do
-    before do
-      @store = RegistryStore.new
-      RegistryStore.should_receive(:new).and_return(@store)
-    end
-    
     it "should delegate load to RegistryStore" do
-      @store.should_receive(:load).with('foo')
+      store = RegistryStore.new
+      store.should_receive(:load).with('foo')
+      RegistryStore.should_receive(:new).and_return(store)
       Registry.yardoc_file = 'foo'
       Registry.load_yardoc
     end
+    
+    it "should maintain hash key equality on loaded objects" do
+      Registry.clear
+      Registry.load!(File.dirname(__FILE__) + '/serializers/data/serialized_yardoc')
+      baz = Registry.at('Foo#baz')
+      Registry.at('Foo').aliases.keys.should include(baz)
+      Registry.at('Foo').aliases.has_key?(baz).should == true
+    end
   end
 end

data/spec/serializers/data/serialized_yardoc/checksums

@@ -0,0 +1 @@
+test.rb 80e5834ff1e98223761615c0917ff9b77b7ae057

data/spec/serializers/data/serialized_yardoc/proxy_types

@@ -0,0 +1,2 @@
+{I"Object:EF:
+class

data/spec/serializers/yardoc_serializer_spec.rb

@@ -0,0 +1,35 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+instance_eval do
+  class YARD::Serializers::YardocSerializer
+    public :dump
+    public :internal_dump
+  end
+end
+
+describe YARD::Serializers::YardocSerializer do
+  describe '#dump' do
+    before do
+      @serializer = YARD::Serializers::YardocSerializer.new('.yardoc')
+
+      Registry.clear
+      @foo = CodeObjects::ClassObject.new(:root, :Foo)
+      @bar = CodeObjects::MethodObject.new(@foo, :bar)
+    end
+
+    it "should maintain object equality when loading a dumped object" do
+      newfoo = @serializer.internal_dump(@foo)
+      newfoo.should equal(@foo)
+      newfoo.should == @foo
+      @foo.should equal(newfoo)
+      @foo.should == newfoo
+      newfoo.hash.should == @foo.hash
+    end
+    
+    it "should maintain hash key equality when loading a dumped object" do
+      newfoo = @serializer.internal_dump(@foo)
+      {@foo => 1}.should have_key(newfoo)
+      {newfoo => 1}.should have_key(@foo)
+    end
+  end
+end

data/spec/verifier_spec.rb

@@ -47,5 +47,35 @@ describe YARD::Verifier do
       obj.should_receive(:tag).and_return(nil)
       Verifier.new('@return.text').call(obj).should == false
     end
+    
+    it "should not fail if no expressions were added" do
+      lambda { Verifier.new.call(nil) }.should_not raise_error
+    end
+  end
+  
+  describe '#expressions' do
+    it "should maintain a list of all unparsed expressions" do
+      Verifier.new('@return.text', '@private').expressions.should == ['@return.text', '@private']
+    end
+  end
+
+  describe '#expressions=' do
+    it "should recompile expressions when attribute is modified" do
+      obj = mock(:object)
+      obj.should_receive(:tag).with('return')
+      v = Verifier.new
+      v.expressions = ['@return']
+      v.call(obj)
+    end
+  end
+  
+  describe '#add_expressions' do
+    it "should add new expressions and recompile" do
+      obj = mock(:object)
+      obj.should_receive(:tag).with('return')
+      v = Verifier.new
+      v.add_expressions '@return'
+      v.call(obj)
+    end
   end
 end

data/templates/default/module/html/item_summary.erb

@@ -1,9 +1,9 @@
 <li class="<%= @item.visibility %> <%= @item.has_tag?(:deprecated) ? 'deprecated' : '' %>">
   <span class="summary_signature">
     <% if @item.tags(:overload).size == 1 %>
-      <%= signature(@item.tag(:overload), true, false) %>
+      <%= signature(@item.tag(:overload), true, !@item.attr_info) %>
     <% else %>
-      <%= signature(@item, true, false, false) %>
+      <%= signature(@item, true, false, !@item.attr_info) %>
     <% end %>
 
     <% if @item.aliases.size > 0 %>

data/templates/default/tags/text/example.erb

@@ -4,8 +4,8 @@ Examples:
 ---------
 
 <% object.tags(:example).each_with_index do |tag, i| %>
-<%= indent(wrap("# " + tag.name)) if tag.name %>
-<%= indent(wrap(format_source(tag.text))) %>
+<%= indent("# " + tag.name + "\n") if tag.name %>
+<%= indent(format_source(tag.text)) + "\n" %>
 <%= "\n" if i < object.tags(:example).size - 1 %>
 <% end %>
 <% end %>

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: yard
 version: !ruby/object:Gem::Version 
-  hash: 7
+  hash: 5
   prerelease: false
   segments: 
   - 0
   - 5
-  - 6
-  version: 0.5.6
+  - 7
+  version: 0.5.7
 platform: ruby
 authors: 
 - Loren Segal
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-06-12 00:00:00 -04:00
+date: 2010-06-21 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -218,8 +218,15 @@ files:
 - spec/rake/yardoc_task_spec.rb
 - spec/registry_spec.rb
 - spec/registry_store_spec.rb
+- spec/serializers/data/serialized_yardoc/checksums
+- spec/serializers/data/serialized_yardoc/objects/Foo/bar_i.dat
+- spec/serializers/data/serialized_yardoc/objects/Foo/baz_i.dat
+- spec/serializers/data/serialized_yardoc/objects/Foo.dat
+- spec/serializers/data/serialized_yardoc/objects/root.dat
+- spec/serializers/data/serialized_yardoc/proxy_types
 - spec/serializers/file_system_serializer_spec.rb
 - spec/serializers/spec_helper.rb
+- spec/serializers/yardoc_serializer_spec.rb
 - spec/spec_helper.rb
 - spec/tags/default_factory_spec.rb
 - spec/tags/default_tag_spec.rb