yard 0.8.7.6 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2f723063cf267909777160a18d322d5dd78acace
-  data.tar.gz: 8ff1809f4067f82eafc3667601f75882b1a1aabc
+  metadata.gz: 601891a952ecd1662fcfaceb1160b3b664bf56d2
+  data.tar.gz: 979f166173832405bfcea7ba9b2aae33de865f5f
 SHA512:
-  metadata.gz: de4c7904f326053e2ad7dc88d3e63c2915689e74216b9f94df603fb20b39dd35a52d398882dfd3c8d73a2a0e7b74727a17420db745d05e1f6d732d265c65cddd
-  data.tar.gz: d75edfe99a18af7a74638c490501b328682f2aeb8d216624e8a4b1d48a25d2be66779eedca64d263b73addd6385af70782a672cb62087435a8a8dd9fd9a0e348
+  metadata.gz: 8753f755361ae434ae739fd354182f8c5ed6fc5469b6c50d2af9a99bd73694d246b1c4e200cec05f8cc84f674070c2921e6bf8bd947836684f8679ab4896ec8a
+  data.tar.gz: 1ef05a31710af7aba1837cdbbfa54cad528b7e412e02c37433a8ebb07e6dfc8691e522f17a0ff2e90d4cb5a1d581af383bafb0b43b954c7841a21bc5b15faf0f

data/CHANGELOG.md

