yard 0.6.8 → 0.7.0

data/lib/yard/rake/yardoc_task.rb

@@ -3,38 +3,38 @@ require 'rake/tasklib'
 
 module YARD
   module Rake
-    
+
     # The rake task to run {CLI::Yardoc} and generate documentation.
     class YardocTask < ::Rake::TaskLib
       # The name of the task
       # @return [String] the task name
       attr_accessor :name
-      
+
       # Options to pass to {CLI::Yardoc}
       # @return [Hash] the options passed to the commandline utility
       attr_accessor :options
-      
+
       # The Ruby source files (and any extra documentation files separated by '-')
       # to process
       # @return [Array<String>] a list of files
       attr_accessor :files
-      
+
       # Runs a +Proc+ before the task
       # @return [Proc] a proc to call before running the task
       attr_accessor :before
-      
+
       # Runs a +Proc+ after the task
       # @return [Proc] a proc to call after running the task
       attr_accessor :after
-      
-      # @return [Proc] an optional lambda to run against all objects being
-      #   generated. Any object that the lambda returns false for will be
-      #   excluded from documentation. 
+
+      # @return [Verifier, Proc] an optional {Verifier} to run against all objects 
+      #   being generated. Any object that the verifier returns false for will be
+      #   excluded from documentation. This attribute can also be a lambda.
       # @see Verifier
       attr_accessor :verifier
 
       # Creates a new task with name +name+.
-      # 
+      #
       # @param [String, Symbol] name the name of the rake task
       # @yield a block to allow any options to be modified on the task
       # @yieldparam [YardocTask] _self the task object to allow any parameters
@@ -43,25 +43,26 @@ module YARD
         @name = name
         @options = []
         @files = []
-        
+
         yield self if block_given?
-        self.options +=  ENV['OPTS'].split(/[ ,]/) if ENV['OPTS'] 
+        self.options +=  ENV['OPTS'].split(/[ ,]/) if ENV['OPTS']
         self.files   += ENV['FILES'].split(/[ ,]/) if ENV['FILES']
-        
+
         define
       end
-      
+
       protected
-      
+
       # Defines the rake task
-      # @return [void] 
+      # @return [void]
       def define
         desc "Generate YARD Documentation"
         task(name) do
           before.call if before.is_a?(Proc)
           yardoc = YARD::CLI::Yardoc.new
+          yardoc.parse_arguments *(options + files)
           yardoc.options[:verifier] = verifier if verifier
-          yardoc.run *(options + files) 
+          yardoc.run
           after.call if after.is_a?(Proc)
         end
       end

data/lib/yard/registry.rb

@@ -5,21 +5,21 @@ module YARD
   # The +Registry+ is the centralized data store for all {CodeObjects} created
   # during parsing. The storage is a key value store with the object's path
   # (see {CodeObjects::Base#path}) as the key and the object itself as the value.
-  # Object paths must be unique to be stored in the Registry. All lookups for 
-  # objects are done on the singleton Registry instance using the {Registry.at} 
+  # Object paths must be unique to be stored in the Registry. All lookups for
+  # objects are done on the singleton Registry instance using the {Registry.at}
   # or {Registry.resolve} methods.
-  # 
-  # == Saving / Loading a Registry 
-  # The registry is saved to a "yardoc file" (actually a directory), which can 
-  # be loaded back to perform any lookups. See {Registry.load!} and 
+  #
+  # == Saving / Loading a Registry
+  # The registry is saved to a "yardoc file" (actually a directory), which can
+  # be loaded back to perform any lookups. See {Registry.load!} and
   # {Registry.save} for information on saving and loading of a yardoc file.
-  # 
+  #
   # == Threading Notes
   # The registry class is a singleton class that is accessed directly in many
   # places across YARD. To mitigate threading issues, YARD (0.6.5+) makes
   # the Registry thread local. This means all access to a registry for a specific
   # object set must occur in the originating thread.
