yard 0.8.0 → 0.8.1

data/lib/yard/handlers/base.rb

@@ -431,7 +431,7 @@ module YARD
       # @since 0.8.0
       def register_docstring(object, docstring = statement.comments, stmt = statement)
         docstring = docstring.join("\n") if Array === docstring
-        parser = DocstringParser.new
+        parser = Docstring.parser
         parser.parse(docstring || "", object, self)
 
         if object && docstring

data/lib/yard/i18n/message.rb

@@ -0,0 +1,56 @@
+require "set"
+
+module YARD
+  module I18n
+    # +Message+ is a translation target message. It has message ID as
+    # {#id} and some properties {#locations} and {#comments}.
+    #
+    # @since 0.8.1
+    class Message
+      # @return [String] the message ID of the trnslation target message.
+      attr_reader :id
+
+      # @return [Set] the set of locations. Location is an array of 
+      # path and line number where the message is appered.
+      attr_reader :locations
+
+      # @return [Set] the set of comments for the messages.
+      attr_reader :comments
+
+      # Creates a trasnlate target message for message ID +id+.
+      #
+      # @param [String] id the message ID of the translate target message.
+      def initialize(id)
+        @id = id
+        @locations = Set.new
+        @comments = Set.new
+      end
+
+      # Adds location information for the message.
+      #
+      # @param [String] path the path where the message appears.
+      # @param [Integer] line the line number where the message appears.
+      # @return [void]
+      def add_location(path, line)
+        @locations << [path, line]
+      end
+
+      # Adds a comment for the message.
+      #
+      # @param [String] comment the comment for the message to be added.
+      # @return [void]
+      def add_comment(comment)
+        @comments << comment unless comment.nil?
+      end
+
+      # @param [Message] other the +Message+ to be compared.
+      # @return [Boolean] checks whether this message is equal to another.
+      def ==(other)
+        other.is_a?(self.class) and
+          @id == other.id and
+          @locations == other.locations and
+          @comments == other.comments
+      end
+    end
+  end
+end

data/lib/yard/i18n/messages.rb

@@ -0,0 +1,55 @@
+module YARD
+  module I18n
+    # Acts as a container for {Message} objects.
+    #
+    # @since 0.8.1
+    class Messages
+      include Enumerable
+
+      # Creates a new container.
+      def initialize
+        @messages = {}
+      end
+
+      # Enumerates each {Message} in the container.
+      #
+      # @yieldparam [Message] message the next message object in
+      #   the enumeration.
+      # @return [void]
+      def each(&block)
+        @messages.each_value(&block)
+      end
+
+      # @param [String] id the message ID to perform a lookup on.
+      # @return [Message, nil] a registered message for the given +id+,
+      #   or nil if no message for the ID is found.
+      def [](id)
+        @messages[id]
+      end
+
+      # Registers a {Message}, the mssage ID of which is +id+. If
+      # corresponding +Message+ is already registered, the previously
+      # registered object is returned.
+      #
+      # @param [String] id the ID of the message to be registered.
+      # @return [Message] the registered +Message+.
+      def register(id)
+        @messages[id] ||= Message.new(id)
+      end
+
+      # Checks if this messages list is equal to another messages list.
+      #
+      # @param [Messages] other the container to compare.
+      # @return [Boolean] whether +self+ and +other+ is equivalence or not.
+      def ==(other)
+        other.is_a?(self.class) and
+          @messages == other.messages
+      end
+
+      protected
+
+      # @return [Hash{String=>Message}] the set of message objects
+      attr_reader :messages
+    end
+  end
+end

data/lib/yard/i18n/pot_generator.rb

@@ -62,26 +62,15 @@ module YARD
     # @see http://www.gnu.org/software/gettext/manual/html_node/PO-Files.html
     #   GNU gettext manual about details of PO file
     class PotGenerator
-      # Extracted messages. Key is a translation target message and
-      # value is properties of the translation target message. The
-      # properties are added to the msgid entry for the translation
-      # target message. The properties are +:locations+ and
-      # +:comments+.
+      # Extracted messages.
       #
