yard 0.7.5 → 0.8.0

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

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

data/docs/templates/default/fulldoc/html/setup.rb

@@ -0,0 +1,6 @@
+def generate_tag_list
+  @list_title = "Tag List"
+  @list_type = "tag"
+  asset('tag_list.html', erb(:full_list))
+end
+

data/docs/templates/default/layout/html/setup.rb

@@ -0,0 +1,8 @@
+def init
+  super
+  sections.place(:tag_list).after_any(:files)
+end
+
+def menu_lists
+  super + [{:type => 'tag', :title => 'Tags', :search_title => 'Tag List'}]
+end

data/docs/templates/default/layout/html/tag_list.erb

@@ -0,0 +1,11 @@
+<h2>Tag Listing</h2>
+<p>The following are a brief list of tags that can be used in YARD formatted
+  documentation. See <%= link_file "docs/Tags.md" %> for information on using tags.</p>
+<ul id="tags" class="index_inline_list">
+<% n = 1 %>
+<% collect_tags.each do |tag| %>
+  <li class="r<%= n %>"><%= tag_link(tag) %></li>
+  <% n = n == 2 ? 1 : 2 %>
+<% end %>
+</ul>
+<div class="clear"></div>

data/docs/templates/default/yard_tags/html/list.erb

@@ -0,0 +1,18 @@
+<% [["Tag", all_tags], ["Directive", all_directives]].each do |(name, list)| %>
+<h2><%= name %> List</h2>
+
+<% list.each_with_index do |tag, i| %>
+<div class="method_details <%= i == 0 ? 'first' : '' %>">
+  <h3 class="signature"
+      id="<%= tag.name %>" toc-title="<%= tag_link_name(tag) %>">
+    <%= tag_signature tag %>
+  </h3>
+  <% if name == "Directive" %>
+    <%= yieldall :object => P("YARD::Tags::#{tag.text}") %>
+  <% else %>
+    <%= yieldall :object => tag.object %>
+  <% end %>
+</div>
+<% end %>
+
+<% end%>

data/docs/templates/default/yard_tags/html/setup.rb

@@ -0,0 +1,27 @@
+def init
+  sections :list, [T('docstring')]
+end
+
+def tag_signature(tag)
+  types = tag.types || []
+  signature = "<strong>#{tag_link_name(tag)}</strong> "
+  extra = nil
+  if sig_tag = tag.object.tag('yard.signature')
+    extra = sig_tag.text
+  end
+  extra = case types.first
+  when 'with_name'
+    "name description"
+  when 'with_types'
+    "[Types] description"
+  when 'with_types_and_name'
+    "name [Types] description"
+  when 'with_title_and_text'
+    "title\ndescription"
+  when 'with_types_and_title'
+    "[Types] title\ndescription"
+  else
+    "description"
+  end if extra.nil?
+  signature + h(extra).gsub(/\n/, "<br/>&nbsp;&nbsp;&nbsp;")
+end

data/docs/templates/plugin.rb

@@ -0,0 +1,65 @@
+include YARD
+include Templates
+
+module TagTemplateHelper
+  def all_tags
+    Registry.all(:method).map {|m| m.tag('yard.tag') }.compact
+  end
+
+  def all_directives
+    Registry.all(:method).map {|m| m.tag('yard.directive') }.compact
+  end
+
+  def collect_tags
+    (all_tags + all_directives).sort_by {|t| t.name }
+  end
+
+  def tag_link(tag)
+    link_file("docs/Tags.md", tag_link_name(tag), tag.name)
+  end
+
+  def tag_link_name(tag)
+    prefix = tag.tag_name == 'yard.directive' ? '@!' : '@'
+    h(prefix + tag.name)
+  end
+
+  # Wrap url_for and url_for_file to rewrite object when generating docs for
+  # yard.tag/directive objects.
+  %w(url_for, url_for_file).each do |meth|
+    self.class.send(:define_method, meth) do
+      if object.is_a?(CodeObjects::Base) &&
+            (object.tag('yard.tag') || object.tag('yard.directive') ||
+            (object.type == :class && object.superclass.name == :Directive))
+          obj, self.object = object, Registry.root
+          url = super
+          self.object = obj
+          url
+      else
+        super
+      end
+    end
+  end
+
+  def linkify(*args)
+    if args.first.is_a?(String)
+      case args.first
+      when "yard:include_tags"
+        return T('yard_tags').run(options)
+      when /^tag:(\S+)/
+        tag_name, suffix = $1, "tag"
+        if tag_name =~ /^!/
+          tag_name, suffix = tag_name[1..-1], "directive"
+        end
+        if obj = Registry.at("YARD::Tags::Library##{tag_name}_#{suffix}")
+          return tag_link(obj.tag("yard.#{suffix}"))
+        end
+        log.warn "Cannot find tag: #{args.first}"
+        return args.first
+      end
+    end
+    super
+  end
+end
+
+Template.extra_includes << TagTemplateHelper
+Engine.register_template_path(File.dirname(__FILE__))

