RubyGems - yard - Versions diffs - 0.2.0 - Mend

yard 0.2.0

Potentially problematic release.

This version of yard might be problematic. Click here for more details.

Files changed (31) hide show

data/LICENSE.txt +22 -0
data/README.pdf +0 -0
data/bin/yardoc +73 -0
data/bin/yri +4 -0
data/lib/code_object.rb +340 -0
data/lib/formatter.rb +78 -0
data/lib/handlers/all_handlers.rb +2 -0
data/lib/handlers/attribute_handler.rb +46 -0
data/lib/handlers/class_handler.rb +29 -0
data/lib/handlers/class_variable_handler.rb +9 -0
data/lib/handlers/code_object_handler.rb +104 -0
data/lib/handlers/constant_handler.rb +11 -0
data/lib/handlers/exception_handler.rb +20 -0
data/lib/handlers/method_handler.rb +27 -0
data/lib/handlers/mixin_handler.rb +9 -0
data/lib/handlers/module_handler.rb +9 -0
data/lib/handlers/visibility_handler.rb +7 -0
data/lib/handlers/yield_handler.rb +31 -0
data/lib/namespace.rb +98 -0
data/lib/quick_doc.rb +104 -0
data/lib/ruby_lex.rb +1318 -0
data/lib/source_parser.rb +246 -0
data/lib/tag_library.rb +162 -0
data/lib/tag_type.rb +155 -0
data/lib/yard.rb +3 -0
data/templates/html_formatter.erb +455 -0
data/test/fixtures/docstring.txt +23 -0
data/test/fixtures/docstring2.txt +4 -0
data/test/test_code_object.rb +66 -0
data/test/test_namespace.rb +10 -0
metadata +78 -0

data/LICENSE.txt ADDED Viewed

@@ -0,0 +1,22 @@
+Copyright (c) 2007 Loren Segal
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+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.

data/README.pdf ADDED Viewed

Binary file

data/bin/yardoc ADDED Viewed

@@ -0,0 +1,73 @@
+#!/usr/bin/ruby
+require File.dirname(__FILE__) + '/../lib/yard'
+include YARD
+if ARGV[0] == "-h"
+  puts "yardoc 0.2.0"
+  return
+end
+Dir.mkdir("doc") unless FileTest.directory?("doc")
+Namespace.load(Namespace::DEFAULT_YARDOC_FILE, true)
+ac = File.open("doc/all-classes.html", "w")
+ac.puts <<-eof
+<html>
+  <head>
+    <base target="main" />
+  </head>
+  <body>
+  <h3>All Classes</h3>
+eof
+meths = []
+Namespace.all.sort.each do |path|
+  object = Namespace.at(path)
+  if object.is_a?(MethodObject) && object.visibility == :public
+    meths << [object.name, object]
+  end
+  next unless object.is_a? ClassObject
+  ac.puts "<a href='" + path.gsub("::","_") + ".html'>" + path + "</a><br />"
+  File.open("doc/#{path.gsub('::','_')}.html", "w") {|f| f.write(object.format) }
+end
+ac.puts "</body></html>"
+ac.close
+File.open("doc/all-methods.html", "w") do |f|
+  f.puts <<-eof
+    <html>
+      <head>
+        <base target="main" />
+      </head>
+      <body>
+      <h3>All Methods</h3>
+eof
+  meths.sort {|a,b| a.first <=> b.first }.each do |name, object|
+    f.puts "<a href='" + object.parent.path.gsub("::", "_") + ".html##{object.scope}_method-#{name}'>#{name}</a><br />"
+  end
+end
+if ARGV[0]
+  main_page = ARGV[0]
+else
+  main_page = Namespace.all.sort.find {|name| Namespace.at(name).is_a? YARD::ClassObject }
+end
+main_page = main_page.gsub("::", "_") + ".html"
+File.open("doc/index.html", "w") do |f|
+  f.puts <<-eof
+  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+    "http://www.w3.org/TR/html4/loose.dtd">
+  <html>
+    <head>
+      <meta http-equiv="Content-type" content="text/html; charset=utf-8">
+      <title>Ruby Classes</title>
+    </head>
+    <frameset cols="250,*">
+      <frameset rows="*,40%">
+        <frame src="all-classes.html">
+        <frame src="all-methods.html">
+      </frameset>
+      <frame name="main" src="#{main_page}">
+    </frameset>
+  </html>
+eof
+end

data/bin/yri ADDED Viewed

@@ -0,0 +1,4 @@
+#!/usr/bin/ruby
+require File.dirname(__FILE__) + '/../lib/yard'
+require File.dirname(__FILE__) + '/../lib/quick_doc'
+YARD::QuickDoc.new(ARGV[0])

data/lib/code_object.rb ADDED Viewed

