yard 0.8.3 → 0.8.4

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2007-2012 Loren Segal
+Copyright (c) 2007-2013 Loren Segal
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/README.md

@@ -6,10 +6,10 @@ YARD: Yay! A Ruby Documentation Tool
 **Git**:          [http://github.com/lsegal/yard](http://github.com/lsegal/yard)   
 **Author**:       Loren Segal  
 **Contributors**: See Contributors section below    
-**Copyright**:    2007-2012    
+**Copyright**:    2007-2013    
 **License**:      MIT License    
-**Latest Version**: 0.8.3 (codename "Rainier")    
-**Release Date**: October 15th 2012    
+**Latest Version**: 0.8.4    
+**Release Date**: February 4th 2013    
 
 Synopsis
 --------
@@ -286,6 +286,17 @@ More options can be seen by typing `yard graph --help`, but here is an example:
 
 ## Changelog
 
+- **February.4.13**: 0.8.4 release
+    - Add `-B/--bind` switch to yard server (#593, #608)
+    - Add CodeObjects::Base#title for plugins to customize how object
+      links display (#646)
+    - Disable linking objects filtered out by verifiers (#645)
+    - Allow macro expansion on class methods (#632)
+    - Expand newly attached macro on first DSL method call (#631)
+    - Disable RubyGems plugin in Ruby 2.0 (#627)
+    - Fix line range for class/module node bodies (#626)
+    - Search extended modules for attached DSL macros (#553)
+
 - **October.14.12**: 0.8.3 release
     - Add `--non-transitive-tag` to disable tag transitivity (#571)
     - Support --db inside .yardopts for graph/server commands (#583, #586)
@@ -562,7 +573,7 @@ http://github.com/lsegal/yard/contributors
 
 ## Copyright
 
-YARD © 2007-2012 by [Loren Segal](mailto:lsegal@soen.ca). YARD is
+YARD © 2007-2013 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/docs/GettingStarted.md

@@ -51,7 +51,7 @@ In YARD, we would simply define our method as:
 
     # Converts the object into textual markup given a specific format.
     #
-    # @param [Symbol] format the format type, `:text` or `:html`
+    # @param format [Symbol] the format type, `:text` or `:html`
     # @return [String] the object converted into the expected format.
     def to_format(format = :html)
       # format the object
@@ -105,7 +105,7 @@ from that docstring/tag into your current object. Consider the example:
 
     class MyWebServer
       # Handles a request
-      # @param [Request] request the request object
+      # @param request [Request] the request object
       # @return [String] the resulting webpage
       def get(request) "hello" end
 
@@ -134,7 +134,7 @@ and return tags:
 
     class MyWebServer
       # Handles a GET request
-      # @param [Request] request the request object
+      # @param request [Request] the request object
       # @return [String] the resulting webpage
       def get(request) "hello" end
 
@@ -165,8 +165,8 @@ with or without a types field.
 The list of types is in the form `[type1, type2, ...]` and is mostly free-form,
 so we can also specify duck-types or constant values. For example:
 
-    # @param [#to_s] argname any object that responds to `#to_s`
-    # @param [true, false] argname only true or false
+    # @param argname [#to_s] any object that responds to `#to_s`
+    # @param argname [true, false] only true or false
 
 Note the latter example can be replaced by the meta-type "Boolean".
 Another meta-type is "void", which stands for "no meaningful value"
@@ -177,7 +177,7 @@ List types can be specified in the form `CollectionClass<ElementType, ...>`.
 For instance, consider the following Array that holds a set of Strings and
 Symbols:
 
-    # @param [Array<String, Symbol>] list the list of strings and symbols.
+    # @param list [Array<String, Symbol>] the list of strings and symbols.
 
 We mentioned that these type fields are "mostly" free-form. In truth, they
 are defined "by convention". To view samples of common type specifications

data/docs/WhatsNew.md

@@ -17,6 +17,7 @@
 13. **Single object db now default (multi-object db unsupported)** (0.8.0)
 14. **Added `--api` tag to generate documentation for API sets** (0.8.1)
 15. **Added `--non-transitive-tag` to disable transitive tag** (0.8.3)
+16. **Added `-B/--bind` to bind to a port in yard server** (0.8.4)
 
 ## Directives (new behavioural tag syntax) (0.8.0)
 
@@ -292,6 +293,10 @@ when you define it on a class. Only the class itself has a specific
 Which will avoid classifying treating @api as a transitive tag
 when parsing modules and classes.
 
+## Added `-B/--bind` to bind to a port in yard server (0.8.4)
+
+You can now bind the `yard server` command to a given local port
+with `yard server -B PORT` or `yard server --bind PORT`.
 
 # What's New in 0.7.x?
 

data/lib/yard/autoload.rb

@@ -127,6 +127,7 @@ module YARD
     end
 
     autoload :Base,                       __p('handlers/base')
+    autoload :HandlerAborted,             __p('handlers/base')
     autoload :NamespaceMissingError,      __p('handlers/base')
     autoload :Processor,                  __p('handlers/processor')
   end
@@ -230,6 +231,7 @@ module YARD
     autoload :AttributeDirective,  __p('tags/directives')
     autoload :DefaultFactory,      __p('tags/default_factory')
     autoload :DefaultTag,          __p('tags/default_tag')
+    autoload :Directive,           __p('tags/directives')
     autoload :EndGroupDirective,   __p('tags/directives')
     autoload :GroupDirective,      __p('tags/directives')
     autoload :Library,             __p('tags/library')

data/lib/yard/cli/graph.rb

@@ -26,7 +26,7 @@ module YARD
       #   :format => :dot
       attr_reader :options
 
-      # The set of objects to include in the graph.
+      # The set of objects to include in the graph.
       attr_reader :objects
 
       # Creates a new instance of the command-line utility
@@ -50,7 +50,6 @@ module YARD
       # @param [Array<String>] args each tokenized argument
       def run(*args)
         parse_arguments(*args)
-        Registry.load
 
         contents = objects.map do |o|
           o.format(options.merge(:serialize => false))
@@ -112,6 +111,8 @@ module YARD
         common_options(opts)
         parse_options(opts, args)
 
+        Registry.load
+
         options.verifier = Verifier.new("object.type != :method || #{visibilities.uniq.inspect}.include?(object.visibility)")
         if args.first
           @objects = args.map {|o| Registry.at(o) }.compact

data/lib/yard/cli/server.rb

@@ -181,6 +181,9 @@ module YARD
         opts.on('-d', '--daemon', 'Daemonizes the server process') do
           server_options[:daemonize] = true
         end
+        opts.on('-B HOST', '--bind', 'The host address to bind to') do |host|
+          server_options[:Host] = host.to_s
+        end        
         opts.on('-p PORT', '--port', 'Serves documentation on PORT') do |port|
           server_options[:Port] = port.to_i
         end

data/lib/yard/cli/yardoc.rb

@@ -441,6 +441,7 @@ module YARD
       # @return [void]
       # @since 0.8.3
       def apply_locale
+        YARD::I18n::Locale.default = options.locale
         options.files.each do |file|
           file.locale = options.locale
         end

data/lib/yard/code_objects/base.rb

@@ -50,7 +50,7 @@ module YARD
     CONSTANTMATCH = /[A-Z]\w*/
 
     # Regular expression to match namespaces (const A or complex path A::B)
-    NAMESPACEMATCH = /(?:(?:#{NSEPQ})?#{CONSTANTMATCH})+/
+    NAMESPACEMATCH = /(?:(?:#{NSEPQ}\s*)?#{CONSTANTMATCH})+/
 
     # Regular expression to match a method name
     METHODNAMEMATCH = /[a-zA-Z_]\w*[!?=]?|[-+~]\@|<<|>>|=~|===?|<=>|[<>]=?|\*\*|[-\/+%^&*~`|]|\[\]=?/
@@ -136,9 +136,10 @@ module YARD
       # @return [String] a line of source
       attr_accessor :signature
 
-      # The documentation string associated with the object
+      # The non-localized documentation string associated with the object
       # @return [Docstring] the documentation string
-      attr_reader :docstring
+      # @since 0.8.4
+      attr_reader :base_docstring
 
       # Marks whether or not the method is conditionally defined at runtime
       # @return [Boolean] true if the method is conditionally defined at runtime
@@ -218,9 +219,8 @@ module YARD
         @source_type = :ruby
         @visibility = :public
         @tags = []
-        @docstring = Docstring.new('', self)
-        @docstring_extra = nil
-        @docstring_extra_tags = nil
+        @docstrings = {}
+        @base_docstring = Docstring.new('', self)
         @namespace = nil
         self.namespace = namespace
         yield(self) if block_given?
@@ -237,7 +237,7 @@ module YARD
           ivar = "@#{ivar}"
           other.instance_variable_set(ivar, instance_variable_get(ivar))
         end
-        other.docstring = docstring.to_raw
+        other.docstring = @base_docstring.to_raw
         other
       end
 
@@ -365,19 +365,25 @@ module YARD
         end
       end
 
-      undef docstring
-      def docstring
-        return @docstring if !@docstring_extra
-        case @docstring
-        when Proxy
-          return @docstring_extra
-        when Base
-          @docstring = @docstring.docstring + @docstring_extra
-          @docstring.add_tag(*@docstring_extra_tags)
-          @docstring_extra = nil
-          @docstring_extra_tags = nil
+      # The documentation string associated with the object
+      #
+      # @param [String, I18n::Locale] locale (I18n::Locale.default)
+      #   the locale of the documentation string.
+      # @return [Docstring] the documentation string
+      def docstring(locale = I18n::Locale.default)
+        if locale.nil?
+          @base_docstring.resolve_reference
+          return @base_docstring
+        end
+
+        if locale.is_a?(String)
+          locale_name = locale
+          locale = nil
+        else
+          locale_name = locale.name
         end
-        @docstring
+        @docstrings[locale_name] ||=
+          translate_docstring(locale || Registry.locale(locale_name))
       end
 
       # Attaches a docstring to a code object by parsing the comments attached to the statement
@@ -387,16 +393,11 @@ module YARD
       #   the comments attached to the code object to be parsed
       #   into a docstring and meta tags.
       def docstring=(comments)
-        if comments =~ /\A\s*\(see (\S+)\s*\)(?:\s|$)/
-          path, extra = $1, $'
-          @docstring_extra = Docstring.new(extra, self)
-          @docstring_extra_tags = Docstring === comments ? comments.tags : []
-          @docstring_extra.add_tag(*@docstring_extra_tags)
-          @docstring = Proxy.new(namespace, path)
+        @docstrings.clear
+        if Docstring === comments
+          @base_docstring = comments
         else
-          @docstring_extra = nil
-          @docstring_extra_tags = nil
-          @docstring = Docstring === comments ? comments : Docstring.new(comments, self)
+          @base_docstring = Docstring.new(comments, self)
         end
       end
 
@@ -405,7 +406,7 @@ module YARD
       #
       # @return [Symbol] the type of code object this represents
       def type
-        self.class.name.split(/#{NSEPQ}/).last.gsub(/Object$/, '').downcase.to_sym
+        self.class.name.split('::').last.gsub(/Object$/, '').downcase.to_sym
       end
 
       # Represents the unique path of the object. The default implementation
@@ -426,6 +427,16 @@ module YARD
       end
       alias_method :to_s, :path
 
+      # @note
+      #   Override this method if your object has a special title that does
+      #   not match the {#path} attribute value. This title will be used
+      #   when linking or displaying the object.
+      # @return [String] the display title for an object
+      # @see 0.8.4
+      def title
+        path
+      end
+
       # @param [Base, String] other another code object (or object path)
       # @return [String] the shortest relative path from this object to +other+
       # @since 0.5.3
@@ -509,6 +520,14 @@ module YARD
       # @see Docstring#has_tag?
       def has_tag?(name); docstring.has_tag?(name) end
 
+      # Add tags to the {#docstring}
+      # @see Docstring#add_tag
+      # @since 0.8.4
+      def add_tag(*tags)
+        @docstrings.clear
+        @base_docstring.add_tag(*tags)
+      end
+
       # @return whether or not this object is a RootObject
       def root?; false end
 
@@ -532,7 +551,7 @@ module YARD
       # @since 0.8.0
       def copyable_attributes
         vars = instance_variables.map {|ivar| ivar.to_s[1..-1] }
-        vars -= %w(docstring namespace name path)
+        vars -= %w(base_docstring docstrings namespace name path)
         vars
       end
 
@@ -548,6 +567,17 @@ module YARD
         indent = last ? last[/^([ \t]*)/, 1].length : 0
         source.gsub(/^[ \t]{#{indent}}/, '')
       end
+
+      def translate_docstring(locale)
+        @base_docstring.resolve_reference
+        return @base_docstring if locale.nil?
+
+        text = I18n::Text.new(@base_docstring)
+        localized_text = text.translate(locale)
+        docstring = Docstring.new(localized_text, self)
+        docstring.add_tag(*@base_docstring.tags)
+        docstring
+      end
     end
   end
 end

data/lib/yard/code_objects/extra_file_object.rb

@@ -58,7 +58,7 @@ module YARD::CodeObjects
     end
     alias to_s inspect
 
-    def type; 'extra_file' end
+    def type; :extra_file end
 
     def ==(other)
       return false unless self.class === other

data/lib/yard/code_objects/proxy.rb

@@ -96,6 +96,7 @@ module YARD
       end
       alias to_s path
       alias to_str path
+      alias title path
 
       # @return [Boolean]
       def is_a?(klass)

data/lib/yard/docstring.rb

@@ -118,13 +118,23 @@ module YARD
       end
     end
 
+    def to_s
+      resolve_reference
+      super
+    end
+
     # Replaces the docstring with new raw content. Called by {#all=}.
     # @param [String] content the raw comments to be parsed
     def replace(content, parse = true)
       content = content.join("\n") if content.is_a?(Array)
       @tags, @ref_tags = [], []
-      @all = content
-      super(parse ? parse_comments(content) : content)
+      if parse
+        super(parse_comments(content))
+      else
+        @all = content
+        @unresolved_reference = nil
+        super(content)
+      end
     end
     alias all= replace
 
@@ -136,6 +146,7 @@ module YARD
     # @return [Docstring] a new copied docstring
     # @since 0.7.0
     def dup
+      resolve_reference
       obj = super
       %w(all summary tags ref_tags).each do |name|
         val = instance_variable_get("@#{name}")
@@ -155,6 +166,7 @@ module YARD
     # Gets the first line of a docstring to the period or the first paragraph.
     # @return [String] The first line or paragraph of the docstring; always ends with a period.
     def summary
+      resolve_reference
       return @summary if @summary
       open_parens = ['{', '(', '[']
       close_parens = ['}', ')', ']']
@@ -298,6 +310,26 @@ module YARD
 
     # @endgroup
 
+    # Resolves unresolved other docstring reference if there is
+    # unresolved reference. Does nothing if there is no unresolved
+    # reference.
+    #
+    # Normally, you don't need to call this method
+    # explicitly. Resolving unresolved reference is done implicitly.
+    #
+    # @return [void]
+    def resolve_reference
+      loop do
+        return if @unresolved_reference.nil?
+        return if CodeObjects::Proxy === @unresolved_reference
+
+        reference, @unresolved_reference = @unresolved_reference, nil
+        resolved_tags = reference.docstring.tags
+        self.all = [reference.docstring.all, @all].join("\n")
+        add_tag(*resolved_tags)
+      end
+    end
+
     private
 
     # Maps valid reference tags
@@ -319,6 +351,8 @@ module YARD
     def parse_comments(comments)
       parser = self.class.parser
       parser.parse(comments, object)
+      @all = parser.raw_text
+      @unresolved_reference = parser.reference
       add_tag(*parser.tags)
       parser.text
     end

data/lib/yard/docstring_parser.rb

@@ -54,6 +54,11 @@ module YARD
     #   not attached to any object.
     attr_accessor :object
 
+    # @return [CodeObjects::Base, nil] the object referenced by
+    #   the docstring being parsed. May be nil if the docstring doesn't
+    #   refer to any object.
+    attr_accessor :reference
+
     # @return [Handlers::Base, nil] the handler parsing this
     #   docstring. May be nil if this docstring parser is not
     #   initialized through
@@ -79,6 +84,7 @@ module YARD
       @directives = []
       @library = library
       @object = nil
+      @reference = nil
       @handler = nil
       @state = OpenStruct.new
     end
@@ -106,8 +112,8 @@ module YARD
     def parse(content, object = nil, handler = nil)
       @object = object
       @handler = handler
-      @raw_text = content
-      text = parse_content(content)
+      @reference, @raw_text = detect_reference(content)
+      text = parse_content(@raw_text)
       # Remove trailing/leading whitespace / newlines
       @text = text.gsub(/\A[\r\n\s]+|[\r\n\s]+\Z/, '')
       call_directives_after_parse
@@ -232,6 +238,23 @@ module YARD
 
     private
 
+    def namespace
+      if object
+        object.namespace
+      else
+        nil
+      end
+    end
+
+    def detect_reference(content)
+      if content =~ /\A\s*\(see (\S+)\s*\)(?:\s|$)/
+        path, extra = $1, $'
+        [CodeObjects::Proxy.new(namespace, path), extra]
+      else
+        [nil, content]
+      end
+    end
+
     # @!group Parser Callback Methods
 
     # Calls the {Directive#after_parse} callback on all the