yard 0.2.3 → 0.2.3.2

data/.yardopts

@@ -0,0 +1,12 @@
+-
+docs/WHATSNEW.markdown
+docs/GETTING_STARTED.markdown
+docs/OVERVIEW.markdown
+docs/CODE_OBJECTS.markdown
+docs/TAGS.markdown
+docs/PARSER.markdown
+docs/HANDLERS.markdown
+docs/GENERATORS.markdown
+docs/FAQ.markdown
+docs/GLOSSARY.markdown
+LICENSE

data/README.markdown

@@ -1,5 +1,5 @@
-YARD Release 0.2.3 (June 7th 2009) 
-===================================
+YARD Release 0.2.3.2 (July 6th 2009)
+=====================================
 
 **Homepage**:  [http://yard.rubyforge.org](http://yard.rubyforge.org)   
 **IRC**:       **Join us on IRC in #yard on irc.freenode.net!**   
@@ -178,6 +178,24 @@ More options can be seen by typing `yard-graph --help`, but here is an example:
 CHANGELOG
 ---------
 
+- **July.06.09**: 0.2.3.2 release
+    - Fix Textile hard-break issues
+    - Add description for @see tag to use as link title in HTML docs.
+    - Add --title CLI option to specify a title for HTML doc files.
+    - Add custom.css file that can be overridden with various custom
+      styelsheet declarations. To use this, simply add `default/fulldoc/html/custom.css`
+      inside your code directory and use the `-t` template directory yardoc CLI
+      option to point to that template directory (the dir holding 'default').
+    - Add support in `yardoc` CLI to specify extra files (formerly --files)
+      by appending "- extra files here" after regular source files. Example:
+
+            yardoc --private lib/**/*.rb - FAQ LICENSE
+
+- **Jun.13.09**: 0.2.3.1 release.
+    - Add a RubyGems 1.3.2+ plugin to generate YARD documentation instead of
+      RDoc. To take advantage of this plugin, set `has_rdoc = 'yard'` in your
+      .gemspec file.
+
 - **Jun.07.09**: 0.2.3 release. See the {file:WHATSNEW.markdown} file for a 
   list of important new features.
 

data/Rakefile

@@ -27,10 +27,11 @@ Spec::Rake::SpecTask.new("specs") do |t|
   $DEBUG = true if ENV['DEBUG']
   t.spec_opts = ["--format", "specdoc", "--colour"]
   t.spec_files = Dir["spec/**/*_spec.rb"].sort
-  # t.rcov = true
+  t.rcov = true if ENV['RCOV']
   t.rcov_opts = ['-x', '_spec\.rb$,spec_helper\.rb$']
 end
+task :spec => :specs
 
 YARD::Rake::YardocTask.new do |t|
   t.after = lambda { `cp -R docs/images/ doc/images/` }
-end
+end

data/lib/rubygems_plugin.rb

@@ -0,0 +1,91 @@
+require 'rubygems/specification'
+require 'rubygems/doc_manager'
+
+class Gem::Specification
+  # has_rdoc should not be ignored!
+  overwrite_accessor(:has_rdoc) { @has_rdoc }
+  overwrite_accessor(:has_rdoc=) {|v| @has_rdoc = v }
+  
+  def self.has_yardoc=(value)
+    @has_rdoc = 'yard'
+  end
+  
+  def has_yardoc
+    @has_rdoc == 'yard'
+  end
+  
+  def has_rdoc?
+    @has_rdoc && @has_rdoc != 'yard'
+  end
+  
+  alias has_yardoc? has_yardoc
+end
+
+class Gem::DocManager
+  def self.load_yardoc
+    require File.dirname(__FILE__) + '/yard'
+  end
+  
+  def run_yardoc(*args)
+    args << @spec.rdoc_options
+    args << '--quiet'
+    if @spec.extra_rdoc_files.size > 0
+      args << '--files'
+      args << @spec.extra_rdoc_files.join(",")
+    end
+    args << @spec.require_paths.map {|p| p + "/**/*.rb" }
+    args = args.flatten.map do |arg| arg.to_s end
+
+    old_pwd = Dir.pwd
+    Dir.chdir(@spec.full_gem_path)
+    YARD::CLI::Yardoc.run(*args)
+  rescue Errno::EACCES => e
+    dirname = File.dirname e.message.split("-")[1].strip
+    raise Gem::FilePermissionError.new(dirname)
+  rescue RuntimeError => ex
+    alert_error "While generating documentation for #{@spec.full_name}"
+    ui.errs.puts "... MESSAGE:   #{ex}"
+    ui.errs.puts "... YARDDOC args: #{args.join(' ')}"
+    ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if
+    Gem.configuration.backtrace
+    ui.errs.puts "(continuing with the rest of the installation)"
+  ensure
+    Dir.chdir(old_pwd)
+  end
+
+  def setup_rdoc
+    if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then
+      raise Gem::FilePermissionError.new(@doc_dir)
+    end
+
+    FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
+
+    self.class.load_rdoc if @spec.has_rdoc?
+    self.class.load_yardoc if @spec.has_yardoc?
+  end
+
+  def install_yardoc
+    rdoc_dir = File.join(@doc_dir, 'rdoc')
+
+    FileUtils.rm_rf rdoc_dir
+
+    say "Installing YARD documentation for #{@spec.full_name}..."
+    run_yardoc '-o', rdoc_dir
+  end
+
+  def install_ri_yard
+    install_ri_yard_orig if @spec.has_rdoc?
+  end
+  alias install_ri_yard_orig install_ri
+  alias install_ri install_ri_yard
+  
+  def install_rdoc_yard
+    if @spec.has_rdoc?
+      install_rdoc_yard_orig
+    elsif @spec.has_yardoc?
+      install_yardoc
+    end
+  end
+  alias install_rdoc_yard_orig install_rdoc
+  alias install_rdoc install_rdoc_yard
+end

data/lib/yard.rb

@@ -1,9 +1,10 @@
 module YARD
-  VERSION = "0.2.3"
+  VERSION = "0.2.3.2"
   ROOT = File.dirname(__FILE__)
   TEMPLATE_ROOT = File.join(File.dirname(__FILE__), '..', 'templates')
   
   def self.parse(*args) Parser::SourceParser.parse(*args) end
+  def self.parse_string(*args) Parser::SourceParser.parse_string(*args) end
 end
 
 # Keep track of Ruby version for compatibility code

data/lib/yard/cli/yardoc.rb

@@ -16,14 +16,15 @@ module YARD
           :format => :html, 
           :template => :default, 
           :serializer => YARD::Serializers::FileSystemSerializer.new, 
+          :files => [],
           :verifier => lambda do |gen, obj| 
             return false if gen.respond_to?(:visibility) && !visibilities.include?(gen.visibility) 
           end
         ]