-      # +:locations+ is an array of location. Location is an array of
-      # path and line number of the translation target message is
-      # appeared. Each location is prepended +:relative_base_path+
-      # that is passed on creating a +PotGenerator+ instance.
-      #
-      # +:comments+ is an array of comment. All comments are added to
-      # the msgid entry for the translation target message.
-      #
-      # @api private
-      # @return [Hash{String => Hash{:locations => Array<Array[String, Integer]>, :comments => Array<String>}}]
+      # @return [Messages]
+      # @since 0.8.1
       attr_reader :messages
 
       # Creates a POT generator that uses +relative_base_path+ to
-      # generate locations for a msgid.
+      # generate locations for a msgid. +relative_base_path+ is
+      # prepended to all locations.
       #
       # @param [String] relative_base_path a relative working
       #   directory path from a directory path that has created .pot
@@ -89,7 +78,7 @@ module YARD
       def initialize(relative_base_path)
         @relative_base_path = relative_base_path
         @extracted_objects = {}
-        @messages = {}
+        @messages = Messages.new
       end
 
       # Parses {CodeObjects::Base} objects and stores extracted msgids
@@ -118,17 +107,27 @@ module YARD
 
       # Generates POT from +@messages+.
       #
+      # One PO file entry is generated from a +Message+ in
+      # +@messages+.
+      #
+      # Locations of the +Message+ are used to generate the reference
+      # line that is started with "#: ". +relative_base_path+ passed
+      # when the generater is created is prepended to each path in location.
+      #
+      # Comments of the +Message+ are used to generate the
+      # translater-comment line that is started with "# ".
+      #
       # @return [String] POT format string
       def generate
         pot = header
-        sorted_messages = @messages.sort_by do |message, options|
-          sorted_locations = (options[:locations] || []).sort_by do |location|
+        sorted_messages = @messages.sort_by do |message|
+          sorted_locations = message.locations.sort_by do |location|
             location
           end
           sorted_locations.first || []
         end
-        sorted_messages.each do |message, options|
-          generate_message(pot, message, options)
+        sorted_messages.each do |message|
+          generate_message(pot, message)
         end
         pot
       end
@@ -158,30 +157,30 @@ msgstr ""
 EOH
       end
 
-      def generate_message(pot, message, options)
-        options[:comments].compact.uniq.each do |comment|
+      def generate_message(pot, message)
+        message.comments.sort.each do |comment|
           pot << "# #{comment}\n" unless comment.empty?
         end
-        options[:locations].uniq.each do |path, line|
+        message.locations.sort.each do |path, line|
           pot << "#: #{@relative_base_path}/#{path}:#{line}\n"
         end
-        escaped_message = escape_message(message)
-        escaped_message = escaped_message.gsub(/\n/, "\\\\n\"\n\"")
-        pot << "msgid \"#{escaped_message}\"\n"
+        escaped_message_id = escape_message_id(message.id)
+        escaped_message_id = escaped_message_id.gsub(/\n/, "\\\\n\"\n\"")
+        pot << "msgid \"#{escaped_message_id}\"\n"
         pot << "msgstr \"\"\n"
         pot << "\n"
         pot
       end
 