data/lib/yard.rb

@@ -1,5 +1,5 @@
 module YARD
-  VERSION = "0.7.5"
+  VERSION = "0.8.0"
 
   # The root path for YARD source libraries
   ROOT = File.expand_path(File.dirname(__FILE__))
@@ -32,15 +32,6 @@ end
 # Keep track of Ruby version for compatibility code
 RUBY19, RUBY18 = *(RUBY_VERSION >= "1.9.1" ? [true, false] : [false, true])
 
-# Whether or not continuations are (properly) supported
-begin
-  begin; require 'continuation'; rescue LoadError; end
-  cc = callcc {|cc| cc }; cc.call if cc
-  CONTINUATIONS_SUPPORTED = true
-rescue Exception
-  CONTINUATIONS_SUPPORTED = false
-end
-
 # Load Ruby core extension classes
 Dir.glob(File.join(YARD::ROOT, 'yard', 'core_ext', '*.rb')).each do |file|
   require file

data/lib/yard/autoload.rb

@@ -15,6 +15,7 @@ module YARD
     autoload :Stats,          __p('cli/stats')
     autoload :Yardoc,         __p('cli/yardoc')
     autoload :YRI,            __p('cli/yri')
+    autoload :I18n,           __p('cli/i18n')
   end
 
   # A "code object" is defined as any entity in the Ruby language.
@@ -57,6 +58,26 @@ module YARD
   # parsing phase. This allows YARD as well as any custom extension to
   # analyze source and generate {CodeObjects} to be stored for later use.
   module Handlers
+    # CRuby Handlers
+    # @since 0.8.0
+    module C
+      autoload :Base,                     __p('handlers/c/base')
+
+      autoload :AliasHandler,             __p('handlers/c/alias_handler')
+      autoload :AttributeHandler,         __p('handlers/c/attribute_handler')
+      autoload :ClassHandler,             __p('handlers/c/class_handler')
+      autoload :ConstantHandler,          __p('handlers/c/constant_handler')
+      autoload :HandlerMethods,           __p('handlers/c/handler_methods')
+      autoload :InitHandler,              __p('handlers/c/init_handler')
+      autoload :MethodHandler,            __p('handlers/c/method_handler')
+      autoload :MixinHandler,             __p('handlers/c/mixin_handler')
+      autoload :ModuleHandler,            __p('handlers/c/module_handler')
+      autoload :OverrideCommentHandler,   __p('handlers/c/override_comment_handler')
+      autoload :PathHandler,              __p('handlers/c/path_handler')
+      autoload :StructHandler,            __p('handlers/c/struct_handler')
+      autoload :SymbolHandler,            __p('handlers/c/symbol_handler')
+    end
+
     module Ruby # All Ruby handlers
       module Legacy # Handlers for old Ruby 1.8 parser
         autoload :Base,                   __p('handlers/ruby/legacy/base')
@@ -66,13 +87,15 @@ module YARD
         autoload :ClassHandler,           __p('handlers/ruby/legacy/class_handler')
         autoload :ClassConditionHandler,  __p('handlers/ruby/legacy/class_condition_handler')
         autoload :ClassVariableHandler,   __p('handlers/ruby/legacy/class_variable_handler')
