yard 0.4.0 → 0.5.0

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

@@ -261,7 +261,7 @@ module YARD
         # 
         # @yield each descendent node in order
         # @yieldparam [AstNode] self, or a child/descendent node
-        # @return [nil] 
+        # @return [void] 
         def traverse
           nodes = [self]
           nodes.each.with_index do |node, index|
@@ -273,7 +273,7 @@ module YARD
         private
 
         # Resets line information
-        # @return [nil] 
+        # @return [void] 
         def reset_line_info
           if size == 0
             self.line_range = @fallback_line

data/lib/yard/parser/ruby/legacy/ruby_lex.rb

@@ -14,7 +14,6 @@ module YARD
       
       class Token
         NO_TEXT = "??".freeze
-        attr :text
 
         def initialize(line_no, char_no)
           @line_no = line_no
@@ -457,9 +456,9 @@ module YARD
         @exception_on_syntax_error = true
       end
 
-      attr :skip_space, true
-      attr :read_auto_clean_up, true
-      attr :exception_on_syntax_error, true
+      attr_accessor :skip_space
+      attr_accessor :read_auto_clean_up
+      attr_accessor :exception_on_syntax_error
 
       attr :indent
 

data/lib/yard/parser/source_parser.rb

@@ -32,11 +32,12 @@ module YARD
         # 
         # @return [Symbol] the parser type
         attr_accessor :parser_type
+        undef parser_type=
         
         # Sets the parser and makes sure it's a valid type
         # 
         # @param [Symbol] value the new parser type
-        # @return [nil] 
+        # @return [void] 
         def parser_type=(value)
           @parser_type = validated_parser_type(value)
         end
@@ -48,9 +49,12 @@ module YARD
         # @param [Fixnum] level the logger level to use during parsing. See
         #   {YARD::Logger}
         # @return the parser object that was used to parse the source. 
-        def parse(paths = "lib/**/*.rb", level = log.level)
+        def parse(paths = ["lib/**/*.rb", "ext/**/*.c"], level = log.level)
           log.debug("Parsing #{paths} with `#{parser_type}` parser")
-          files = [paths].flatten.map {|p| p.include?("*") ? Dir[p] : p }.flatten
+          files = [paths].flatten.
+            map {|p| File.directory?(p) ? "#{p}/**/*.{rb,c}" : p }.
+            map {|p| p.include?("*") ? Dir[p] : p }.flatten.
+            reject {|p| !File.file?(p) }
 
           log.enter_level(level) do
             parse_in_order(*files.uniq)
@@ -91,7 +95,7 @@ module YARD
         # that can continue processing the file.
         # 
         # @param [Array<String>] files a list of files to queue for parsing
-        # @return [nil]
+        # @return [void]
         def parse_in_order(*files)
           files = files.sort_by {|x| x.length if x }
           while file = files.shift
@@ -134,12 +138,18 @@ module YARD
       # use the class methods {parse} and {parse_string}.
       #
       # @param [String, #read, Object] content the source file to parse
-      # @return the parser object used to parse the source
+      # @return [Object, nil] the parser object used to parse the source
       def parse(content = __FILE__)
         case content
         when String
           @file = content
           content = IO.read(content)
+          checksum = Registry.checksum_for(content)
+          if Registry.checksums[file] == checksum
+            log.info "File '#{file}' hasn't changed, skipping..."
+            return
+          end
+          Registry.checksums[@file] = checksum
           self.parser_type = parser_type_for_filename(file)
         else
           content = content.read if content.respond_to? :read
@@ -174,8 +184,9 @@ module YARD
       private
 
       # Runs a {Handlers::Processor} object to post process the parsed statements.
-      # @return [nil] 
+      # @return [void] 
       def post_process
+        return unless @parser.respond_to? :enumerator
         post = Handlers::Processor.new(@file, @load_order_errors, @parser_type)
         post.process(@parser.enumerator)
       end
@@ -204,7 +215,7 @@ module YARD
       def parse_statements(content)
         case parser_type
         when :c
-          raise NotImplementedError, "no support for C/C++ files"
+          CParser.new(content, file).parse
         when :ruby18
           Ruby::Legacy::StatementList.new(content)
         when :ruby

data/lib/yard/rake/yardoc_task.rb

@@ -54,7 +54,7 @@ module YARD
       protected
       
       # Defines the rake task