-  # 
+  #
   # @example Loading a Registry
   #   Registry.load!('/path/to/yardocfile') # loads all objects into memory
   #   Registry.at('YARD::CodeObjects::Base').docstring
@@ -37,13 +37,13 @@ module YARD
       # @group Getting .yardoc File Locations
 
       # 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 
+      # @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.
@@ -51,12 +51,12 @@ module YARD
         spec = Gem.source_index.find_name(gem, ver_require)
         return if spec.empty?
         spec = spec.first
-      
+
         if gem =~ /^yard-doc-/
           path = File.join(spec.full_gem_path, DEFAULT_YARDOC_FILE)
           return File.exist?(path) && !for_writing ? path : nil
         end
-      
+
         if for_writing
           global_yardoc_file(spec, for_writing) ||
             local_yardoc_file(spec, for_writing)
@@ -65,20 +65,20 @@ module YARD
             global_yardoc_file(spec, for_writing)
         end
       end
-    
+
       # Gets/sets the yardoc filename
       # @return [String] the yardoc filename
       # @see DEFAULT_YARDOC_FILE
       attr_accessor :yardoc_file
       def yardoc_file=(v) Thread.current[:__yard_yardoc_file__] = v end
       def yardoc_file
-        Thread.current[:__yard_yardoc_file__] ||= DEFAULT_YARDOC_FILE 
+        Thread.current[:__yard_yardoc_file__] ||= DEFAULT_YARDOC_FILE
       end
-    
+
       # @group Loading Data from Disk
-    
+
       # Loads the registry and/or parses a list of files
-      # 
+      #
       # @example Loads the yardoc file or parses files 'a', 'b' and 'c' (but not both)
       #   Registry.load(['a', 'b', 'c'])
       # @example Reparses files 'a' and 'b' regardless of whether yardoc file exists
@@ -108,9 +108,9 @@ module YARD
         end
         self
       end
-    
+
       # Loads a yardoc file directly
-      # 
+      #
       # @param [String] file the yardoc file to load.
       # @return [Registry] the registry object (for chaining)
       def load_yardoc(file = yardoc_file)
@@ -118,10 +118,10 @@ module YARD
         thread_local_store.load(file)
         self
       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 [Registry] the registry object (for chaining)
       # @see #load_yardoc
@@ -132,9 +132,9 @@ module YARD
         thread_local_store.load!(file)
         self
       end
-    
+
       # Forces all objects cached on disk into memory
-      # 
+      #
       # @example Loads all objects from disk
       #   Registry.load
       #   Registry.all.count #=> 0
@@ -146,86 +146,86 @@ module YARD
         thread_local_store.load_all
         self
       end
-    
+
       # @group Saving and Deleting Data from Disk
 
       # Saves the registry to +file+
-      # 
+      #
       # @param [String] file the yardoc file to save to
       # @return [Boolean] true if the file was saved
       def save(merge = false, file = yardoc_file)
         thread_local_store.save(merge, file)
       end
-    
+
       # Deletes the yardoc file from disk
       # @return [void]
       def delete_from_disk
         thread_local_store.destroy
       end
-    
+
       # @group Adding and Deleting Objects from the Registry
 
       # Registers a new object with the registry
-      # 
+      #
       # @param [CodeObjects::Base] object the object to register
       # @return [CodeObjects::Base] the registered object
       def register(object)
         return if object.is_a?(CodeObjects::Proxy)
         thread_local_store[object.path] = object
       end
-    
+
       # Deletes an object from the registry
       # @param [CodeObjects::Base] object the object to remove
-      # @return [void] 
-      def delete(object) 
+      # @return [void]
+      def delete(object)
         thread_local_store.delete(object.path)
       end
 
       # Clears the registry
-      # @return [void] 
+      # @return [void]
       def clear
         self.thread_local_store = RegistryStore.new
       end
 
       # @group Accessing Objects in the Registry
-     
+
       # Iterates over {all} with no arguments
       def each(&block)
         all.each(&block)
       end