+        autoload :CommentHandler,         __p('handlers/ruby/legacy/comment_handler')
         autoload :ConstantHandler,        __p('handlers/ruby/legacy/constant_handler')
+        autoload :DSLHandler,             __p('handlers/ruby/legacy/dsl_handler')
         autoload :ExceptionHandler,       __p('handlers/ruby/legacy/exception_handler')
         autoload :ExtendHandler,          __p('handlers/ruby/legacy/extend_handler')
-        autoload :MacroHandler,           __p('handlers/ruby/legacy/macro_handler')
         autoload :MethodHandler,          __p('handlers/ruby/legacy/method_handler')
         autoload :MixinHandler,           __p('handlers/ruby/legacy/mixin_handler')
         autoload :ModuleHandler,          __p('handlers/ruby/legacy/module_handler')
+        autoload :ModuleFunctionHandler,  __p('handlers/ruby/legacy/module_function_handler')
         autoload :PrivateConstantHandler, __p('handlers/ruby/legacy/private_constant_handler')
         autoload :VisibilityHandler,      __p('handlers/ruby/legacy/visibility_handler')
         autoload :YieldHandler,           __p('handlers/ruby/legacy/yield_handler')
@@ -85,15 +108,17 @@ module YARD
       autoload :ClassHandler,             __p('handlers/ruby/class_handler')
       autoload :ClassConditionHandler,    __p('handlers/ruby/class_condition_handler')
       autoload :ClassVariableHandler,     __p('handlers/ruby/class_variable_handler')
+      autoload :CommentHandler,           __p('handlers/ruby/comment_handler')
       autoload :ConstantHandler,          __p('handlers/ruby/constant_handler')
+      autoload :DSLHandler,               __p('handlers/ruby/dsl_handler')
+      autoload :DSLHandlerMethods,        __p('handlers/ruby/dsl_handler_methods')
       autoload :ExceptionHandler,         __p('handlers/ruby/exception_handler')
       autoload :ExtendHandler,            __p('handlers/ruby/extend_handler')
-      autoload :MacroHandler,             __p('handlers/ruby/macro_handler')
-      autoload :MacroHandlerMethods,      __p('handlers/ruby/macro_handler_methods')
       autoload :MethodHandler,            __p('handlers/ruby/method_handler')
       autoload :MethodConditionHandler,   __p('handlers/ruby/method_condition_handler')
       autoload :MixinHandler,             __p('handlers/ruby/mixin_handler')
       autoload :ModuleHandler,            __p('handlers/ruby/module_handler')
+      autoload :ModuleFunctionHandler,    __p('handlers/ruby/module_function_handler')
       autoload :PrivateConstantHandler,   __p('handlers/ruby/private_constant_handler')
       autoload :StructHandlerMethods,     __p('handlers/ruby/struct_handler_methods')
       autoload :VisibilityHandler,        __p('handlers/ruby/visibility_handler')
@@ -105,9 +130,25 @@ module YARD
     autoload :Processor,                  __p('handlers/processor')
   end
 
+  # Namespace for internationalization (i18n)
+  # @since 0.8.0
+  module I18n
+    autoload :PotGenerator,    __p('i18n/pot_generator')
+    autoload :Text,            __p('i18n/text')
+  end
+
   # The parser namespace holds all parsing engines used by YARD.
   # Currently only Ruby and C (Ruby) parsers are implemented.
   module Parser
+    module C # CRuby Parsing components
+      autoload :BodyStatement,     __p('parser/c/statement')
+      autoload :Comment,           __p('parser/c/statement')
+      autoload :CommentParser,     __p('parser/c/comment_parser')
+      autoload :CParser,           __p('parser/c/c_parser')
+      autoload :Statement,         __p('parser/c/statement')
+      autoload :ToplevelStatement, __p('parser/c/statement')
+    end
+
     module Ruby # Ruby parsing components.
       module Legacy # Handles Ruby parsing in Ruby 1.8.
         autoload :RipperParser,   __p('parser/ruby/legacy/ruby_parser')
@@ -123,7 +164,6 @@ module YARD
     end
 
     autoload :Base,                __p('parser/base')