-      # @return [nil] 
+      # @return [void] 
       def define
         desc "Generate YARD Documentation"
         task(name) do

data/lib/yard/registry.rb

@@ -1,5 +1,6 @@
 require 'singleton'
-require 'find'
+require 'fileutils'
+require 'digest/sha1'
 
 module YARD
   # The +Registry+ is the centralized data store for all {CodeObjects} created
@@ -16,6 +17,7 @@ module YARD
   # delegated to the instance.
   class Registry 
     DEFAULT_YARDOC_FILE = ".yardoc"
+    LOCAL_YARDOC_INDEX = File.expand_path('~/.yard/gem_index')
     
     include Singleton
   
@@ -28,11 +30,57 @@ module YARD
       attr_reader :objects
       
       # Clears the registry and cache
-      # @return [nil] 
+      # @return [void] 
       def clear
         instance.clear 
         objects.clear
       end
+
+      # Returns the .yardoc file associated with a gem.
+      # 
+      # @param [String] gem the name of the gem to search for
+      # @param [String] ver_require an optional Gem version requirement
+      # @param [Boolean] for_writing whether or not the method should search
+      #   for writable locations
+      # @return [String] if +for_writing+ is set to +true+, returns the best 
+      #   location suitable to write the .yardoc file. Otherwise, the first 
+      #   existing location associated with the gem's .yardoc file.
+      # @return [nil] if +for_writing+ is set to false and no yardoc file
+      #   is found, returns nil.
+      def yardoc_file_for_gem(gem, ver_require = ">= 0", for_writing = false)
+        spec = Gem.source_index.find_name(gem, ver_require).first
+        
+        if for_writing
+          global_yardoc_file(spec, for_writing) ||
+            local_yardoc_file(spec, for_writing)
+        else
+          local_yardoc_file(spec, for_writing) ||
+            global_yardoc_file(spec, for_writing)
+        end
+      end
+      
+      private
+      
+      def global_yardoc_file(spec, for_writing = false)
+        path = spec.full_gem_path
+        yfile = File.join(path, DEFAULT_YARDOC_FILE)
+        if for_writing && File.writable?(path)
+          return yfile
+        elsif !for_writing && File.exist?(yfile)
+          return yfile
+        end
+      end
+      
+      def local_yardoc_file(spec, for_writing = false)
+        path = Registry::LOCAL_YARDOC_INDEX
+        FileUtils.mkdir_p(path) if for_writing
+        path = File.join(path, "#{spec.full_name}.yardoc")
+        if for_writing
+          path
+        else
+          File.exist?(path) ? path : nil
+        end
+      end
     end
 
     # Gets/sets the yardoc filename
@@ -42,7 +90,9 @@ module YARD
     
     # The assumed types of a list of paths
     # @return [{String => Symbol}] a set of unresolved paths and their assumed type
-    attr_reader :proxy_types
+    def proxy_types
+      @store.proxy_types
+    end
     
     # Loads the registry and/or parses a list of files
     # 
@@ -64,9 +114,9 @@ module YARD
         if File.exists?(yardoc_file) && !reload
           load_yardoc
         else
-          size = namespace.size
+          size = @store.keys.size
           YARD.parse(files)
-          save if namespace.size > size
+          save if @store.keys.size > size
         end
         true
       elsif files.is_a?(String)
@@ -80,21 +130,30 @@ module YARD
     # Loads a yardoc file directly
     # 
     # @param [String] file the yardoc file to load.
-    # @return [nil] 
+    # @return [void] 
     def load_yardoc(file = yardoc_file)
-      return false unless File.exists?(file)
-      ns, pt = *Marshal.load(IO.read(file))
-      namespace.update(ns)
-      proxy_types.update(pt)
+      clear
+      @store.load(file)
     end
     
     # Saves the registry to +file+
     # 
     # @param [String] file the yardoc file to save to
     # @return [Boolean] true if the file was saved
-    def save(file = yardoc_file)
-      File.open(file, "wb") {|f| Marshal.dump([@namespace, @proxy_types], f) }
-      true
+    def save(merge = false, file = yardoc_file)
+      @store.save(merge, file)
+    end
+    
+    def checksums
+      @store.checksums
+    end
+    
+    def checksum_for(data)
+      Digest::SHA1.hexdigest(data)
+    end
+    
+    def delete_from_disk
+      @store.destroy
     end
 
     # Returns all objects in the registry that match one of the types provided