+        @files = []
         @visibilities = [:public]
         @reload = true
         @generate = true
-        @files = ['lib/**/*.rb']
         @options_file = DEFAULT_YARDOPTS_FILE
       end
       
@@ -56,14 +57,45 @@ module YARD
         []
       end
       
+      def add_extra_files(*files)
+        files.map! {|f| f.include?("*") ? Dir.glob(f) : f }.flatten!
+        files.each do |file|
+          raise Errno::ENOENT, "Could not find extra file: #{file}" unless File.file?(file)
+          options[:files] << file
+        end
+      end
+      
+      def parse_files(*files)
+        self.files = []
+        seen_extra_files_marker = false
+        
+        files.each do |file|
+          if file == "-"
+            seen_extra_files_marker = true
+            next
+          end
+          
+          if seen_extra_files_marker
+            add_extra_files(file)
+          else
+            self.files << file
+          end
+        end
+      end
+      
       def optparse(*args)
         serialopts = SymbolHash.new
         
         opts = OptionParser.new
-        opts.banner = "Usage: yardoc [options] [source files]"
+        opts.banner = "Usage: yardoc [options] [source_files [- extra_files]]"
 
         opts.separator "(if a list of source files is omitted, lib/**/*.rb is used.)"
         opts.separator ""
+        opts.separator "Example: yardoc -o documentation/ - FAQ LICENSE"
+        opts.separator "  The above example outputs documentation for files in"
+        opts.separator "  lib/**/*.rb to documentation/ including the extra files"
+        opts.separator "  FAQ and LICENSE."
+        opts.separator ""
         opts.separator "A base set of options can be specified by adding a .yardopts"
         opts.separator "file to your base path containing all extra options separated"
         opts.separator "by whitespace."
@@ -113,6 +145,10 @@ module YARD
         opts.on('--no-highlight', "Don't highlight code in docs as Ruby.") do 
           options[:no_highlight] = true
         end