-    
+
       # Returns all objects in the registry that match one of the types provided
       # in the +types+ list (if +types+ is provided).
-      # 
+      #
       # @example Returns all objects
       #   Registry.all
       # @example Returns all classes and modules
       #   Registry.all(:class, :module)
       # @param [Array<Symbol>] types an optional list of types to narrow the
-      #   objects down by. Equivalent to performing a select: 
+      #   objects down by. Equivalent to performing a select:
       #     +Registry.all.select {|o| types.include(o.type) }+
       # @return [Array<CodeObjects::Base>] the list of objects found
       # @see CodeObjects::Base#type
       def all(*types)
-        thread_local_store.values.select do |obj| 
+        thread_local_store.values.select do |obj|
           if types.empty?
             obj != root
           else
             obj != root &&
-              types.any? do |type| 
+              types.any? do |type|
                 type.is_a?(Symbol) ? obj.type == type : obj.is_a?(type)
               end
           end
         end + (types.include?(:root) ? [root] : [])
       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(reload = false)
         thread_local_store.keys(reload).map {|k| k.to_s }
       end
-    
+
       # Returns the object at a specific path.
       # @param [String, :root] path the pathname to look for. If +path+ is +root+,
       #   returns the {root} object.
@@ -233,14 +233,14 @@ module YARD
       # @return [nil] if no object is found
       def at(path) path ? thread_local_store[path] : nil end
       alias_method :[], :at
-    
+
       # The root namespace object.
       # @return [CodeObjects::RootObject] the root object in the namespace
       def root; thread_local_store[:root] end
-    
+
       # Attempts to find an object by name starting at +namespace+, performing
       # a lookup similar to Ruby's method of resolving a constant in a namespace.
-      # 
+      #
       # @example Looks for instance method #reverse starting from A::B::C
       #   Registry.resolve(P("A::B::C"), "#reverse")
       # @example Looks for a constant in the root namespace
@@ -260,7 +260,7 @@ module YARD
       # @param [Boolean] proxy_fallback If +true+, returns a proxy representing
       #   the unresolved path (namespace + name) if no object is found.
       # @return [CodeObjects::Base] the object if it is found
-      # @return [CodeObjects::Proxy] a Proxy representing the object if 
+      # @return [CodeObjects::Proxy] a Proxy representing the object if
       #   +proxy_fallback+ is +true+.
       # @return [nil] if +proxy_fallback+ is +false+ and no object was found.
       # @see P
@@ -268,7 +268,7 @@ module YARD
         if namespace.is_a?(CodeObjects::Proxy)
           return proxy_fallback ? CodeObjects::Proxy.new(namespace, name) : nil
         end
-      
+
         if namespace == :root || !namespace
           namespace = root
         else
@@ -298,24 +298,24 @@ module YARD
       end
 
       # @group Managing Source File Checksums
-    
+
       # @return [Hash{String => String}] a set of checksums for files
       def checksums
         thread_local_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
-    
+
       # @group Managing Internal State (Advanced / Testing Only)
-       
+
       # Whether or not the Registry storage should load everything into a
-      # single object database (for disk efficiency), or spread them out 
+      # single object database (for disk efficiency), or spread them out
       # (for load time efficiency).
-      # 
+      #
       # @note Setting this attribute to nil will offload the decision to
       #   the {RegistryStore storage adapter}.
       # @return [Boolean, nil] if this value is set to nil, the storage
@@ -330,21 +330,21 @@ module YARD
       def proxy_types
         thread_local_store.proxy_types
       end
-      
+
       # @group Legacy Methods
-      
+
       # The registry singleton instance.
-      # 
+      #
       # @deprecated use Registry.methodname directly.
       # @return [Registry] returns the registry instance
       def instance; self end
-    
+
       private
-    
+
       # @group Accessing Objects in the Registry
 
       # Attempts to resolve a name in a namespace