@@ -0,0 +1,340 @@
+require File.dirname(__FILE__) + '/tag_library'
+require File.dirname(__FILE__) + '/formatter'
+module YARD #:nodoc:
+  ##
+  # The documentation parser is responsible for parsing the docstring into
+  # text and saving the meta tags attached to it
+  #
+  # @author Loren Segal
+  class CodeObject
+    attr_reader :source, :full_source, :file, :line, :docstring, :attributes
+    attr_reader :name, :type
+    attr_accessor :visibility, :scope
+    attr_accessor :parent, :children
+    ##
+    # Creates a new code object with necessary information such as the object's name (not full path),
+    # it's type (:class, :module, :method, etc.), visibility (:public, :private, :protected) and scope
+    # (:instance or :class level). Optionally you can specify a parent object and comments too, but these
+    # can also be assigned later through the {#parent=} and {#attach_docstring} methods.
+    #
+    # @param [String] name        the name of the object, not including its namespace ('initialize' for this method)
+    # @param [Symbol] type        the type of object this is, including (but not limited to):
+    #                             :module, :class, :method, :constant
+    # @param [Symbol] visibility  :public, :protected or :private depending on the visibility of the object
+    # @param [Symbol] scope       :instance or :class depending on if the object is instance level or class level.
+    #                             Instance level objects use the '#' character to separate from their parent instead of '::'
+    # @param [CodeObject] parent  The parent of this object. Without a parent this object will not be registered
+    #                             in the {Namespace}
+    # @param [String] comments    Comments to be parsed as a docstring for the object.
+    # @return [CodeObject] the created code object
+    # @yieldparam [CodeObject] _self the object is yielded during initialization to perform any initialization operations
+    #                                on it more conveniently.
+    # @see #attach_docstring
+    # @see #parent=
+    def initialize(name, type, visibility = :public, scope = :instance, parent = nil, comments = nil)
+      @name, @type, @visibility, @scope = name, type, visibility.to_sym, scope.to_sym
+      @tags, @attributes, @children = [], {}, []
+      self.parent = parent
+      attach_docstring(comments)
+      yield(self) if block_given?
+    end
+    def to_s
+      "#{visibility} #{type} #{path}"
+    end
+    ##
+    # Attaches source code to a code object with an optional file location
+    #
+    # @param [Statement, String] statement the +Statement+ holding the source code
+    #                                      or the raw source as a +String+ for the
+    #                                      definition of the code object only (not the block)
+    # @param [String] file the filename the source resides in
+    def attach_source(statement, file = nil)
+      if statement.is_a? String
+        @source = statement
+      else
+        @source = statement.tokens.to_s
+        @line = statement.tokens.first.line_no
+        attach_full_source statement.tokens.to_s + (statement.block.to_s rescue "")
+      end
+      @file = file
+    end
+    ##
+    # Manually attaches full source code for an object given the source
+    # as a +String+
+    #
+    # @param [String] source the source code for the object
+    def attach_full_source(source)
+      @full_source = source
+    end
+    ##
+    # Attaches a docstring to a code oject by parsing the comments attached to the statement
+    # and filling the {#tags} and {#docstring} methods with the parsed information.
+    #
+    # @param [String, Array<String>] comments the comments attached to the code object to be
+    #                                         parsed into a docstring and meta tags.
+    def attach_docstring(comments)
+      parse_comments(comments) if comments
+    end
+    def [](key)
+      @attributes[key.to_sym]
+    end
+    def []=(key, value)
+      @attributes[key.to_sym] = value
+    end
+    ##
+    # Sets the parent object and registers the object path with
+    # the {Namespace}. If the object was already registered
+    # to an old path, it will be removed from the namespace.
+    #
+    # @param [CodeObject] value the new parent object
+    # @see Namespace
+    def parent=(value)
+      # Delete old object path if there was one
+      Namespace.instance.namespace.delete(path) if parent
+      @parent = value
+      # Register new path with namespace
+      Namespace.add_object(self) if value
+    end
+    ##
+    # See if the method call exists in the attributes hash, and return
+    # it. Otherwise send the missing method call up the stack.
+    #
+    # @param meth the method name called. This method is checked in the
+    #             attributes hash
+    # @param args the arguments to the call
+    # @param block an optional block for the call
+    def method_missing(meth, *args, &block)
+      return self[meth] if self[meth]
+      super
+    end
+    ##
+    # Returns the unique path for this code object. The resulting path will be
+    # a Ruby style path name of the namespace the object resides in plus the
+    # object name delimited by a "::" or "#" depending on if the object is an
+    # instance level object or a class level object.
+    #
+    # Example:
+    #
+    #
+    #
+    def path
+      [(parent.path if parent && parent.type != :root), name].join(scope == :instance ? "#" : "::").gsub(/^::/, '')
+    end
+    ##
+    # Convenience method to return the first tag
+    # object in the list of tag objects of that name
+    #
+    # Example:
+    #   doc = YARD::Documentation.new("@return zero when nil")
+    #   doc.tag("return").text  # => "zero when nil"
+    #
+    # @param [#to_s] name the tag name to return data for
+    # @return [BaseTag] the first tag in the list of {#tags}
+    def tag(name)
+      name = name.to_s
+      @tags.find {|tag| tag.tag_name == name }
+    end
+    ##
+    # Returns a list of tags specified by +name+ or all tags if +name+ is not specified.
+    #
+    # @param name the tag name to return data for, or nil for all tags
+    # @return [Array<BaseTag>] the list of tags by the specified tag name
+    def tags(name = nil)
+      return @tags if name.nil?
+      name = name.to_s
+      @tags.select {|tag| tag.tag_name == name }
+    end
+    ##
+    # Returns true if at least one tag by the name +name+ was declared
+    #
+    # @param [String] name the tag name to search for
+    # @return [Boolean] whether or not the tag +name+ was declared
+    def has_tag?(name)
+      name = name.to_s
+      @tags.any? {|tag| tag.tag_name == name }
+    end
+    ##
+    # Returns a code object formatted as a given type, defaults to html.
+    #
+    # @param [Symbol] format the output format to generate
+    # @return [String] the code object formatted by the specified +format+
+    def format(type = :html)
+      Formatter.new.format(self, type)
+    end
+    private
+      ##
+      # Parses out comments split by newlines into a new code object
+      #
+      # @param [Array<String>, String] comments the newline delimited
+      #                                         array of comments. If the comments
+      #                                         are passed as a String, they will
+      #                                         be split by newlines.
+      def parse_comments(comments)
+        return if comments.empty?
+        meta_match = /^\s*@(\S+)\s*(.*)/
+        comments = comments.split(/\r?\n/) if comments.is_a? String
+        @tags, @docstring = [], ""
+        indent, last_indent = comments.first[/^\s*/].length, 0
+        tag_name, tag_klass, tag_buf = nil, nil, ""
+        # Add an extra line to catch a meta directive on the last line
+        (comments+['']).each do |line|
+          indent = line[/^\s*/].length
+          if (indent < last_indent && tag_name) || line == '' || line =~ meta_match
+            tag_method = "#{tag_name}_tag"
+            if tag_name && TagLibrary.respond_to?(tag_method)
+              @tags << TagLibrary.send(tag_method, tag_buf.squeeze(" "))
+            end
+            tag_name, tag_buf = nil, ''
+          end
+          # Found a meta tag
+          if line =~ meta_match
+            tag_name, tag_buf = $1, $2
+          elsif indent >= last_indent && tag_name
+            # Extra data added to the tag on the next line
+            tag_buf << line
+          else
+            # Regular docstring text
+            @docstring << line << "\n"
+          end
+          last_indent = indent
+        end
+        # Remove trailing/leading whitespace / newlines
+        @docstring.gsub!(/\A[\r\n\s]+|[\r\n\s]+\Z/, '')
+      end
+  end
+  class CodeObjectWithMethods < CodeObject
+    def initialize(name, type, parent = nil, comments = nil)
+      super(name, type, :public, :class, parent, comments) do |obj|
+        obj[:instance_methods] = {}
+        obj[:class_methods] = {}
+        obj[:constants] = {}
+        obj[:class_variables] = {}
+        obj[:mixins] = []
+        yield(obj) if block_given?
+      end
+    end
+    def inherited_class_methods
+      inherited_methods(:class)
+    end
+    def inherited_instance_methods
+      inherited_methods(:instance)
+    end
+    def inherited_methods(scopes = [:class, :instance])
+      [scopes].flatten.each do |scope|
+        full_mixins.inject({}) {|hash, mixin| hash.update(mixin.send(scope + "_methods")) }
+      end
+    end
+    def full_mixins
+      mixins.collect {|mixin| Namespace.find_from_path(self, mixin).path rescue mixin }
+    end
+  end
+  class ModuleObject < CodeObjectWithMethods
+    def initialize(name, *args)
+      super(name, :module, *args) do |obj|
+        yield(obj) if block_given?
+      end
+    end
+  end
+  class ClassObject < CodeObjectWithMethods
+    BASE_OBJECT = "Object"
+    def initialize(name, superclass = BASE_OBJECT, *args)
+      super(name, :class, *args) do |obj|
+        obj[:attributes] = {}
+        obj[:superclass] = superclass
+        yield(obj) if block_given?
+      end
+    end
+    def inherited_methods(scopes = [:class, :instance])
+      inherited_methods = super
+      superobject = Namespace.find_from_path(path, superclass)
+      if superobject && superobject.path != path # avoid infinite loop
+        [scopes].flatten.each do |scope|
+          inherited_methods.update(superobject.send(scope + "_methods"))
+          inherited_methods.update(superobject.send("inherited_#{scope}_methods"))
+        end
+      end
+      inherited_methods
+    end
+    def superclasses
+      superobject = Namespace.find_from_path(path, superclass)
+      return [superclass] if superobject.nil?
+      [superobject.path] + superobject.superclasses
+    end
+    def inheritance_tree
+      full_mixins.reverse + superclasses
+    end
+  end
+  class MethodObject < CodeObject
+    # @param [String] name the name of the method
+    # @param visibility the object visibility (:public, :private, :protected)
+    # @param [String] scope the object scope (:instance, :class)
+    # @param [CodeObjectWithMethods] parent the object that holds this method
+    def initialize(name, visibility, scope, parent, comments = nil)
+      super(name, :method, visibility, scope, parent, comments) do |obj|
+        parent["#{scope}_methods".to_sym].update(name.to_s => obj)
+        yield(obj) if block_given?
+      end
+    end
+  end
+  class ConstantObject < CodeObject
+    def initialize(name, parent = nil, statement = nil)
+      super(name, :constant, :public, :class, parent) do |obj|
+        if statement
+          obj.attach_docstring(statement.comments)
+          obj.attach_source(statement)
+          parent[:constants].update(name.to_s => obj)
+          yield(obj) if block_given?
+        end
+      end
+    end
+  end
+  class ClassVariableObject < CodeObject
+    def initialize(statement, parent)
+      name, value = *statement.tokens.to_s.gsub(/\r?\n/, '').split(/\s*=\s*/, 2)
+      super(name, :class_variable, :public, :class, parent) do |obj|
+        obj.parent[:class_variables].update(name => obj)
+        obj.attach_docstring(statement.comments)
+        obj.attach_source("#{name} = #{value}")
+      end
+    end
+  end
+end