-    autoload :CParser,             __p('parser/c_parser')
     autoload :ParserSyntaxError,   __p('parser/source_parser')
     autoload :SourceParser,        __p('parser/source_parser')
     autoload :UndocumentableError, __p('parser/source_parser')
@@ -162,9 +202,6 @@ module YARD
       autoload :DisplayObjectCommand, __p('server/commands/display_object_command')
       autoload :FramesCommand,        __p('server/commands/frames_command')
       autoload :ListCommand,          __p('server/commands/list_command')
-      autoload :ListClassesCommand,   __p('server/commands/list_command')
-      autoload :ListFilesCommand,     __p('server/commands/list_command')
-      autoload :ListMethodsCommand,   __p('server/commands/list_command')
       autoload :LibraryCommand,       __p('server/commands/library_command')
       autoload :LibraryIndexCommand,  __p('server/commands/library_index_command')
       autoload :SearchCommand,        __p('server/commands/search_command')
@@ -186,15 +223,23 @@ module YARD
   end
 
   module Tags # Namespace for Tag components
-    autoload :DefaultFactory, __p('tags/default_factory')
-    autoload :DefaultTag,     __p('tags/default_tag')
-    autoload :Library,        __p('tags/library')
-    autoload :OptionTag,      __p('tags/option_tag')
-    autoload :OverloadTag,    __p('tags/overload_tag')
-    autoload :RefTag,         __p('tags/ref_tag')
-    autoload :RefTagList,     __p('tags/ref_tag_list')
-    autoload :Tag,            __p('tags/tag')
-    autoload :TagFormatError, __p('tags/tag_format_error')
+    autoload :AttributeDirective,  __p('tags/directives')
+    autoload :DefaultFactory,      __p('tags/default_factory')
+    autoload :DefaultTag,          __p('tags/default_tag')
+    autoload :EndGroupDirective,   __p('tags/directives')
+    autoload :GroupDirective,      __p('tags/directives')
+    autoload :Library,             __p('tags/library')
+    autoload :MacroDirective,      __p('tags/directives')
+    autoload :MethodDirective,     __p('tags/directives')
+    autoload :OptionTag,           __p('tags/option_tag')
+    autoload :OverloadTag,         __p('tags/overload_tag')
+    autoload :ParseDirective,      __p('tags/directives')
+    autoload :RefTag,              __p('tags/ref_tag')
+    autoload :RefTagList,          __p('tags/ref_tag_list')
+    autoload :ScopeDirective,      __p('tags/directives')
+    autoload :Tag,                 __p('tags/tag')
+    autoload :TagFormatError,      __p('tags/tag_format_error')
+    autoload :VisibilityDirective, __p('tags/directives')
   end
 
   # Namespace for templating system
@@ -215,19 +260,22 @@ module YARD
       autoload :UMLHelper,                  __p('templates/helpers/uml_helper')
     end
 
-    autoload :Engine,   __p('templates/engine')
-    autoload :ErbCache, __p('templates/erb_cache')
-    autoload :Section,  __p('templates/section')
-    autoload :Template, __p('templates/template')
+    autoload :Engine,          __p('templates/engine')
+    autoload :ErbCache,        __p('templates/erb_cache')
+    autoload :Section,         __p('templates/section')
+    autoload :Template,        __p('templates/template')
+    autoload :TemplateOptions, __p('templates/template_options')
   end
 
-  autoload :Config,         __p('config')
-  autoload :Docstring,      __p('docstring')
-  autoload :Logger,         __p('logging')
-  autoload :Registry,       __p('registry')
-  autoload :RegistryStore,  __p('registry_store')
-  autoload :StubProxy,      __p('serializers/yardoc_serializer')
-  autoload :Verifier,       __p('verifier')
+  autoload :Config,          __p('config')
+  autoload :Docstring,       __p('docstring')
+  autoload :DocstringParser, __p('docstring_parser')
+  autoload :Logger,          __p('logging')
+  autoload :Options,         __p('options')
+  autoload :Registry,        __p('registry')
+  autoload :RegistryStore,   __p('registry_store')
+  autoload :StubProxy,       __p('serializers/yardoc_serializer')
+  autoload :Verifier,        __p('verifier')
 end
 
 undef __p