@@ -1,4 +1,23 @@
-# HEAD
+# 0.9.0 - July 4th, 2016
+
+Special thanks to Alex Dowad, MSP-Greg, and Alex McLain for their extended
+contributions to this version.
+
+- (Breaking Change): Replaced default template with an updated "frameless" version.
+  This change may affect backward compatibility if custom templates made modifications
+  to `default/fulldoc/html`, specifically the index or navigation lists.
+- Added support for Ruby 2.1+ decorator style method declaration syntax. YARD now
+  supports:
+    private def foo(x, y) end
+- Metadata headers in extra files can now be escaped from rendering by enclosing them
+  in HTML comment blocks (`<!--\n @metadata here... \n-->`). Ensure that the opening
+  comment tag is alone on the first line of the file to use this functionality.
+- Improved parsing of various CRuby coding styles.
+- Fixed issue with binary image assets when using `yard server`.
+- Fixed deprecation warnings from Rake 10.x.
+- Tests updated for RSpec 3.
+
+# 0.8.7.6 - October 26, 2014
 
 - Support using `@option` tag on keyword arg splat parameter. (#729)
 - Add `.stats_options` for `YardocTask`. (#800, #801)

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2007-2013 Loren Segal
+Copyright (c) 2007-2016 Loren Segal
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation
@@ -19,4 +19,4 @@ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -3,7 +3,7 @@
 [![Homepage](http://img.shields.io/badge/home-yardoc.org-blue.svg)](http://yardoc.org)
 [![GitHub](http://img.shields.io/badge/github-lsegal/yard-blue.svg)](http://github.com/lsegal/yard)
 [![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/yard/frames)
-[![Gitter Chat](http://img.shields.io/badge/chat-gitter.im-orange.svg)](https://gitter.im/lsegal/yard)
+[![IRC Chat](https://img.shields.io/badge/chat-%23yard%20@%20freenode-orange.svg)](irc://irc.freenode.net/yard)
 
 [![Gem Version](https://badge.fury.io/rb/yard.svg)](http://github.com/lsegal/yard/releases)
 [![Build Status](https://travis-ci.org/lsegal/yard.svg?branch=master)](https://travis-ci.org/lsegal/yard)
@@ -288,7 +288,7 @@ See {file:CHANGELOG.md} for a list of changes.
 
 ## License
 
-YARD © 2007-2014 by [Loren Segal](mailto:lsegal@soen.ca). YARD is
+YARD © 2007-2016 by [Loren Segal](mailto:lsegal@soen.ca). YARD is
 licensed under the MIT license except for some files which come from the
 RDoc/Ruby distributions. Please see the {file:LICENSE} and {file:LEGAL}
 documents for more information.

data/Rakefile

@@ -13,7 +13,7 @@ end
 
 desc "Installs the gem"
 task :install => :gem do
-  sh "gem install yard-#{YARD::VERSION}.gem --no-rdoc --no-ri"
+  sh "gem install yard-#{YARD::VERSION}.gem --no-document"
 end
 
 begin

data/docs/GettingStarted.md

@@ -186,7 +186,62 @@ and recommended conventions for writing type specifications, see
 conventions may change every now and then, although we are working on a more
 "formal" type specification proposal.
 
-## Documenting DSL Methods
+## Documenting Attributes
+
+To document a Ruby attribute, add documentation text above the attribute
+definition.
+
+    # Controls the amplitude of the waveform.
+    # @return [Numeric] the amplitude of the waveform
+    attr_accessor :amplitude
+
+As a short-hand syntax for declaring reader and writer attribute pairs,
+YARD will automatically wire up the correct method types and information
+by simply defining documentation in the `@return` tag. For example,
+the following declaration will show the correct information for the
+`waveform` attribute, both for the getter's return type and the
+setter's value parameter type: 
+
+    # @return [Numeric] the amplitude of the waveform
+    attr_accessor :amplitude
+
+In this case, the most important details for the attribute are the
+object type declaration and its descriptive text.
+
+### Documentation for a Separate Attribute Writer
+
+Usually an attribute will get and set a value using the same syntax,
+so there is no reason to have separate documentation for an attribute
+writer. In the above `amplitude` case, the `Numeric` type is both used
+for the getter and setter types.
+
+Sometimes, however, you might want to have separate documentation
+for the getter and setter. In this case, you would still add
+the documentation text to the getter declaration (or `attr_accessor`)
+and use `@overload` tags to declare the separate docstrings. For example:
+
+    # @overload amplitude
+    #   Gets the current waveform amplitude.
+    #   @return [Numeric] the amplitude of the waveform
+    # @overload amplitude=(value)
+    #   Sets the new amplitude.
+    #   @param value [Numeric] the new amplitude value
+    #   @note The new amplitude will only take effect if {#restart}
+    #     is called on the stream.
+
+Note that by default, YARD exposes the reader portion of the attribute
+in HTML output. If you have separate `attr_reader` and `attr_writer`
+declarations, make sure to put your documentation (for both reader
+and writer methods) on the reader declaration using `@overload`
+tags as described above. For example:
+
+    # @overload ...documentation here...
+    attr_reader :amplitude
+
+    # This documentation will be ignored by YARD.
+    attr_writer :amplitude
+
+## Documenting Custom DSL Methods
 
 Application code in Ruby often makes use of DSL style metaprogrammed methods.
 The most common is the `attr_accessor` method, which of course has built-in
@@ -520,6 +575,17 @@ might not be descriptive enough, so YARD allows you to specify a full title:
 Currently all other meta-data is hidden from view, though accessible
 programmatically using the {YARD::CodeObjects::ExtraFileObject} class.
 
+You can wrap the meta data section in an HTML comment to prevent it
+from being displayed in rendered markdown on GitHub:
+
+    <!--
+    # @markup markdown
+    # @title The Best Library in the World!
+    # @author The Author Name
+    -->
+
+    This is the best library you will ever meet. Lipsum ...
+
 <a name="config"></a>
 
 ## Configuring YARD
@@ -571,16 +637,32 @@ document covers the basics of how YARD's templating system works.
 
 ## Plugin Support
 
-As of 0.4, YARD will automatically load any gem named with the prefix of
-`yard-` or `yard_`. You can use this to load a custom plugin that
+YARD will allow any RubyGem installed on your system (or in your Gemfile)
+to be loaded as a plugin provided it has a name with the prefix of
+`yard-` or `yard_`. In order to load a plugin, use the `--plugin`
+switch with the short-name (name minus the `yard-` prefix) or full-name
+of the gem:
+
+    $ gem install yard-custom-plugin
+    ...
+    $ yard doc --plugin custom-plugin
+    or
+    $ yard doc --plugin yard-custom-plugin
+
+Note: you can also put this switch in your `.yardopts` file. See the
+      `.yardopts` section above for more information.
+
+You can use this functionality to load a custom plugin that
 [extend](#extending) YARD's functionality. A good example of this
 is the [yard-rspec][yard-rspec] plugin, which adds [RSpec][rspec] specifications
 to your documentation (`yardoc` and `yri`). You can try it out by installing
 the gem or cloning the project and trying the example:
 
-    $ gem install yard-rspec -s http://gemcutter.org
-    or
-    $ git clone git://github.com/lsegal/yard-spec-plugin
+    $ gem install yard-rspec
+
+ You can then load the plugin with:
+
+    $ yard doc --plugin rspec
 
 YARD also provides a way to temporarily disable plugins on a per-user basis.
 To disable a plugin create the file `~/.yard/ignored_plugins` with a list

data/docs/templates/default/fulldoc/html/full_list_tag.erb

@@ -1,7 +1,9 @@
-<% n = 1 %>
+<% even_odd = 'odd'  %>
 <% collect_tags.each do |tag| %>
-  <li class="r<%= n %> <%= tag.object.has_tag?(:deprecated) ? 'deprecated' : '' %>">
-    <span class="object_link"><%= tag_link(tag) %></span>
+  <li class="<%= even_odd %> <%= tag.object.has_tag?(:deprecated) ? 'deprecated' : '' %>">
+    <div class="item">
+      <span class="object_link"><%= tag_link(tag) %></span>
+    </div>
   </li>
-  <% n = n == 2 ? 1 : 2 %>
+  <% even_odd = (even_odd == 'even' ? 'odd' : 'even') %>
 <% end %>

data/lib/yard/autoload.rb

@@ -46,6 +46,7 @@ module YARD
     autoload :BUILTIN_MODULES,      __p('code_objects/base')
     autoload :BUILTIN_EXCEPTIONS,   __p('code_objects/base')
     autoload :CONSTANTMATCH,        __p('code_objects/base')
+    autoload :CONSTANTSTART,        __p('code_objects/base')
     autoload :METHODMATCH,          __p('code_objects/base')
     autoload :METHODNAMEMATCH,      __p('code_objects/base')
     autoload :NAMESPACEMATCH,       __p('code_objects/base')
@@ -114,6 +115,7 @@ module YARD
       autoload :ClassVariableHandler,     __p('handlers/ruby/class_variable_handler')
       autoload :CommentHandler,           __p('handlers/ruby/comment_handler')
       autoload :ConstantHandler,          __p('handlers/ruby/constant_handler')
+      autoload :DecoratorHandlerMethods,  __p('handlers/ruby/decorator_handler_methods')
       autoload :DSLHandler,               __p('handlers/ruby/dsl_handler')
       autoload :DSLHandlerMethods,        __p('handlers/ruby/dsl_handler_methods')
       autoload :ExceptionHandler,         __p('handlers/ruby/exception_handler')
@@ -125,6 +127,7 @@ module YARD
       autoload :ModuleFunctionHandler,    __p('handlers/ruby/module_function_handler')
       autoload :PrivateClassMethodHandler, __p('handlers/ruby/private_class_method_handler')
       autoload :PrivateConstantHandler,   __p('handlers/ruby/private_constant_handler')
+      autoload :PublicClassMethodHandler, __p('handlers/ruby/public_class_method_handler')
       autoload :StructHandlerMethods,     __p('handlers/ruby/struct_handler_methods')
       autoload :VisibilityHandler,        __p('handlers/ruby/visibility_handler')
       autoload :YieldHandler,             __p('handlers/ruby/yield_handler')

data/lib/yard/cli/yardoc.rb

@@ -276,7 +276,7 @@ module YARD
         super(*args)
 
         # Last minute modifications
-        self.files = ['{lib,app}/**/*.rb', 'ext/**/*.c'] if self.files.empty?
+        self.files = Parser::SourceParser::DEFAULT_PATH_GLOB if self.files.empty?
         self.files.delete_if {|x| x =~ /\A\s*\Z/ } # remove empty ones
         readme = Dir.glob('README{,*[^~]}').first
         readme ||= Dir.glob(files.first).first if options.onefile

data/lib/yard/code_objects/base.rb

@@ -49,11 +49,14 @@ module YARD
     # Regular expression to match constant name
     CONSTANTMATCH = /[A-Z]\w*/
 
+    # Regular expression to match the beginning of a constant
+    CONSTANTSTART = /^[A-Z]/
+
     # Regular expression to match namespaces (const A or complex path A::B)
     NAMESPACEMATCH = /(?:(?:#{NSEPQ}\s*)?#{CONSTANTMATCH})+/
 
     # Regular expression to match a method name
-    METHODNAMEMATCH = /[a-zA-Z_]\w*[!?=]?|[-+~]\@|<<|>>|=~|===?|<=>|[<>]=?|\*\*|[-\/+%^&*~`|]|\[\]=?/
+    METHODNAMEMATCH = /[a-zA-Z_]\w*[!?=]?|[-+~]\@|<<|>>|=~|===?|![=~]?|<=>|[<>]=?|\*\*|[-\/+%^&*~`|]|\[\]=?/
 
     # Regular expression to match a fully qualified method def (self.foo, Class.foo).
     METHODMATCH = /(?:(?:#{NAMESPACEMATCH}|[a-z]\w*)\s*(?:#{CSEPQ}|#{NSEPQ})\s*)?#{METHODNAMEMATCH}/

data/lib/yard/code_objects/extra_file_object.rb

@@ -93,6 +93,8 @@ module YARD::CodeObjects
           end
         when /^\s*#\s*@(\S+)\s*(.+?)\s*$/
           attributes[$1] = $2
+        when /^\s*<!--\s*$/, /^\s*-->\s*$/
+          # Ignore HTML comments
         else
           cut_index = index
           break
@@ -125,4 +127,4 @@ module YARD::CodeObjects
       text.translate(YARD::Registry.locale(locale))
     end
   end
-end
+end

data/lib/yard/code_objects/proxy.rb

@@ -242,12 +242,12 @@ module YARD
         if @namespace.root?
           (@imethod ? ISEP : "") + name.to_s
         elsif @origname
-          if @origname =~ /^[A-Z]/
+          if @origname =~ CONSTANTSTART
             @origname
           else
             [namespace.path, @origname].join
           end
-        elsif name.to_s =~ /^[A-Z]/ # const
+        elsif name.to_s =~ CONSTANTSTART
           name.to_s
         else # class meth?
           [namespace.path, name.to_s].join(CSEP)

data/lib/yard/docstring.rb

@@ -172,15 +172,20 @@ module YARD
       resolve_reference
       return @summary if @summary
       stripped = self.gsub(/<.+?>/m, '').gsub(/[\r\n](?![\r\n])/, ' ').strip
-      open_parens = ['{', '(', '[']
-      close_parens = ['}', ')', ']']
       num_parens = 0
       idx = length.times do |index|
         case stripped[index, 1]
-        when ".", "\r", "\n"
+        when "."
           next_char = stripped[index + 1, 1].to_s
-          if num_parens == 0 && next_char =~ /^\s*$/
-            break index - 1
+          break index - 1 if num_parens <= 0 && next_char =~ /^\s*$/
+        when "\r", "\n"
+          next_char = stripped[index + 1, 1].to_s
+          if next_char =~ /^\s*$/
+            if stripped[index - 1, 1] == '.'
+              break index - 2
+            else
+              break index - 1
+            end
           end
         when "{", "(", "["
           num_parens += 1
@@ -207,7 +212,7 @@ module YARD
         when Tags::OverloadTag
           tag_text = "@#{tag.tag_name} #{tag.signature}\n"
           unless tag.docstring.blank?
-            tag_text += "\n" + tag.docstring.all.gsub(/\r?\n/, "\n  ")
+            tag_text += "\n  " + tag.docstring.all.gsub(/\r?\n/, "\n  ")
           end
         when Tags::OptionTag
           tag_text = "@#{tag.tag_name} #{tag.name}"

data/lib/yard/handlers/base.rb

@@ -483,9 +483,8 @@ module YARD
       # @return [void]
       # @since 0.8.0
       def register_transitive_tags(object)
-        return unless object
+        return unless object && !object.namespace.is_a?(Proxy)
         Tags::Library.transitive_tags.each do |tag|
-          next if object.namespace.is_a?(Proxy)
           next unless object.namespace.has_tag?(tag)
           next if object.has_tag?(tag)
           object.add_tag(*object.namespace.tags(tag))

data/lib/yard/handlers/c/base.rb

@@ -65,6 +65,25 @@ module YARD
           var.empty? ? nil : P(var)
         end
 
+        def ensure_variable_defined!(var, max_retries = 1)
+          retries, object = 0, nil
+
+          loop do
+            object = namespace_for_variable(var)
+            break unless object.is_a?(Proxy)
+
+            if retries <= max_retries
+              log.debug "Missing namespace variable #{var} in file `#{parser.file}', moving it to the back of the line."
+              parser.parse_remaining_files
+            else
+              raise NamespaceMissingError, object
+            end
+            retries += 1
+          end
+
+          object
+        end
+
         def namespaces
           globals.cruby_namespaces ||= {}
         end

data/lib/yard/handlers/c/handler_methods.rb

@@ -7,7 +7,7 @@ module YARD
 
         def handle_class(var_name, class_name, parent, in_module = nil)
           parent = nil if parent == "0"
-          namespace = in_module ? namespace_for_variable(in_module) : Registry.root
+          namespace = in_module ? ensure_variable_defined!(in_module) : Registry.root
           if namespace.nil?
             raise Parser::UndocumentableError, "class #{class_name}. " +
               "Cannot find definition for parent namespace."
@@ -29,7 +29,7 @@ module YARD
         end
 
         def handle_module(var_name, module_name, in_module = nil)
-          namespace = in_module ? namespace_for_variable(in_module) : Registry.root
+          namespace = in_module ? ensure_variable_defined!(in_module) : Registry.root
           if namespace.nil?
             raise Parser::UndocumentableError, "module #{module_name}. " +
               "Cannot find definition for parent namespace."
@@ -51,6 +51,16 @@ module YARD
           end
 
           namespace = namespace_for_variable(var_name)
+
+          # Is this method being defined on a core Ruby class or module?
+          if namespace.is_a?(Proxy)
+            if var_name =~ /^rb_c(\w+)/ && YARD::CodeObjects::BUILTIN_CLASSES.include?($1)
+              namespace = namespaces[var_name] = YARD::CodeObjects::ClassObject.new(:root, $1)
+            elsif var_name =~ /^rb_m(\w+)/ && YARD::CodeObjects::BUILTIN_MODULES.include?($1)
+              namespace = namespaces[var_name] = YARD::CodeObjects::ModuleObject.new(:root, $1)
+            end
+          end
+
           return if namespace.nil? # XXX: raise UndocumentableError might be too noisy.
           register MethodObject.new(namespace, name, scope) do |obj|
             register_visibility(obj, visibility)
@@ -93,8 +103,12 @@ module YARD
         end
 
         def handle_constants(type, var_name, const_name, value)
-          return unless type == 'const'
-          namespace = namespace_for_variable(var_name)
+          return unless type =~ /^const$|^global_const$/
+          if type == 'global_const'
+            namespace = :root
+          else
+            namespace = namespace_for_variable(var_name)
+          end
           register ConstantObject.new(namespace, const_name) do |obj|
             obj.source_type = :c
             obj.value = value
@@ -147,6 +161,7 @@ module YARD
           if src_stmt = symbols[symbol]
             register_file_info(object, src_stmt.file, src_stmt.line, true)
             register_source(object, src_stmt)
+            record_parameters(object, symbol, src_stmt)
             unless src_stmt.comments.nil? || src_stmt.comments.source.empty?
               register_docstring(object, src_stmt.comments.source, src_stmt)
               return # found docstring
@@ -157,10 +172,15 @@ module YARD
           # so look in overrides
           override_comments.each do |name, override_comment|
             next unless override_comment.file == file
-            name = name.gsub(/::([^:]+?)\Z/, '.\1')
-            just_method_name = name.gsub(/\A.+(#|::|\.)/, '')
-            just_method_name = 'initialize' if just_method_name == 'new'
-            if object.path == name || object.name.to_s == just_method_name
+            name = name.gsub(/::([^:\.#]+?)\Z/, '.\1')
+
+            path = if name =~ /\.|#/ # explicit namespace in override comment
+              object.path
+            else
+              object.name.to_s
+            end
+
+            if path == name || path == name.sub(/new$/, 'initialize') || path == name.sub('.', '#')
               register_docstring(object, override_comment.source, override_comment)
               return
             end
@@ -171,6 +191,20 @@ module YARD
             register_docstring(object, statement.comments.source, statement)
           end
         end
+
+        def record_parameters(object, symbol, src)
+          # use regex to extract comma-delimited list of parameters from cfunc definition
+          if src.source =~ /VALUE\s+#{symbol}\(([^)]*)\)\s*\{/m
+            params = $~[1].split(/\s*,\s*/)
+            # cfunc for a "varargs" method has params "int argc, VALUE *argv"
+            if params[0] =~ /int\s+argc/ && params[1] =~ /VALUE\s*\*\s*argv/
+              object.parameters = [['*args', nil]]
+            else
+              # the first cfunc argument is the 'self' argument, we don't need that
+              object.parameters = params.drop(1).map { |s| [s[/VALUE\s+(\S+)/, 1], nil] }
+            end
+          end
+        end
       end
     end
   end