data/lib/formatter.rb ADDED Viewed

@@ -0,0 +1,78 @@
+require 'erb'
+require 'rdoc/markup/simple_markup'
+require 'rdoc/markup/simple_markup/to_html'
+SMP = SM::SimpleMarkup.new
+SMH = SM::ToHtml.new
+module YARD
+  ##
+  # Formats the code objects in the {Namespace} in a variety of formats
+  #
+  # @author Loren Segal
+  # @version 1.0
+  class Formatter
+    OUTPUT_FORMATS = [ :html, :xhtml, :xml ]
+    ##
+    # Formats an object as a specified output format. Default is +:html+.
+    #
+    # @param [String, CodeObject] object the code object to format or the path to the code object
+    # @param [Symbol] format the output format to generate documentation in.
+    #                        Defaults to +:html+, which is a synonym for +:xhtml+.
+    # @see OUTPUT_FORMATS
+    def format(object, format = :html)
+      object = Namespace.at(object) if object.is_a? String
+      erb = File.join(template_directory, "#{format}_formatter.erb")
+      @object = object
+      ERB.new(IO.read(erb), nil, ">").result(binding)
+    end
+    ##
+    # Directory for templates. Override this to load your own templates
+    def template_directory
+      File.join(File.dirname(__FILE__), '..', 'templates')
+    end
+  end
+  protected
+    def link_to_path(name, from_path = nil, label = nil)
+      return "<a href='#instance_method-#{name[1..-1]}'>#{label || name}</a>" if name =~ /^\#/ && from_path.nil?
+      if from_path
+        obj = Namespace.find_from_path(from_path, name)
+      else
+        obj = Namespace.at(name)
+      end
+      label = name if label.nil?
+      if obj
+        file = obj.parent.path.gsub("::","_") + ".html"
+        case obj
+          when ConstantObject
+            "<a href='#{file}#const-#{obj.name}'>#{label}</a>"
+          when ClassVariableObject
+            "<a href='#{file}#cvar-#{obj.name}'>#{label}</a>"
+          when MethodObject
+            "<a href='#{file}##{obj.scope}_method-#{obj.name}'>#{label}</a>"
+          else
+            "<a href='#{obj.path.gsub("::","_")}.html'>#{label}</a>"
+        end
+      else
+        name
+      end
+    end
+    def to_html(text, path = @object)
+      resolve_links(SMP.convert(text || "", SMH).gsub(/\A<p>|<\/p>\Z/,''), path)
+    end
+    def resolve_links(text, path)
+      t, re = text, /\{(.+?)\}/
+      while t =~ re
+        t.sub!(re, "<tt>" + link_to_path($1, path) + "</tt>")
+      end
+      t
+    end
+end