yard 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 601891a952ecd1662fcfaceb1160b3b664bf56d2
-  data.tar.gz: 979f166173832405bfcea7ba9b2aae33de865f5f
+  metadata.gz: ec4f1f12885dba0ad0385e0a1f7bd460275291cd
+  data.tar.gz: 2281f497dc0fa185ccc79d8eb5a374bdae40bee2
 SHA512:
-  metadata.gz: 8753f755361ae434ae739fd354182f8c5ed6fc5469b6c50d2af9a99bd73694d246b1c4e200cec05f8cc84f674070c2921e6bf8bd947836684f8679ab4896ec8a
-  data.tar.gz: 1ef05a31710af7aba1837cdbbfa54cad528b7e412e02c37433a8ebb07e6dfc8691e522f17a0ff2e90d4cb5a1d581af383bafb0b43b954c7841a21bc5b15faf0f
+  metadata.gz: 81280e2f91643f20e5fda61e118b97b5cb8868ca9eca7b15ff9572d9a65552df404961f7ad2af281e84937a3a6e67367f72d2746eb2add634e06f62cef126676
+  data.tar.gz: 4ab74c0f9d79622761098afcc0dd349308500d5593f9ea75414f211207b6798c3475aed0d8936eb4e317df76d6981f5b8499bf1e90ae41d180dc8405335aa829

data/CHANGELOG.md