-      def escape_message(message)
-        message.gsub(/(\\|")/) do
+      def escape_message_id(message_id)
+        message_id.gsub(/(\\|")/) do
           special_character = $1
           "\\#{special_character}"
         end
       end
 
-      def add_message(text)
-        @messages[text] ||= {:locations => [], :comments => []}
+      def register_message(id)
+        @messages.register(id)
       end
 
       def extract_documents(object)
@@ -196,11 +195,11 @@ EOH
         end
 
         if object.group
-          message = add_message(object.group)
+          message = register_message(object.group)
           object.files.each do |path, line|
-            message[:locations] << [path, line]
+            message.add_location(path, line)
           end
-          message[:comments] << object.path unless object.path.empty?
+          message.add_comment(object.path) unless object.path.empty?
         end
 
         docstring = object.docstring
@@ -210,11 +209,11 @@ EOH
             case type
             when :paragraph
               paragraph, line_no = *args
-              message = add_message(paragraph.rstrip)
+              message = register_message(paragraph.rstrip)
               object.files.each do |path, line|
-                message[:locations] << [path, (docstring.line || line) + line_no]
+                message.add_location(path, (docstring.line || line) + line_no)
               end
-              message[:comments] << object.path unless object.path.empty?
+              message.add_comment(object.path) unless object.path.empty?
             else
               raise "should not reach here: unexpected type: #{type}"
             end
@@ -234,26 +233,26 @@ EOH
         return if tag.name.nil?
         return if tag.name.is_a?(String) and tag.name.empty?
         key = "tag|#{tag.tag_name}|#{tag.name}"
-        message = add_message(key)
-        tag.object.files.each do |file|
-          message[:locations] << file
+        message = register_message(key)
+        tag.object.files.each do |path, line|
+          message.add_location(path, line)
         end
         tag_label = "@#{tag.tag_name}"
         tag_label << " [#{tag.types.join(', ')}]" if tag.types
-        message[:comments] << tag_label
+        message.add_comment(tag_label)
       end
 
       def extract_tag_text(tag)
         return if tag.text.nil?
         return if tag.text.empty?
-        message = add_message(tag.text)
-        tag.object.files.each do |file|
-          message[:locations] << file
+        message = register_message(tag.text)
+        tag.object.files.each do |path, line|
+          message.add_location(path, line)
         end
         tag_label = "@#{tag.tag_name}"
         tag_label << " [#{tag.types.join(', ')}]" if tag.types
         tag_label << " #{tag.name}" if tag.name
-        message[:comments] << tag_label
+        message.add_comment(tag_label)
       end
 
       def extract_paragraphs(file)
@@ -263,13 +262,13 @@ EOH
             case type
             when :attribute
               name, value, line_no = *args
-              message = add_message(value)
-              message[:locations] << [file.filename, line_no]
-              message[:comments] << name
+              message = register_message(value)
+              message.add_location(file.filename, line_no)
+              message.add_comment(name)
             when :paragraph
               paragraph, line_no = *args
-              message = add_message(paragraph.rstrip)
-              message[:locations] << [file.filename, line_no]
+              message = register_message(paragraph.rstrip)
+              message.add_location(file.filename, line_no)
             else
               raise "should not reach here: unexpected type: #{type}"
             end

data/lib/yard/tags/directives.rb

@@ -386,7 +386,7 @@ module YARD
         return if tag.text.empty?
         handler = parser.handler
         object = parser.object
-        self.parser = DocstringParser.new(parser.library)
+        self.parser = parser.class.new(parser.library)
         parser.parse(tag.text, object, handler)
       end
 

data/lib/yard/tags/library.rb

@@ -57,16 +57,17 @@ module YARD
     # @see Directive
     class Library
       class << self
+        # @return [SymbolHash{Symbol=>String}] the map of tag names and their
+        #   respective display labels.
         attr_reader :labels
 
+        # @!attribute instance
+        # @return [Library] the main Library instance object.
         def instance
           @instance ||= new
         end
 
-        def default_factory
-          @default_factory ||= DefaultFactory.new
-        end
-
+        # @!attribute default_factory
         # Replace the factory object responsible for parsing tags by setting
         # this to an object (or class) that responds to +parse_TAGNAME+ methods
         # where +TAGNAME+ is the name of the tag.
@@ -80,6 +81,10 @@ module YARD
         # @param [Class, Object] factory the factory that parses all tags
         #
         # @see DefaultFactory
+        def default_factory
+          @default_factory ||= DefaultFactory.new
+        end
+
         def default_factory=(factory)
           @default_factory = factory.is_a?(Class) ? factory.new : factory
         end
@@ -256,19 +261,32 @@ module YARD
         self.factory = factory
       end
 
+      # @param [#to_s] tag_name the name of the tag to look for
+      # @return [Boolean] whether a tag by the given name is registered in
+      #   the library.
       def has_tag?(tag_name)
         tag_name && respond_to?(self.class.tag_method_name(tag_name))
       end
 
+      # Creates a new {Tag} object with a given tag name and data
+      # @return [Tag] the newly created tag object
       def tag_create(tag_name, tag_buf)
         send(self.class.tag_method_name(tag_name), tag_buf)
       end
 
+      # @param [#to_s] tag_name the name of the tag to look for
+      # @return [Boolean] whether a directive by the given name is registered in
+      #   the library.
       def has_directive?(tag_name)
         tag_name && respond_to?(self.class.directive_method_name(tag_name))
       end
 
-      # @return [Directive]
+      # Creates a new directive with tag information and a docstring parser
+      # object.
+      # @param [String] tag_name the name of the tag
+      # @param [String] tag_buf the tag data
+      # @param [DocstringParser] parser the parser object parsing the docstring
+      # @return [Directive] the newly created directive
       def directive_create(tag_name, tag_buf, parser)
         meth = self.class.factory_method_for(tag_name)
         tag = send_to_factory(tag_name, meth, tag_buf)
@@ -277,9 +295,10 @@ module YARD
       end
 
       # @!macro yard.tag.transitive
-      #   @note This tag is *transitive*. If this tag is applied on a
+      #   @note This tag is *transitive*. If it is applied on a
       #     namespace (module or class), it will automatically be
-      #     applied to all children objects of that namespace.
+      #     applied to all children objects of that namespace unless
+      #     it is redefined on the child object.
 
       # Marks a class/module/method as abstract with optional
       # implementor information.
@@ -425,23 +444,31 @@ module YARD
       #   def load_page(url) end
       define_tag "Parameters",         :param,       :with_types_and_name
 
-      # Defines an object as private. This exists for classes,
-      # modules and constants that do not obey Ruby's visibility rules. For
-      # instance, an inner class might be considered "private", though Ruby
-      # would make no such distinction. By declaring the @private tag, the
-      # class can be hidden from documentation by using the +--no-private+
-      # command-line switch to yardoc (see {file:README.md}).
+      # Declares that the _logical_ visibility of an object is private.
+      # In other words, it specifies that this method should be marked
+      # private but cannot due to Ruby's visibility restrictions. This
+      # exists for classes, modules and constants that do not obey Ruby's
+      # visibility rules. For instance, an inner class might be considered
+      # "private", though Ruby would make no such distinction.
+      #
+      # This tag is meant to be used in conjunction with the +--no-private+
+      # command-line option, and is required to actually remove these objects
+      # from documentation output. See {file:README.md} for more information on
+      # switches.
+      #
+      # If you simply want to set the API visibility of a method, you should
+      # look at the {tag:api} tag instead.
       #
       # @note This method is not recommended for hiding undocumented or
       #   "unimportant" methods. This tag should only be used to mark objects
       #   private when Ruby visibility rules cannot do so. In Ruby 1.9.3, you
       #   can use +private_constant+ to declare constants (like classes or
       #   modules) as private, and should be used instead of +@private+.
-      # @note If +@private+ is applied to a class or module, all methods within
-      #   that namespace are also marked private.
+      # @macro yard.tag.transitive
       # @example
       #   # @private
       #   class InteralImplementation; end
+      # @see tag:api
       # @yard.signature
       define_tag "Private",            :private
 

data/lib/yard/verifier.rb

@@ -140,8 +140,8 @@ module YARD
     #
     # @return [String] the parsed expression
     def parse_expression(expr)
-      expr = expr.gsub(/@@(\w+)/, 'object.tags("\1")')
-      expr = expr.gsub(/@(\w+)/, 'object.tag("\1")')
+      expr = expr.gsub(/@@(?:(\w+)|\{([\w\.]+)\})/, 'object.tags("\1\2")')
+      expr = expr.gsub(/@(?:(\w+)|\{([\w\.]+)\})/, 'object.tag("\1\2")')
       expr
     end
   end