-      # 
+      #
       # @param [CodeObjects::NamespaceObject] namespace the starting namespace
       # @param [String] name the name to look for
       def partial_resolve(namespace, name)
@@ -360,9 +360,9 @@ module YARD
         end
         nil
       end
-    
+
       # @group Retrieving yardoc File Locations
-    
+
       def global_yardoc_file(spec, for_writing = false)
         path = spec.full_gem_path
         yfile = File.join(path, DEFAULT_YARDOC_FILE)
@@ -372,7 +372,7 @@ module YARD
           return yfile
         end
       end
-    
+
       def local_yardoc_file(spec, for_writing = false)
         path = Registry::LOCAL_YARDOC_INDEX
         FileUtils.mkdir_p(path) if for_writing
@@ -383,14 +383,14 @@ module YARD
           File.exist?(path) ? path : nil
         end
       end
-      
+
       # @group Threading support
-       
+
       # @since 0.6.5
       def thread_local_store
         Thread.current[:__yard_registry__] ||= clear
       end
-      
+
       # @since 0.6.5
       def thread_local_store=(value)
         Thread.current[:__yard_registry__] = value

data/lib/yard/registry_store.rb

@@ -2,12 +2,12 @@ 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 = {}
@@ -19,9 +19,9 @@ module YARD
       @store[:root] = CodeObjects::RootObject.allocate
       @store[:root].send(:initialize, nil, :root)
     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
@@ -41,7 +41,7 @@ module YARD
         nil
       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
@@ -51,34 +51,34 @@ module YARD
         @store[:root] = value
       else
         @notfound.delete(key.to_sym)
-        @store[key.to_sym] = value 
+        @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 = false) 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 = false) 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)
@@ -92,7 +92,7 @@ module YARD
 
     # Loads the .yardoc file and loads all cached objects into memory
     # automatically.
-    # 
+    #
     # @param [String, nil] file the name of the yardoc db to load
     # @return [Boolean] whether the database was loaded
     # @see #load_all
@@ -105,7 +105,7 @@ module YARD
         false
       end
     end
-    
+
     # Loads all cached objects into memory
     # @return [void]
     def load_all
@@ -113,7 +113,7 @@ module YARD
       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
@@ -125,7 +125,7 @@ module YARD
       @loaded_objects += objects.size
       log.debug "Loaded database (file='#{@file}' count=#{objects.size} total=#{@available_objects})"
     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.
@@ -137,7 +137,7 @@ module YARD
         @serializer = Serializers::YardocSerializer.new(@file)
       end
       destroy unless merge
-      
+
       sdb = Registry.single_object_db
       if sdb == true || (sdb == nil && keys.size < 3000)
         @serializer.serialize(@store)
@@ -150,9 +150,9 @@ module YARD
       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.
@@ -160,9 +160,9 @@ module YARD
     #   otherwise.
     def destroy(force = false)
       if (!force && file =~ /\.yardoc$/) || force
-        if File.file?(@file) 
+        if File.file?(@file)
           # Handle silent upgrade of old .yardoc format
-          File.unlink(@file) 
+          File.unlink(@file)
         elsif File.directory?(@file)
           FileUtils.rm_rf(@file)
         end
@@ -171,21 +171,21 @@ module YARD
         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
@@ -202,18 +202,18 @@ module YARD
         false
       end
     end
-    
+
     private
 
     def load_yardoc_old
       @store, @proxy_types = *Marshal.load(File.read_binary(@file))
     end
-    
+
     def load_proxy_types
       return unless File.file?(proxy_types_path)
       @proxy_types = Marshal.load(File.read_binary(proxy_types_path))
     end
-    
+
     def load_checksums
       return unless File.file?(checksums_path)
       lines = File.readlines(checksums_path).map do |line|
@@ -221,7 +221,7 @@ module YARD
       end
       @checksums = Hash[lines]
     end
-    
+
     def load_root
       if root = @serializer.deserialize('root')
         @loaded_objects += 1
@@ -238,11 +238,11 @@ module YARD
     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}") }