@@ -110,7 +169,7 @@ module YARD
     # @return [Array<CodeObjects::Base>] the list of objects found
     # @see CodeObjects::Base#type
     def all(*types)
-      namespace.values.select do |obj| 
+      @store.values.select do |obj| 
         if types.empty?
           obj != root
         else
@@ -123,9 +182,10 @@ module YARD
     end
     
     # Returns the paths of all of the objects in the registry.
+    # @param [Boolean] reload whether to load entire database
     # @return [Array<String>] all of the paths in the registry.
-    def paths
-      namespace.keys.map {|k| k.to_s }
+    def paths(reload = true)
+      @store.keys(reload).map {|k| k.to_s }
     end
     
     # Returns the object at a specific path.
@@ -133,27 +193,25 @@ module YARD
     #   returns the {#root} object.
     # @return [CodeObjects::Base] the object at path
     # @return [nil] if no object is found
-    def at(path) path.to_s.empty? ? root : namespace[path] end
+    def at(path) @store[path] end
     alias_method :[], :at
     
     # The root namespace object.
     # @return [CodeObjects::RootObject] the root object in the namespace
-    def root; namespace[:root] end
+    def root; @store[:root] end
     
     # Deletes an object from the registry
     # @param [CodeObjects::Base] object the object to remove
-    # @return [nil] 
+    # @return [void] 
     def delete(object) 
-      namespace.delete(object.path)
+      @store.delete(object.path)
       self.class.objects.delete(object.path)
     end
 
     # Clears the registry
-    # @return [nil] 
+    # @return [void] 
     def clear
-      @namespace = SymbolHash.new
-      @namespace[:root] = CodeObjects::RootObject.new(nil, :root)
-      @proxy_types = {}
+      @store = RegistryStore.new
     end
 
     # Creates the Registry
@@ -170,7 +228,7 @@ module YARD
     def register(object)
       self.class.objects[object.path] = object
       return if object.is_a?(CodeObjects::Proxy)
-      namespace[object.path] = object
+      @store[object.path] = object
     end
 
     # Attempts to find an object by name starting at +namespace+, performing
@@ -246,10 +304,6 @@ module YARD
     end
 
     private
-  
-    # The internal namespace hash
-    # @return [Hash{String => CodeObjects::Base}] the path/object hash
-    attr_accessor :namespace
 
     # Attempts to resolve a name in a namespace
     # 

data/lib/yard/registry_store.rb

