yard 0.6.1 → 0.6.2

data/docs/Tags.md

@@ -96,19 +96,25 @@ YARD supplies the following built-in tags:
     implementor information.
   
         @abstract Subclass and override {#run} to implement a custom Threadable class.
+        
+  * `@api`: Declares the API that the object belongs to. Does not display in
+    output, but useful for performing queries (`yardoc --query`). Any text is
+    allowable in this tag, and there are no predefined values.
+    
+        @api freeform text
       
   * `@attr`: Declares an attribute from the docstring of a class. Meant to be
-    used on Struct classes (classes that inherit Struct).
+    used on Struct classes only (classes that inherit Struct).
   
         @attr [Types] attribute_name a full description of the attribute
       
   * `@attr_reader`: Declares a readonly attribute from the docstring of a class.
-    Meant to be used on Struct classes (classes that inherit Struct). See `@attr`.
+    Meant to be used on Struct classes only (classes that inherit Struct). See `@attr`.
   
         @attr_reader [Types] name description of a readonly attribute
       
   * `@attr_writer`: Declares a writeonly attribute from the docstring of class.
-    Meant to be used on Struct classes (classes that inherit Struct). See `@attr`.
+    Meant to be used on Struct classes only (classes that inherit Struct). See `@attr`.
   
         @attr_writer [Types] name description of writeonly attribute
 
@@ -125,7 +131,12 @@ YARD supplies the following built-in tags:
     first line is an optional title.
 
         @example Reverse a string
-          "mystring.reverse" #=> "gnirtsym"
+          "mystring".reverse #=> "gnirtsym"
+          
+  * `@note`: Creates an emphasized note for the users to read about the
+    object.
+    
+        @note This method should only be used in outer space.
 
   * `@option`: Describe an options hash in a method. The tag takes the
     name of the options parameter first, followed by optional types,
@@ -168,7 +179,7 @@ YARD supplies the following built-in tags:
     command-line switch to yardoc (see {file:README.md}).
   
         @private
-
+        
   * `@raise`: Describes an Exception that a method may throw
 
         @raise [ExceptionClass] description

data/docs/WhatsNew.md

@@ -14,6 +14,11 @@ What's New in 0.6.x?
 11. **Added `--transitive-tags` to register transitive tags** (0.6.0)
 12. **`yardoc` now displays RDoc-like statistics (`--no-stats` to hide)** (0.6.0)
 13. **`yri` now works on constants** (0.6.0)
+14. **Plugins are no longer auto-loaded (added `--plugin` switch)** (0.6.2)
+15. **Added `YARD::Config` API and `~/.yard/config` configuration file** (0.6.2)
+16. **Added `yard config` command to view/edit configuration** (0.6.2)
+17. **Added `yard server -t` template path switch** (0.6.2)
+18. **Added `YARD::Server.register_static_path` for static server assets** (0.6.2)
 
 ## Local documentation server for RubyGems or projects (`yard server`) (0.6.0)
 
@@ -218,6 +223,59 @@ To hide this output when yardoc is run, use `--no-stats`.
 Templates have now been added for text view of constants, which displays any 
 documentation and the constant value.
 
+## Plugins are no longer auto-loaded (added `--plugin` switch) (0.6.2)
+
+This is a backwards-incompatible change that disables plugins from automatically
+loading when YARD starts up. From now on, you should manually declare which
+plugins your project is using by adding `--plugin PLUGINNAME` to a `.yardopts`
+file in the root of your project. You can also re-enable autoloaded plugins
+by setting `load_plugins` to true in your configuration file (`yard config load_plugins true`, 
+see next item). You can also set `autoload_plugins` to a list of plugins 
+to be automatically loaded on start.
+
+If you are a YARD plugin author, please make sure to inform your users of these
+changes.
+
+Note that `--plugin` switches passed on the commandline (not via `.yardopts`) 
+are parsed before commands are loaded, and therefore can add in new CLI commands.
+
+## Added `YARD::Config` API and `~/.yard/config` configuration file (0.6.2)
+
+There is a new global configuration API that can be accessed programmatically
+and set via the `~/.yard/config` file. The file is encoded as a YAML file,
+and looks like:
+
+    :load_plugins: false
+    :ignored_plugins:
+      - my_plugin
+      - my_other_plugin
+    :autoload_plugins:
+      - my_autoload_plugin
+    :safe_mode: false
+
+You can also set configuration options via the command-line (see next item).
+    
+## Added `yard config` command to view/edit configuration (0.6.2)
+
+A new `yard config` command was created to view or edit the configuration
+file via the commandline. 
+
+* To view the current configuration use `yard config --list`.
+* To view a specific item use `yard config ITEMNAME`
+* To modify an item value use `yard config ITEMNAME VALUE`
+
+## Added `yard server -t` template path switch (0.6.2)
+
+The `yard server` command now accepts `-t` or `--template-path` to register
+a new template path for template customization.
+
+## Added `YARD::Server.register_static_path` for static server assets (0.6.2)
+
+The server now supports a command to register static asset paths. If you are
+extending the YARD::Server modules, make sure to register your asset paths
+through this method.
+
+
 What's New in 0.5.x?
 ====================
 
@@ -254,13 +312,13 @@ Incremental parsing and output generation with `yardoc -c` (0.5.0, 0.5.3)
 YARD now compares file checksums before parsing when using `yardoc -c`
 (aka `yardoc --use-cache`) to do incremental parsing of only the files that
 have changed. HTML (or other output format) generation will also only be
-done on the objects that were parsed from changed files (*). This makes doing
+done on the objects that were parsed from changed files (\*). This makes doing
 a documentation development cycle much faster for quick HTML previews. Just
 remember that when using incremental output generation, the index will not
 be rebuilt and inter-file links might not hook up right, so it is best to
 perform a full rebuild at the end of such previews.
 
-(*) Only for versions prior to 0.5.3. For 0.5.3+, use `--incremental` for
+(\*) Only for versions prior to 0.5.3. For 0.5.3+, use `--incremental` for
 incremental HTML output.
 
 Improved `yri` support to perform lookups on installed Gems (0.5.0)

data/lib/yard.rb

@@ -1,5 +1,5 @@
 module YARD
-  VERSION = "0.6.1"
+  VERSION = "0.6.2"
   
   # The root path for YARD source libraries
   ROOT = File.expand_path(File.dirname(__FILE__))
@@ -7,7 +7,7 @@ module YARD
   # The root path for YARD builtin templates
   TEMPLATE_ROOT = File.join(ROOT, '..', 'templates')
   
-  # The location where YARD stores user-specific settings
+  # @deprecated Use {Config::CONFIG_DIR}
   CONFIG_DIR = File.expand_path('~/.yard')
   
   # An alias to {Parser::SourceParser}'s parsing method
@@ -24,39 +24,23 @@ module YARD
   # @see Parser::SourceParser.parse_string
   def self.parse_string(*args) Parser::SourceParser.parse_string(*args) end
   
-  # Loads gems that match the name 'yard-*' (recommended) or 'yard_*' except
-  # those listed in +~/.yard/ignored_plugins+. This is called immediately 
-  # after YARD is loaded to allow plugin support.
-  # 
-  # @return [true] always returns true
-  def self.load_plugins
-    ignored_plugins_file = File.join(CONFIG_DIR, "ignored_plugins")
-    if File.file?(ignored_plugins_file)
-      ignored_plugins = IO.read(ignored_plugins_file).split(/\s+/)
-    else
-      ignored_plugins = []
-    end
-    
-    Gem.source_index.find_name('').each do |gem|
-      begin
-        if gem.name =~ /^yard[-_](?!doc-)/ && !ignored_plugins.include?(gem.name)
-          log.debug "Loading plugin '#{gem.name}'..."
-          require gem.name 
-        end
-      rescue Gem::LoadError, LoadError
-        log.warn "Error loading plugin '#{gem.name}'"
-      end
-    end
-    true
-  end
+  # (see YARD::Config.load_plugins)
+  # @deprecated Use {Config.load_plugins}
+  def self.load_plugins; YARD::Config.load_plugins end
 end
 
-# Ruby 1.9.2 removes '.' which is not exactly a good idea
-$LOAD_PATH.push('.') if RUBY_VERSION >= '1.9.2'
-
 # Keep track of Ruby version for compatibility code
 RUBY19, RUBY18 = *(RUBY_VERSION >= "1.9.1" ? [true, false] : [false, true])
 
+# Whether or not continuations are (properly) supported
+begin
+  begin; require 'continuation'; rescue LoadError; end
+  cc = callcc {|cc| cc }; cc.call if cc
+  CONTINUATIONS_SUPPORTED = true
+rescue
+  CONTINUATIONS_SUPPORTED = false
+end
+
 # Load Ruby core extension classes
 Dir.glob(File.join(YARD::ROOT, 'yard', 'core_ext', '*.rb')).each do |file|
   require file
@@ -66,10 +50,5 @@ end
   require File.join(YARD::ROOT, 'yard', file)
 end
 
-# Load any plugins
-begin
-  require 'rubygems'
-  YARD.load_plugins
-rescue LoadError
-  log.debug "RubyGems is not present, skipping plugin loading"
-end
+# Load YARD configuration options (and plugins)
+YARD::Config.load

data/lib/yard/autoload.rb

@@ -5,6 +5,7 @@ module YARD
   module CLI # Namespace for command-line interface components
     autoload :Command,        __p('cli/command')
     autoload :CommandParser,  __p('cli/command_parser')
+    autoload :Config,         __p('cli/config')
     autoload :Diff,           __p('cli/diff')
     autoload :Gems,           __p('cli/gems')
     autoload :Graph,          __p('cli/graph')
@@ -136,6 +137,8 @@ module YARD
   # Namespace for classes and modules that handle serving documentation over HTTP
   # @since 0.6.0
   module Server
+    require __p('server')
+
     module Commands
       autoload :Base,                 __p('server/commands/base')
       autoload :DisplayFileCommand,   __p('server/commands/display_file_command')
@@ -197,10 +200,12 @@ module YARD
     autoload :Template, __p('templates/template')
   end
 
+  autoload :Config,         __p('config')
   autoload :Docstring,      __p('docstring')
   autoload :Logger,         __p('logging')
   autoload :Registry,       __p('registry')
   autoload :RegistryStore,  __p('registry_store')
+  autoload :StubProxy,      __p('serializers/yardoc_serializer')
   autoload :Verifier,       __p('verifier')
 end
 

data/lib/yard/cli/command.rb

@@ -24,12 +24,11 @@ module YARD
         opts.separator ""
         opts.separator "Other options:"
         opts.on('-e', '--load FILE', 'A Ruby script to load before the source tree is parsed.') do |file|
-          begin
-            require(file.gsub(/\.rb$/, ''))
-          rescue LoadError
-            log.error "The file `#{file}' could not be loaded, check the path and try again."
-            exit
-          end
+          load_script(file)
+        end
+        opts.on('--plugin PLUGIN', 'Load a YARD plugin (gem with `yard-\' prefix)') do |name|
+          # Not actually necessary to load here, this is done at boot in YARD::Config.load_plugins
+          # YARD::Config.load_plugin(name)
         end
         opts.on('--legacy', 'Use old style Ruby parser and handlers. Always on in 1.8.x.') do
           YARD::Parser::SourceParser.parser_type = :ruby18
@@ -53,6 +52,19 @@ module YARD
       rescue OptionParser::InvalidOption => e
         log.warn "Unrecognized/#{e.message}"
       end
+      
+      # Loads a Ruby script. If +Config.options[:safe_mode]+ is enabled,
+      # this method will do nothing.
+      # 
+      # @param [String] file the path to the script to load
+      # @since 0.6.2
+      def load_script(file)
+        return if YARD::Config.options[:safe_mode]
+        require(file.gsub(/\.rb$/, ''))
+      rescue LoadError
+        log.error "The file `#{file}' could not be loaded, check the path and try again."
+        exit
+      end
     end
   end
 end

data/lib/yard/cli/command_parser.rb

@@ -31,6 +31,7 @@ module YARD
       end
       
       self.commands = SymbolHash[
+        :config => Config,
         :diff   => Diff,
         :doc    => Yardoc,
         :gems   => Gems,

data/lib/yard/cli/config.rb

@@ -0,0 +1,113 @@
+module YARD
+  module CLI
+    # CLI command to view or edit configuration options
+    # @since 0.6.2
+    class Config < Command
+      # @return [Symbol, nil] the key to view/edit, if any
+      attr_accessor :key
+      
+      # @return [Array, nil] the list of values to set (or single value), if modifying
+      attr_accessor :values
+      
+      # @return [Boolean] whether to reset the {#key}
+      attr_accessor :reset
+      
+      def initialize
+        super
+        self.key = nil
+        self.values = []
+        self.reset = false
+      end
+      
+      def description
+        'Views or edits current global configuration'
+      end
+      
+      def run(*args)
+        optparse(*args)
+        if key
+          if reset || values.size > 0
+            modify_item
+          else
+            view_item
+          end
+        else
+          list_configuration
+        end
+      end
+      
+      private
+      
+      def modify_item
+        if reset
+          log.debug "Resetting #{key}"
+          YARD::Config.options[key] = YARD::Config::DEFAULT_CONFIG_OPTIONS[key]
+        else
+          log.debug "Setting #{key} to #{values.inspect}"
+          YARD::Config.options[key] = encode_values
+        end
+        YARD::Config.save
+      end
+      
+      def view_item
+        log.debug "Viewing #{key}"
+        puts YARD::Config.options[key].inspect
+      end
+      
+      def list_configuration
+        log.debug "Listing configuration"
+        require 'yaml'
+        puts YAML.dump(YARD::Config.options).sub(/\A--.*\n/, '').gsub(/\n\n/, "\n")
+      end
+      
+      def encode_values
+        if values.size == 1
+          encode_value(values.first)
+        else
+          values.map {|v| encode_value(v) }
+        end
+      end
+      
+      def encode_value(value)
+        case value
+        when /^-?\d+/; value.to_i
+        when "true"; true
+        when "false"; false
+        else value
+        end
+      end
+      
+      def optparse(*args)
+        list = false
+        opts = OptionParser.new
+        opts.banner = "Usage: yard config [options] [item [value ...]]"
+        opts.separator ""
+        opts.separator "Example: yard config load_plugins true"
+        opts.separator ""
+        opts.separator "Views and sets configuration items. If an item is provided"
+        opts.separator "With no value, the item is viewed. If a value is provided,"
+        opts.separator "the item is modified. Specifying no item is equivalent to --list."
+        opts.separator "If you specify multiple space delimited values, these are"
+        opts.separator "parsed as an array of values."
+        opts.separator ""
+        opts.separator "Note that `true` and `false` are reserved words."
+        opts.separator ""
+        opts.separator "General options:"
+        
+        opts.on('-l', '--list', 'List current configuration') do
+          list = true
+        end
+        opts.on('-r', '--reset', 'Resets the specific item to default') do
+          self.reset = true
+        end
+        common_options(opts)
+        parse_options(opts, args)
+        args = [] if list
+        self.key = args.shift.to_sym if args.size >= 1
+        self.values = args if args.size >= 1
+        args
+      end
+      
+    end
+  end
+end

data/lib/yard/cli/gems.rb

@@ -15,8 +15,8 @@ module YARD
       # @param [Array<String>] args the list of arguments
       # @return [void] 
       def run(*args)
+        require 'rubygems'
         optparse(*args)
-        @gems += Gem.source_index.find_name('') if @gems.empty?
         build_gems
       end
       
@@ -44,9 +44,14 @@ module YARD
       end
       
       def add_gems(gems)
-        gems.each_slice(2) do |gem, ver_require|
-          specs = Gem.source_index.find_name(gem, ver_require || ">= 0")
-          @gems += specs unless specs.empty?
+        0.step(gems.size - 1, 2) do |index|
+          gem, ver_require = gems[index], gems[index + 1] || ">= 0"
+          specs = Gem.source_index.find_name(gem, ver_require)
+          if specs.empty?
+            log.warn "#{gem} #{ver_require} could not be found in RubyGems index"
+          else
+            @gems += specs
+          end
         end
       end
       
@@ -61,13 +66,17 @@ module YARD
         opts.on('--rebuild', 'Rebuilds index') do
           @rebuild = true
         end
-        opts.on('--legacy', 'Use old style parser and handlers. Unavailable under Ruby 1.8.x') do
-          YARD::Parser::SourceParser.parser_type = :ruby18
-        end
         
         common_options(opts)
         parse_options(opts, args)
         add_gems(args)
+        
+        
+        if !args.empty? && @gems.empty?
+          log.error "No specified gems could be found for command"
+        elsif @gems.empty?
+          @gems += Gem.source_index.find_name('') if @gems.empty?
+        end
       end
     end
   end