@@ -1,3 +1,36 @@
+# 0.9.1 - July 18th, 2016
+
+- Added "Attributes" section to `yard stats`.
+- Added support for RubyGems 2.x `--document=yri,yard` flags. You can now run
+  YARD documentation generation against installed gems by running:
+  `gem install mygem --document=yard,yri`.
+- Added `/static/*` routing for library-specific routing. This enables static
+  template files to be served on a per-library basis instead of globally shared
+  across the `yard server`.
+- Added support for inlining of `{include:*}` syntax. Using this syntax in
+  the middle of a docstring paragraph will no longer create a separate paragraph
+  for the included text.
+- Added support for resolving `{}` syntax in text templates, specifically for
+  use in `{include:*}` syntax.
+- Improved object resolution logic in `{Foo::Bar}` syntax and {YARD::Registry.resolve}.
+  New resolution logic should now more accurately support resolving compound paths
+  across namespaces and through the inheritance tree (as Ruby does).
+- The `frozen_string_literal: true` comment line in Ruby source files will now be
+  excluded from docstrings.
+- Added a workaround for https://bugs.ruby-lang.org/issues/11485
+- Fixed an issue where type using a docstring reference on an `@!attribute` macro
+  would be incorrectly parsed as a type specifier. This change updates the tag
+  parser to disallow newlines between the tag name and opening bracket of the
+  type specification.
+- Fixed an issue where `--embed-mixins` would improperly embed methods from
+  inherited classes instead of modules.
+- Fixed various parsing errors and YARD exceptions.
+- Added a warning for modules or classes being redefined as constants.
+- Reverted stripping of HTML in {YARD::Docstring#summary}.
+- Added optimization to remove initial docstring parse on newly created code objects.
+- {YARD::CodeObjects::Base#format} now passes the :type parameter to templates.
+- Hide methods with filtered namespaces in Method Listing.
+
 # 0.9.0 - July 4th, 2016
 
 Special thanks to Alex Dowad, MSP-Greg, and Alex McLain for their extended

data/Rakefile

@@ -4,7 +4,7 @@ require 'rbconfig'
 
 YARD::VERSION.replace(ENV['YARD_VERSION']) if ENV['YARD_VERSION']
 
-task :default => :specs
+task :default => :travis_ci
 
 desc "Builds the gem"
 task :gem do

data/docs/Tags.md

@@ -97,11 +97,12 @@ following syntaxes are available:
   Note that for extensibility, other bracket types are allowed, such as `<>`,
   `()` and `{}`. The contents of the list are discussed in detail below.
 3. **Freeform data with a name and types specifier list** &mdash; freeform
-  data beginning with an *optional* types list, as well as a name key. The
-  name key is *required*. Note that for extensibility, the name can be placed
-  *before* the types list, like: `name [Types] description`. In this case,
-  a separating space is not required between the name and types, and you
-  can still use any of the other brackets that the type specifier list allows.
+  data beginning with an *optional* types list, as well as a name key, placed
+  either before or after the types list. The name key is *required*. Note that
+  for extensibility, the name can be placed *before* the types list, like:
+  `name [Types] description`. In this case, a separating space is not required
+  between the name and types, and you can still use any of the other brackets
+  that the type specifier list allows.
 4. **Freeform data with title** &mdash; freeform data where the first line cannot
   be split into multiple lines. The first line must also always refer to the
   "title" portion, and therefore, if there is no title, the first line must
@@ -190,7 +191,7 @@ The following example shows a method that takes a parameter of any type
 that responds to the "read" method:
 
     # Reads from any I/O object.
-    # @param [#read] io the input object to read from
+    # @param io [#read] the input object to read from
     def read(io) io.read end
 
 #### Hashes
@@ -238,9 +239,9 @@ A reference tag literally copies the tag data by the given tag name from the
 specified OBJECT. For instance, a method may copy all {tag:param} tags from
 a given object using the reference tag syntax:
 
-    # @param [String] user the username for the operation
-    # @param [String] host the host that this user is associated with
-    # @param [Time] time the time that this operation took place
+    # @param user [String] the username for the operation
+    # @param host [String] the host that this user is associated with
+    # @param time [Time] the time that this operation took place
     def clean(user, host, time = Time.now) end
 
     # @param (see #clean)

data/lib/rubygems_plugin.rb

@@ -1,4 +1,8 @@
-unless defined?(Gem::DocManager.load_yardoc)
-  require File.expand_path(File.dirname(__FILE__) + '/yard/rubygems/specification')
-  require File.expand_path(File.dirname(__FILE__) + '/yard/rubygems/doc_manager')
+if defined?(Gem::VERSION) && Gem::VERSION >= "2.0."
+  require File.expand_path(File.dirname(__FILE__) + '/yard/rubygems/hook')
+else
+  unless defined?(Gem::DocManager.load_yardoc)
+    require File.expand_path(File.dirname(__FILE__) + '/yard/rubygems/specification')
+    require File.expand_path(File.dirname(__FILE__) + '/yard/rubygems/doc_manager')
+  end
 end

data/lib/yard.rb

@@ -1,14 +1,15 @@
-require File.expand_path('../yard/version.rb', __FILE__)
-
 module YARD
   # The root path for YARD source libraries
   ROOT = File.expand_path(File.dirname(__FILE__))
 
+  require File.join(YARD::ROOT, 'yard', 'version')
+  require File.join(YARD::ROOT, 'yard', 'autoload')
+
   # The root path for YARD builtin templates
   TEMPLATE_ROOT = File.join(ROOT, '..', 'templates')
 
   # @deprecated Use {Config::CONFIG_DIR}
-  CONFIG_DIR = File.expand_path('~/.yard')
+  CONFIG_DIR = Config::CONFIG_DIR
 
   # An alias to {Parser::SourceParser}'s parsing method
   #
@@ -63,9 +64,7 @@ end
 # Backport RubyGems SourceIndex and other classes
 require File.join(YARD::ROOT, 'yard', 'rubygems', 'backports')
 
-['autoload', 'globals'].each do |file|
-  require File.join(YARD::ROOT, 'yard', file)
-end
+require File.join(YARD::ROOT, 'yard', 'globals')
 
 # Load YARD configuration options (and plugins)
 YARD::Config.load

data/lib/yard/autoload.rb

@@ -36,6 +36,7 @@ module YARD
     autoload :MacroObject,          __p('code_objects/macro_object')
     autoload :MethodObject,         __p('code_objects/method_object')
     autoload :ModuleObject,         __p('code_objects/module_object')
+    autoload :NamespaceMapper,      __p('code_objects/namespace_mapper')
     autoload :NamespaceObject,      __p('code_objects/namespace_object')
     autoload :Proxy,                __p('code_objects/proxy')
     autoload :ProxyMethodError,     __p('code_objects/proxy')
@@ -216,6 +217,7 @@ module YARD
       autoload :ListCommand,          __p('server/commands/list_command')
       autoload :LibraryCommand,       __p('server/commands/library_command')
       autoload :LibraryIndexCommand,  __p('server/commands/library_index_command')
+      autoload :RootRequestCommand,   __p('server/commands/root_request_command')
       autoload :SearchCommand,        __p('server/commands/search_command')
       autoload :StaticFileCommand,    __p('server/commands/static_file_command')
     end
@@ -281,15 +283,16 @@ module YARD
     autoload :TemplateOptions, __p('templates/template_options')
   end
 
-  autoload :Config,          __p('config')
-  autoload :Docstring,       __p('docstring')
-  autoload :DocstringParser, __p('docstring_parser')
-  autoload :Logger,          __p('logging')
-  autoload :Options,         __p('options')
-  autoload :Registry,        __p('registry')
-  autoload :RegistryStore,   __p('registry_store')
-  autoload :StubProxy,       __p('serializers/yardoc_serializer')
-  autoload :Verifier,        __p('verifier')
+  autoload :Config,           __p('config')
+  autoload :Docstring,        __p('docstring')
+  autoload :DocstringParser,  __p('docstring_parser')
+  autoload :Logger,           __p('logging')
+  autoload :Options,          __p('options')
+  autoload :Registry,         __p('registry')
+  autoload :RegistryResolver, __p('registry_resolver')
+  autoload :RegistryStore,    __p('registry_store')
+  autoload :StubProxy,        __p('serializers/yardoc_serializer')
+  autoload :Verifier,         __p('verifier')
 end
 
 undef __p

data/lib/yard/cli/stats.rb

@@ -8,7 +8,7 @@ module YARD
       # printed.
       #
       # @see #print_statistics
-      STATS_ORDER = [:files, :modules, :classes, :constants, :methods]
+      STATS_ORDER = [:files, :modules, :classes, :constants, :attributes, :methods]
 
       # @return [Boolean] whether to parse and load registry
       attr_accessor :parse
@@ -125,10 +125,20 @@ module YARD
         output "Constants", *type_statistics(:constant)
       end
 
+      # Statistics for attributes
+      def stats_for_attributes
+        objs = all_objects.select {|m| m.type == :method && m.is_attribute? }
+        objs.uniq! {|m| m.name.to_s.gsub(/=$/, '') }
+        undoc = objs.select {|m| m.docstring.blank? }
+        @undoc_list |= undoc if @undoc_list
+        output "Attributes", objs.size, undoc.size
+      end
+
       # Statistics for methods
       def stats_for_methods
         objs = all_objects.select {|m| m.type == :method }
         objs.reject! {|m| m.is_alias? }
+        objs.reject! {|m| m.is_attribute? }
         undoc = objs.select {|m| m.docstring.blank? }
         @undoc_list |= undoc if @undoc_list
         output "Methods", objs.size, undoc.size

data/lib/yard/cli/yri.rb

@@ -6,12 +6,12 @@ module YARD
     class YRI < Command
       # The location in {YARD::CONFIG_DIR} where the YRI cache file is loaded
       # from.
-      CACHE_FILE = File.expand_path('~/.yard/yri_cache')
+      CACHE_FILE = File.expand_path(File.join(YARD::Config::CONFIG_DIR, 'yri_cache'))
 
       # A file containing all paths, delimited by newlines, to search for
       # yardoc databases.
       # @since 0.5.1
-      SEARCH_PATHS_FILE = File.expand_path('~/.yard/yri_search_paths')
+      SEARCH_PATHS_FILE = File.expand_path(File.join(YARD::Config::CONFIG_DIR, 'yri_search_paths'))
 
       # Default search paths that should be loaded dynamically into YRI. These paths
       # take precedence over all other paths ({SEARCH_PATHS_FILE} and RubyGems

data/lib/yard/code_objects/base.rb

@@ -27,6 +27,7 @@ module YARD
       alias_method :<<, :push
     end
 
+    extend NamespaceMapper
 
     # Namespace separator
     NSEP = '::'
@@ -105,12 +106,20 @@ module YARD
     # though a DSL might create a custom {NamespaceObject} to describe a
     # specific set of objects.
     #
+    # == Separators
+    # Custom classes with different separator tokens should define their own
+    # separators using the {NamespaceMapper.register_separator} method. The
+    # standard Ruby separators have already been defined ('::', '#', '.', etc).
+    #
     # @abstract This class should not be used directly. Instead, create a
-    #   subclass that implements {#path}, {#sep} or {#type}.
+    #   subclass that implements {#path}, {#sep} or {#type}. You might also
+    #   need to register custom separators if {#sep} uses alternate separator
+    #   tokens.
     # @see Registry
     # @see #path
     # @see #[]=
     # @see NamespaceObject
+    # @see NamespaceMapper.register_separator
     class Base
       # The files the object was defined in. To add a file, use {#add_file}.
       # @return [Array<String>] a list of files
@@ -225,7 +234,7 @@ module YARD
         @visibility = :public
         @tags = []
         @docstrings = {}
-        @docstring = Docstring.new('', self)
+        @docstring = Docstring.new!('', [], self)
         @namespace = nil
         self.namespace = namespace
         yield(self) if block_given?
@@ -480,6 +489,7 @@ module YARD
       # @see Templates::Engine#render
       def format(options = {})
         options = options.merge(:object => self)
+        options = options.merge(:type => type) if !options[:type]
         Templates::Engine.render(options)
       end
 

data/lib/yard/code_objects/class_object.rb

@@ -1,4 +1,6 @@
 module YARD::CodeObjects
+  register_separator NSEP, :class
+
   # A ClassObject represents a Ruby class in source code. It is a {ModuleObject}
   # with extra inheritance semantics through the superclass.
   class ClassObject < NamespaceObject

data/lib/yard/code_objects/class_variable_object.rb

@@ -1,4 +1,6 @@
 module YARD::CodeObjects
+  register_separator NSEP, :class_variable
+
   # Represents a class variable inside a namespace. The path is expressed
   # in the form "A::B::@@classvariable"
   class ClassVariableObject < Base

data/lib/yard/code_objects/constant_object.rb

@@ -1,4 +1,6 @@
 module YARD::CodeObjects
+  register_separator NSEP, :constant
+
   # A +ConstantObject+ represents a Ruby constant (not a module or class).
   # To access the constant's (source code) value, use {#value}.
   class ConstantObject < Base

data/lib/yard/code_objects/method_object.rb

@@ -1,4 +1,7 @@
 module YARD::CodeObjects
+  register_separator CSEP, :method
+  register_separator ISEP, :method
+
   # Represents a Ruby method in source
   class MethodObject < Base
     # The scope of the method (+:class+ or +:instance+)

data/lib/yard/code_objects/module_object.rb

@@ -1,4 +1,6 @@
 module YARD::CodeObjects
+  register_separator NSEP, :module
+
   # Represents a Ruby module.
   class ModuleObject < NamespaceObject
     # Returns the inheritance tree of mixins.

data/lib/yard/code_objects/namespace_mapper.rb

@@ -0,0 +1,113 @@
+module YARD
+  module CodeObjects
+    # This module controls registration and accessing of namespace separators
+    # for {Registry} lookup.
+    #
+    # @since 0.9.1
+    module NamespaceMapper
+      # @!group Registering a Separator for a Namespace
+
+      # Registers a separator with an optional set of valid types that
+      # must follow the separator lexically.
+      #
+      # @param sep [String] the separator string for the namespace
+      # @param valid_types [Array<Symbol>] a list of object types that
+      #   must follow the separator. If the list is empty, any type can
+      #   follow the separator.
+      # @example Registering separators for a method object
+      #   # Anything after a "#" denotes a method object
+      #   register_separator "#", :method
+      #   # Anything after a "." denotes a method object
+      #   register_separator ".", :method
+      def register_separator(sep, *valid_types)
+        NamespaceMapper.invalidate
+
+        valid_types.each do |t|
+          NamespaceMapper.rev_map[t] ||= []
+          NamespaceMapper.rev_map[t] << sep
+        end
+
+        NamespaceMapper.map[sep] ||= []
+        NamespaceMapper.map[sep] += valid_types
+      end
+
+      # Clears the map of separators.
+      #
+      # @return [void]
+      def clear_separators
+        NamespaceMapper.invalidate
+        NamespaceMapper.map = {}
+        NamespaceMapper.rev_map = {}
+      end
+
+      # Gets or sets the default separator value to use when no
+      # separator for the namespace can be determined.
+      #
+      # @param value [String, nil] the default separator, or nil to return the
+      #   value
+      # @example
+      #   default_separator "::"
+      def default_separator(value = nil)
+        if value
+          NamespaceMapper.default_separator = Regexp.quote value
+        else
+          NamespaceMapper.default_separator
+        end
+      end
+
+      # @!group Separator and Type Lookup Helpers
+
+      # @return [Array<String>] all of the registered separators
+      def separators
+        NamespaceMapper.map.keys
+      end
+
+      # @return [Regexp] the regexp match of all separators
+      def separators_match
+        NamespaceMapper.map_match
+      end
+
+      # @param sep [String] the separator to return types for
+      # @return [Array<Symbol>] a list of types registered to a separator
+      def types_for_separator(sep)
+        NamespaceMapper.map[sep]
+      end
+
+      # @param type [String] the type to return separators for
+      # @return [Array<Symbol>] a list of separators registered to a type
+      def separators_for_type(type)
+        NamespaceMapper.rev_map[type]
+      end
+
+      # Internal methods to act as a singleton registry
+      class << self
+        # @!visibility private
+
+        # @return [Hash] a mapping of types to separators
+        def map
+          @map ||= {}
+        end
+
+        # @return [Hash] a reverse mapping of separators to types
+        def rev_map
+          @rev_map ||= {}
+        end
+
+        # Invalidates all separators
+        # @return [void]
+        def invalidate
+          @map_match = nil
+        end
+
+        # @return [Regexp] the full list of separators as a regexp match
+        def map_match
+          @map_match ||= @map.keys.map {|k| Regexp.quote k }.join('|')
+        end
+
+        # @return [String] the default separator when no separator can begin
+        #   determined.
+        attr_accessor :default_separator
+      end
+    end
+  end
+end

data/lib/yard/code_objects/namespace_object.rb

@@ -1,4 +1,7 @@
 module YARD::CodeObjects
+  register_separator NSEP, :namespace
+  default_separator NSEP
+
   # A "namespace" is any object that can store other objects within itself.
   # The two main Ruby objects that can act as namespaces are modules
   # ({ModuleObject}) and classes ({ClassObject}).

data/lib/yard/docstring.rb

@@ -171,7 +171,7 @@ module YARD
     def summary
       resolve_reference
       return @summary if @summary
-      stripped = self.gsub(/<.+?>/m, '').gsub(/[\r\n](?![\r\n])/, ' ').strip
+      stripped = self.gsub(/[\r\n](?![\r\n])/, ' ').strip
       num_parens = 0
       idx = length.times do |index|
         case stripped[index, 1]