@@ -0,0 +1,213 @@
+require 'fileutils'
+
+module YARD
+  # The data store for the {Registry}.
+  # 
+  # @see Registry
+  # @see Serializers::YardocSerializer
+  class RegistryStore
+    attr_reader :proxy_types, :file, :checksums
+    
+    def initialize
+      @file = nil
+      @checksums = {}
+      @store = { :root => CodeObjects::RootObject.new(nil, :root) }
+      @proxy_types = {}
+      @loaded_objects = 0
+      @available_objects = 0
+    end
+    
+    # Gets a {CodeObjects::Base} from the store
+    # 
+    # @param [String, Symbol] key the path name of the object to look for.
+    #   If it is empty or :root, returns the {#root} object.
+    # @return [CodeObjects::Base, nil] a code object or nil if none is found
+    def get(key)
+      key = :root if key == ''
+      key = key.to_sym
+      return @store[key] if @store[key]
+      return nil if @loaded_objects >= @available_objects
+
+      # check disk
+      if obj = @serializer.deserialize(key)
+        @loaded_objects += 1
+        put(key, obj)
+      end
+    end
+    
+    # Associates an object with a path
+    # @param [String, Symbol] key the path name (:root or '' for root object)
+    # @param [CodeObjects::Base] value the object to store
+    # @return [CodeObjects::Base] returns +value+
+    def put(key, value)
+      if key == ''
+        @store[:root] = value
+      else
+        @store[key.to_sym] = value 
+      end
+    end
+    
+    alias [] get
+    alias []= put
+    
+    def delete(key) @store.delete(key.to_sym) end
+    
+    # Gets all path names from the store. Loads the entire database
+    # if +reload+ is +true+
+    # 
+    # @param [Boolean] reload if false, does not load the entire database
+    #   before a lookup.
+    # @return [Array<Symbol>] the path names of all the code objects
+    def keys(reload = true) load_all if reload; @store.keys end
+    
+    # Gets all code objects from the store. Loads the entire database
+    # if +reload+ is +true+
+    # 
+    # @param [Boolean] reload if false, does not load the entire database
+    #   before a lookup.
+    # @return [Array<CodeObjects::Base>] all the code objects
+    def values(reload = true) load_all if reload; @store.values end
+    
+    # @return [CodeObjects::RootObject] the root object
+    def root; @store[:root] end
+    
+    # @param [String, nil] file the name of the yardoc db to load
+    # @return [Boolean] whether the database was loaded
+    def load(file = nil)
+      @file = file
+      @store = {}
+      @proxy_types = {}
+      @serializer = Serializers::YardocSerializer.new(@file)
+      load_yardoc
+    end
+    
+    # Saves the database to disk
+    # @param [Boolean] merge if true, merges the data in memory with the
+    #   data on disk, otherwise the data on disk is deleted.
+    # @param [String, nil] file if supplied, the name of the file to save to
+    # @return [Boolean] whether the database was saved
+    def save(merge = true, file = nil)
+      if file && file != @file
+        @file = file
+        @serializer = Serializers::YardocSerializer.new(@file)
+      end
+      destroy unless merge
+      values(false).each do |object|
+        @serializer.serialize(object)
+      end
+      write_proxy_types
+      write_checksums
+      true
+    end
+    
+    # Deletes the .yardoc database on disk
+    # 
+    # @param [Boolean] force if force is not set to true, the file/directory
+    #   will only be removed if it ends with .yardoc. This helps with
+    #   cases where the directory might have been named incorrectly.
+    # @return [Boolean] true if the .yardoc database was deleted, false
+    #   otherwise.
+    def destroy(force = false)
+      if (!force && file =~ /\.yardoc$/) || force
+        if File.file?(@file) 
+          # Handle silent upgrade of old .yardoc format
+          File.unlink(@file) 
+        elsif File.directory?(@file)
+          FileUtils.rm_rf(@file)
+        end
+        true
+      else
+        false
+      end
+    end
+    
+    protected
+    
+    def objects_path
+      @serializer.objects_path
+    end
+    
+    def proxy_types_path
+      @serializer.proxy_types_path
+    end
+    
+    def checksums_path
+      @serializer.checksums_path
+    end
+    
+    def load_yardoc
+      return false unless @file
+      if File.directory?(@file) # new format
+        Registry.objects.replace({})
+        @loaded_objects = 0
+        @available_objects = all_disk_objects.size
+        load_proxy_types
+        load_checksums
+        load_root
+        true
+      elsif File.file?(@file) # old format
+        load_yardoc_old
+        true
+      else
+        false
+      end
+    end
+    
+    def load_yardoc_old
+      @store, @proxy_types = *Marshal.load(File.read(@file))
+    end
+    
+    private
+    
+    def load_proxy_types
+      return unless File.file?(proxy_types_path)
+      @proxy_types = Marshal.load(File.read(proxy_types_path))
+    end
+    
+    def load_checksums
+      return unless File.file?(checksums_path)
+      lines = File.readlines(checksums_path).map do |line|
+        line.strip.split(/\s+/)
+      end
+      @checksums = Hash[lines]
+    end
+    
+    def load_root
+      if root = @serializer.deserialize('root')
+        @store[:root] = root
+      end
+    end
+    
+    def load_all
+      return unless @file
+      return if @loaded_objects >= @available_objects
+      log.debug "Loading entire database: #{@file} ..."
+      objects = []
+      
+      all_disk_objects.sort_by {|x| x.size }.each do |path|
+        if obj = @serializer.deserialize(path, true)
+          objects << obj
+        end
+      end
+      objects.each do |obj|
+        put(obj.path, obj)
+      end
+      @loaded_objects += objects.size
+      log.debug "Loaded database (file='#{@file}' count=#{objects.size} total=#{@available_objects})"
+    end
+
+    def all_disk_objects
+      Dir.glob(File.join(objects_path, '**/*')).select {|f| File.file?(f) }
+    end
+    
+    def write_proxy_types
+      File.open(proxy_types_path, 'wb') {|f| f.write(Marshal.dump(@proxy_types)) }
+    end
+    
+    def write_checksums
+      File.open(checksums_path, 'w') do |f|
+        @checksums.each {|k, v| f.puts("#{k} #{v}") }
+      end
+    end
+  end
+end