data/lib/yard/cli/command.rb

@@ -34,6 +34,9 @@ module YARD
                             '  Always on in 1.8.x.') do
           YARD::Parser::SourceParser.parser_type = :ruby18
         end
+        opts.on('--safe', 'Enable safe mode for this instance') do
+          # Parsed in YARD::Config.load
+        end
         opts.on_tail('-q', '--quiet', 'Show no warnings.') { log.level = Logger::ERROR }
         opts.on_tail('--verbose', 'Show more information.') { log.level = Logger::INFO }
         opts.on_tail('--debug', 'Show debugging information.') { log.level = Logger::DEBUG }
@@ -56,14 +59,14 @@ module YARD
         retry
       end
 
-      # Loads a Ruby script. If +Config.options[:safe_mode]+ is enabled,
+      # Loads a Ruby script. If <tt>Config.options[:safe_mode]</tt> is enabled,
       # this method will do nothing.
       #
       # @param [String] file the path to the script to load
       # @since 0.6.2
       def load_script(file)
         return if YARD::Config.options[:safe_mode]
-        require(file.gsub(/\.rb$/, ''))
+        load(file)
       rescue LoadError => load_exception
         log.error "The file `#{file}' could not be loaded:\n#{load_exception}"
         exit

data/lib/yard/cli/command_parser.rb

@@ -40,7 +40,8 @@ module YARD
         :list   => List,
         :ri     => YRI,
         :server => Server,
-        :stats  => Stats
+        :stats  => Stats,
+        :i18n   => I18n
       ]
 
       self.default_command = :doc
@@ -86,4 +87,4 @@ module YARD
       end
     end
   end
-end
+end

data/lib/yard/cli/diff.rb

@@ -63,7 +63,7 @@ module YARD
       end
 
       private
-      
+
       def load_git_commit(commit)
         commit_path = 'git_commit' + commit.gsub(/\W/, '_')
         tmpdir = File.join(Dir.tmpdir, commit_path)

data/lib/yard/cli/i18n.rb

@@ -0,0 +1,69 @@
+require "pathname"
+
+module YARD
+  module CLI
+    # CLI command to support internationalization (a.k.a. i18n).
+    # I18n feature is based on gettext technology.
+    # This command generates .pot file from docstring and extra
+    # documentation.
+    #
+    # @since 0.8.0
+    # @todo Support msgminit and msgmerge features?
+    class I18n < Yardoc
+      def initialize
+        super
+        @options.serializer.basepath = "po/yard.pot"
+      end
+
+      def description
+        'Generates .pot file from source code and extra documentation'
+      end
+
+      def run(*args)
+        if args.size == 0 || !args.first.nil?
+          # fail early if arguments are not valid
+          return unless parse_arguments(*args)
+        end
+
+        YARD.parse(files, excluded)
+
+        serializer = options.serializer
+        pot_file_path = Pathname.new(serializer.basepath).expand_path
+        pot_file_dir_path, pot_file_basename = pot_file_path.split
+        relative_base_path = Pathname.pwd.relative_path_from(pot_file_dir_path)
+        serializer.basepath = pot_file_dir_path.to_s
+        serializer.serialize(pot_file_basename.to_s,
+                             generate_pot(relative_base_path.to_s))
+
+        true
+      end
+
+      private
+
+      def general_options(opts)
+        opts.banner = "Usage: yard i18n [options] [source_files [- extra_files]]"
+        opts.top.list.clear
+        opts.separator "(if a list of source files is omitted, "
+        opts.separator "  {lib,app}/**/*.rb ext/**/*.c is used.)"
+        opts.separator ""
+        opts.separator "Example: yard i18n -o yard.pot - FAQ LICENSE"
+        opts.separator "  The above example outputs .pot file for files in"
+        opts.separator "  lib/**/*.rb to yard.pot 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."
+        super(opts)
+      end
+
+      def generate_pot(relative_base_path)
+        generator = YARD::I18n::PotGenerator.new(relative_base_path)
+        objects = run_verifier(all_objects)
+        generator.parse_objects(objects)
+        generator.parse_files(options.files || [])
+        generator.generate
+      end
+    end
+  end
+end