+        
+        opts.on('--title TITLE', 'Add a specific title to HTML documents') do |title|
+          options[:title] = title
+        end
 
         opts.on('-r', '--readme FILE', 'The readme file used as the title page of documentation.') do |readme|
           raise Errno::ENOENT, readme unless File.file?(readme)
@@ -120,11 +156,7 @@ module YARD
         end
         
         opts.on('--files FILE1,FILE2,...', 'Any extra comma separated static files to be included (eg. FAQ)') do |files|
-          options[:files] = []
-          files.split(",").each do |file|
-            raise Errno::ENOENT, file unless File.file?(file)
-            options[:files] << file
-          end
+          add_extra_files *files.split(",")
         end
 
         opts.on('-m', '--markup MARKUP', 
@@ -174,8 +206,8 @@ module YARD
         end
         
         # Last minute modifications
-        self.files = args unless args.empty?
-        self.reload = false if self.files.empty?
+        parse_files(*args) unless args.empty?
+        self.files = ['lib/**/*.rb'] if self.files.empty?
         self.visibilities.uniq!
         options[:serializer] ||= Serializers::FileSystemSerializer.new(serialopts)
       end

data/lib/yard/code_objects/base.rb

@@ -171,21 +171,11 @@ module YARD
       ##
       # Attaches source code to a code object with an optional file location
       #
-      # @param [Parser::Statement, String] statement 
+      # @param [#source, String] statement 
       #   the +Parser::Statement+ holding the source code or the raw source 
       #   as a +String+ for the definition of the code object only (not the block)
       def source=(statement)
-        if statement.is_a? Parser::Ruby::Legacy::Statement
-          src = statement.tokens.to_s
-          blk = statement.block ? statement.block.to_s : ""
-          if src =~ /^def\s.*[^\)]$/ && blk[0,1] !~ /\r|\n/
-            blk = ";" + blk
-          end
-          
-          @source = format_source(src + blk)
-          self.line = statement.tokens.first.line_no
-          self.signature = src
-        elsif statement.respond_to?(:source)
+        if statement.respond_to?(:source)
           self.line = statement.line
           self.signature = statement.first_line
           @source = format_source(statement.source.strip)

data/lib/yard/docstring.rb

@@ -1,14 +1,26 @@
 module YARD
   class Docstring < String
     attr_reader :ref_tags
-    attr_accessor :object
+    attr_accessor :object, :line_range, :all
+
+    META_MATCH = /^@([a-z_]+)(?:\s+(.*))?$/i
     
     def initialize(content = '', object = nil)
       @tag_factory = Tags::Library.new
-      @tags, @ref_tags = [], []
       @object = object
       
-      replace parse_comments(content)
+      self.all = content
+    end
+    
+    def replace(content)
+      @tags, @ref_tags = [], []
+      @all = content
+      super parse_comments(content)
+    end
+    alias all= replace
+    
+    def line
+      line_range.first
     end
     
     ##
@@ -126,9 +138,8 @@ module YARD
     # @return [String] the non-metadata portion of the comments to
     #   be used as a docstring
     def parse_comments(comments)
+      comments = comments.split(/\r?\n/) if comments.is_a?(String)
       return '' if !comments || comments.empty?
-      meta_match = /^@(\S+)\s*(.*)/
-      comments = comments.split(/\r?\n/) if comments.is_a? String
       docstring = ""
 
       indent, last_indent = comments.first[/^\s*/].length, 0
@@ -142,16 +153,16 @@ module YARD
         done = comments.size == index
 
         if tag_name && (((indent < orig_indent && !empty) || done) || 
-            (indent <= last_indent && line =~ meta_match))
+            (indent <= last_indent && line =~ META_MATCH))
           create_tag(tag_name, tag_buf, raw_buf)
           tag_name, tag_buf, raw_buf = nil, '', []
           orig_indent = 0
         end
 
         # Found a meta tag
-        if line =~ meta_match
+        if line =~ META_MATCH
           orig_indent = indent
-          tag_name, tag_buf = $1, $2 
+          tag_name, tag_buf = $1, ($2 || '')
           raw_buf = [tag_buf.dup]
         elsif tag_name && indent >= orig_indent && !empty
           # Extra data added to the tag on the next line

data/lib/yard/generators/full_doc_generator.rb

@@ -26,6 +26,7 @@ module YARD
       end
     
       def css_file;         'style.css'             end
+      def css_custom_file;  'custom.css'            end
       def css_syntax_file;  'syntax_highlight.css'  end
       def js_file;          'jquery.js'             end
       def js_app_file;      'app.js'                end
@@ -44,7 +45,7 @@ module YARD
       
       def generate_assets
         if format == :html && serializer
-          [css_file, css_syntax_file, js_file, js_app_file].each do |filename|
+          [css_file, css_custom_file, css_syntax_file, js_file, js_app_file].each do |filename|
             template_file = find_template template_path(filename)
             serializer.serialize(filename, File.read(template_file))
           end

data/lib/yard/generators/helpers/html_helper.rb

@@ -20,10 +20,14 @@ module YARD
         return text unless markup
         load_markup_provider(markup)
 
+        # TODO: other libraries might be more complex
         case markup
-        when :markdown, :textile
-          # TODO: other libraries might be more complex
+        when :markdown
           html = markup_class(markup).new(text).to_html
+        when :textile
+          doc = markup_class(markup).new(text)
+          doc.hard_breaks = false if doc.respond_to?(:hard_breaks=)
+          html = doc.to_html
         when :rdoc
           html = MarkupHelper::SimpleMarkup.convert(text, SimpleMarkupHtml)
           html = fix_dash_dash(html)

data/lib/yard/generators/tags_generator.rb

@@ -4,9 +4,24 @@ module YARD
       before_section :header,  :has_tags?
       before_section :option, :has_options?
       before_section :param, :has_params?
+      before_section :todo, :has_todo?
       
       def sections_for(object)
-        [:header, [:example, :param, :yield, :yieldparam, :yieldreturn, :return, :raise, :todo, :author, :version, :since, :see]]
+        sections = [
+          :header, [ :example, :param, :yield, :yieldparam, :yieldreturn, 
+            :return, :raise, :todo, :author, :version, :since, :see ]
+        ]
+        if object.tags(:overload).size == 1
+          size = sections.last.size
+          sections.last.reverse.each_with_index do |item, index|
+            sections.last[size - index - 1, 1] = [:with_overload, [item]]
+          end
+        end
+        sections
+      end
+      
+      def with_overload(object)
+        yield(object.tag(:overload)) + yield(object)
       end
       
       def yield(object)
@@ -44,13 +59,19 @@ module YARD
       protected
       
       def has_params?(object)
-        object.is_a?(CodeObjects::MethodObject) && tags_by_param(object).size > 0
+        (object.is_a?(Tags::OverloadTag) || 
+        object.is_a?(CodeObjects::MethodObject)) && 
+        tags_by_param(object).size > 0
       end
       
       def has_tags?(object)
         object.tags.size > 0
       end
       
+      def has_todo?(object)
+        object.has_tag?(:todo)
+      end
+      
       def has_options?(object)
         object.has_tag?(:option)
       end

data/lib/yard/handlers/base.rb

@@ -295,6 +295,7 @@ module YARD
 
           # Add docstring if there is one.
           object.docstring = statement.comments if statement.comments
+          object.docstring.line_range = statement.comments_range
           
           # Add source only to non-class non-module objects
           unless object.is_a?(NamespaceObject)
@@ -309,6 +310,7 @@ module YARD
       end
 
       def ensure_loaded!(object, max_retries = 1)
+        return if object == Registry.root
         unless parser.load_order_errors
           if object.is_a?(Proxy)
             raise NamespaceMissingError, object
@@ -322,20 +324,19 @@ module YARD
           raise NamespaceMissingError, object
         end
         
-        retries, context = 0, nil
-        callcc {|c| context = c }
-
+        retries = 0
+        context = callcc {|c| c }
         retries += 1 
         
         if object.is_a?(Proxy)
           if retries <= max_retries
-            log.debug "Missing object #{object.parent} in file `#{parser.file}', moving it to the back of the line."
+            log.debug "Missing object #{object} in file `#{parser.file}', moving it to the back of the line."
             raise Parser::LoadOrderError, context
           else
             raise NamespaceMissingError, object
           end
         else
-          log.debug "Object #{object} successfully resolved. Adding item to #{object.parent}'s children"
+          log.debug "Object #{object} successfully resolved. Adding children."
         end
         object
       end