yard 0.2.3.5 → 0.4.0

data/bin/view_generator

@@ -1,17 +0,0 @@
-#!/usr/bin/env ruby
-require File.dirname(__FILE__) + '/../lib/yard'
-
-log.level = Logger::DEBUG
-YARD::Registry.load
-gclass = eval("YARD::Generators::#{ARGV[0]}")
-sclass = ARGV[1] == "nil" ? nil : eval("YARD::Serializers::#{ARGV[1]}") 
-obj = ARGV[2] == "all" ? YARD::Registry.all(:module, :class) : P(ARGV[2])
-format = ARGV[3].to_sym
-
-if sclass
-  sclass = sclass.new 
-else
-  sclass = YARD::Serializers::StdoutSerializer.new(80)
-end
-verifier = lambda {|gen, obj| return false if gen.respond_to?(:visibility) && [:protected, :private].include?(gen.visibility) }
-gclass.new(:format => format, :template => :default, :serializer => sclass, :verifier => verifier).generate(obj)

data/docs/FAQ.markdown

@@ -1,34 +0,0 @@
-FAQ
-===
-
-(1) So, show me some cool stuff. What can YARD do?
---------------------------------------------------
-
-- [Visualize with GraphViz][graphviz] Visualize your classes and methods with GraphViz
-- [Inline RSpecs][inline-rspecs] In your rspec files, call the following to refer 
-  back to and call the inline rspecs: `described_in_docs "String", "camelcase"`
-- [Inline doc testing][inline-doctest] Use the 'docspec' command line tool to 
-  run the above tests.  This is similar to [Ruby DocTest][rubydoctest]'s inline 
-  irb testing.
-  
-(2) Why did you pick the @-symbol tags for documentation?
----------------------------------------------------------
-Java, C++, Python and many other languages have standard documentation tools 
-that use the @tag "standard".  This has been extended to the Ruby language, 
-and YARD takes advantage of this common style.
-
-(3) Can I tweak it to use some other documentation standard?
-------------------------------------------------------------
-  Yes. YARD is flexible enough to have other documentation syntaxes put into use. [TODO: Add information about customization here.]
-
-(4) Why don't you use ParseTree, or sydparse?  Why did you write your own parser?
----------------------------------------------------------------------------------
-As of Ruby 1.9, YARD uses Ripper parser which is packaged with the standard library
-and maintained as such. The legacy parser is only being maintained for bug fixes, 
-but was written because no existing parser properly supported putting comments 
-into the parse tree and did not robustly support edge case scenarios.
-
-[graphviz]:http://gnuu.org/2008/02/29/generating-class-diagrams-with-yard-and-graphviz/
-[inline-rspecs]:http://github.com/lsegal/yard/tree/5b07d706eee6bc0d7f13d9ec1e6e0ab914d3679c/lib/yard/core_ext/string.rb
-[inline-doctest]:http://github.com/lsegal/yard/tree/master/lib/yard/handlers/base.rb#L350
-[rubydoctest]:http://github.com/tablatom/rubydoctest

data/docs/GENERATORS.markdown

@@ -1,211 +0,0 @@
-Generators Architecture
-=======================
-
-Note: This document describes the architecture of the current generators 
-implementation which is likely to undergo large changes in the 0.2.4
-release. Keep this in mind if you plan on extending or implementing
-custom generators.
-      
-Generators are the main component in the output generation process of YARD,
-which is invoked when conventional HTML/text output needs to be generated
-for a set of code objects.
-
-Design Goals
-------------
-
-The general design attempts to be as abstracted from actual content and templates
-as possible. Unlike RDoc which uses one file to describe the entire template,
-YARD splits up the generation of code objects into small components, allowing
-template modification for smaller subsets of a full template without having to
-duplicate the entire template itself. This is necessary because of YARD's support
-for plugins. YARD is designed for extensibility by external plugins, and because
-of this, no one plugin can be responsible for the entire template because no
-one plugin knows about the other plugins being used. For instance, if an RSpec
-plugin was added to support and document specifications in class templates,
-this information would need to be transparently added to the template to work
-in conjunction with any other plugin that performed similar template modifications.
-The design goals can be summarized as follows:
-
-  1. Output should be able to be generated for any arbitrary format with little
-     modification to YARD's source code. The addition of extra templates should
-     be sufficient.
-  2. The output generated for an object should independently generated data
-     from arbitrary sources. These independent components are called "sections".
-  3. Sections should be able to be inserted into any object without affecting
-     any existing sections in the document. This allows for easy modification
-     of templates by plugins.
-     
-Generators
-----------
-
-Generator classes are the objects used to orchestrate the design goals listed 
-above. Specifically, they organize the sections and render the template contents
-depending on the format. The main method used to initiate output is the 
-{YARD::Generators::Base#generate #generate} method which takes a list of
-objects to generate output for. A good example of this is the FullDocGenerator,
-which generates conventional HTML documentation:
-
-    # all_objects is an array of module and class objects
-    Generators::FullDocGenerator.new(options).generate(all_objects)
-
-Generator Options
------------------
-
-A generator keeps state when it is generating output. This state is kept in
-an options hash which is initially passed to it during instantiation. Some
-default options set the template style (`:template`), the output format (`:format`),
-and the serializer to use (`:serializer`). For example, initializing the 
-{YARD::Generators::QuickDocGenerator} to output as text instead of HTML can be
-done as follows:
-
-    YARD::Generators::QuickDocGenerator.new(:format => :text).generate(objects)
-    
-Serializer
-----------
-
-This class abstracts the logic involved in deciding how to serialize data to
-the expected endpoint. For instance, there is both a {YARD::Serializers::StdoutSerializer StdoutSerializer}
-and {YARD::Serializers::FileSystemSerializer FileSystemSerializer} class for
-outputting to console or to a file respectively. When endpoints with locations
-are used (like files or URLs), the serializer implements the {YARD::Serializers::Base#serialized_path #serialized_path}
-method. This allows the translation from a code object to its path at the endpoint,
-which enables inter-document linking.
-
-Generated objects are automatically serialized using the object if present, 
-otherwise the generated object is returned as a string to its parent. Nested
-generator objects automatically set the serializer to nil so that they return
-as a String to their parent.
-
-Templates
----------
-
-Templates for a generator are by default found inside the one of the template 
-root paths (there can be multiple template paths). A standard template 
-directory looks like the following tree:
-
-    (Assuming templates/ is a template root path)
-    templates/
-    |-- default
-    |   |-- attributes
-    |   |   |-- html
-    |   |   |   `-- header.erb
-    |   |   `-- text
-    |   |       `-- header.erb
-    |   |-- class
-    |   |   `-- html
-    |   |       `-- header.erb
-    |   |-- constants
-    |   |   `-- html
-    |   |       |-- constants.erb
-    |   |       |-- header.erb
-    |   |       |-- included.erb
-    |   |       `-- inherited.erb
-    ...
-
-The path `default` refers to the template style and the directories at the next
-level (such as `attributes`) refer to templates for a generator. The next directory
-refers to the output format being used defined by the `:format` generator option. 
-As we saw in the above example, the format option can be set to `:text`, which
-would use the `text/` directory instead of `html/`. Finally, the individual .erb 
-files are the sections that make up the generator. 
-
-Sections
---------
-
-As mentioned above, sections are smaller components that correlate to template
-fragments. Practically speaking, a section can either be a template fragment 
-(a conventional .erb file or other supported templating language), a method 
-(which returns a String) or another Generator object (which in turn has its own 
-list of sections).
-
-Creating a Generator
---------------------
-
-To create a generator, subclass {YARD::Generators::Base} and implement the
-`#sections_for(object)` method. This method should return a list of sections where
-a Symbol refers to a method or template name and a class refers to a generator.
-
-    def sections_for(object)
-      case object
-      when MethodObject
-        [:main, [G(AnotherGenerator)], :footer]
-      else
-        []
-      end
-    end
-    
-A few points about the above example:
-
-  * The method can return different lists depending on the object.
-  * The list of objects is not flat, we will see how nested lists can be used
-    in a future example.
-  * The convenience method `G()` instantiates a generator out of the class using
-    the existing options.
-
-If a section is a Symbol, the generator first checks if a method is defined
-with that name, otherwise it checks in the template directories. If a method
-by the symbol name is defined, you need to manually call {YARD::Generators::Base#render #render}
-to return the contents of the template.
-
-Nested Sections
----------------
-
-Sections often require the ability to encapsulate a set of sub-sections in markup
-(HTML, for instance). Rather than use heavier Generator subclass objects, a more
-lightweight solution is to nest a set of sub-sections as a list that follows
-a section, for example:
-
-    def sections_for(object) 
-      [:header, [:section_a, :section_b]]
-    end
-    
-The above example nests `section_a` and `section_b` within the `header` section.
-Practically speaking, these sections can be placed in the result by `yield`ing
-to them. A sample header.erb template might contain:
-
-    <h2>Header</h2>
-    <div id="contents">
-      <%= yield %>
-    </div>
-    
-This template code would place the output of `section_a` and `section_b` within
-the above div element. Using yield, we can also change the object that is being
-generated. For example, we may want to yield the first method of the class.
-We can do this like so:
-
-    <h2>First method</h2>
-    <%= yield(current_object.meths.first) %>
-
-This would run the nested sections for the method object instead of the class.
-
-Before Filters
---------------
-
-Generators can run before filters using the {YARD::Generators::Base.before_section before_section} method
-for all or a specific section to test if the section should be generated or 
-skipped. For instance, we can do the following to generate the section :foo only 
-for MethodObjects:
-
-    class MyGenerator < YARD::Generators::Base
-      before_section :foo, :is_method?
-      
-      def sections_for(object)
-        [:foo, :bar, :baz]
-      end
-      
-      private
-      
-      def is_method?(object)
-        object.is_a?(MethodObject)
-      end
-    end
-
-Without the argument `:foo`, the before filter would be applied to all sections.
-Note that we must return `false` to skip a section. A return type of nil is not
-enough to skip the section.
-
-There is also a {YARD::Generators::Base.before_list before_list} method to run
-a filter before the entire generator is run. This is useful for doing necessary
-filesystem setup or for generating assets (stylesheets) before generating output 
-for the objects. Note that in this case you will need to serialize your data directly
-using the serializer object (described above).

data/lib/yard/generators/attributes_generator.rb

@@ -1,22 +0,0 @@
-module YARD
-  module Generators
-    class AttributesGenerator < Base
-      include Helpers::MethodHelper
-      
-      before_generate :has_attributes?
-      before_list :includes
-      
-      def sections_for(object) [:header] end
-        
-      protected
-      
-      def includes
-        extend Helpers::UMLHelper if format == :text
-      end
-      
-      def has_attributes?
-        current_object.class_attributes.size + current_object.instance_attributes.size > 0
-      end
-    end
-  end
-end

data/lib/yard/generators/base.rb

@@ -1,305 +0,0 @@
-require 'erb'
-
-module YARD
-  module Generators
-    class Base
-      include Helpers::BaseHelper
-      include Helpers::FilterHelper
-
-      class << self
-        def template_paths
-          @@template_paths ||= [TEMPLATE_ROOT]
-        end
-
-        ##
-        # Convenience method to registering a template path.
-        # Equivalent to calling:
-        #   GeneratorName.template_paths.unshift(path)
-        # 
-        # @param [String] path 
-        #   the pathname to look for the template
-        # 
-        # @see template_paths
-        def register_template_path(path)
-          template_paths.unshift(path)
-        end
-
-        # Calls the +Proc+ object or method name before generating all or a specific
-        # section. The callback should return +false+ if the section is to be
-        # skipped.
-        # 
-        # @overload before_section(method_name)
-        #   @param [Symbol] method_name the name of the method to call before
-        #     running the generator.
-        # 
-        # @overload before_section(proc)
-        #   @param [Proc] proc should return +false+ if section should be skipped.
-        # 
-        # @overload before_section(section, condition)
-        #   Only calls the +Proc+ or method if it matches the passed +section+
-        #   
-        #   @param [Object] section one of the section items in {#sections_for}
-        #   @param [Symbol, Proc] condition see the first two overloads
-        def before_section(*args)
-          if args.size == 1
-            before_section_filters.push [nil, args.first]
-          elsif args.size == 2
-            before_section_filters.push(args)
-          else
-            raise ArgumentError, "before_section takes a generator followed by a Proc/lambda or Symbol referencing the method name"
-          end
-        end
-        
-        def before_section_filters
-          @before_section_filters ||= []
-        end
-        
-        def before_generate(meth)
-          before_generate_filters.push(meth)
-        end
-        
-        def before_generate_filters
-          @before_generate_filters ||= []
-        end
-        
-        def before_list(meth)
-          before_list_filters.push(meth)
-        end
-        
-        def before_list_filters
-          @before_list_filters ||= []
-        end
-      end
-      
-      # Creates a generator by adding extra options
-      # to the options hash. 
-      # 
-      # @example [Creates a new MethodSummaryGenerator for public class methods]
-      #   G(MethodSummaryGenerator, :scope => :class, :visibility => :public)
-      # 
-      # @param [Class] generator 
-      #   the generator class to use.
-      # 
-      # @option opts :ignore_serializer [Boolean] (true) whether or not the serializer is ignored.
-      # 
-      def G(generator, opts = {})
-        opts = SymbolHash[:ignore_serializer => true].update(opts)
-        generator.new(options, opts)
-      end
-
-      attr_reader :format, :template, :verifier
-      attr_reader :serializer, :ignore_serializer
-      attr_reader :options
-      attr_reader :current_object
-      
-      def initialize(opts = {}, extra_opts = {})
-        opts = SymbolHash[
-          :format => :html,
-          :template => :default,
-          :markup => :rdoc,
-          :serializer => nil,
-          :verifier => nil
-        ].update(opts).update(extra_opts)
-        
-        @options = opts
-        @format = options[:format]
-        @template = options[:template] 
-        @serializer = options[:serializer] 
-        @ignore_serializer = options[:ignore_serializer]
-        @verifier = options[:verifier]
-        
-        extend Helpers::HtmlHelper if format == :html
-      end
-      
-      def generator_name
-        self.class.to_s.split("::").last.gsub(/Generator$/, '').downcase
-      end
-      
-      def generate(*list, &block)
-        output = ""
-
-        list = list.flatten
-        @current_object = Registry.root
-        return output if FalseClass === run_before_list(list)
-
-        serializer.before_serialize if serializer && !ignore_serializer
-        
-        list.each do |object|
-          next unless object && !object.is_a?(CodeObjects::Proxy)
-          
-          objout = ""
-          @current_object = object
-
-          next if call_verifier(object).is_a?(FalseClass)
-          next if run_before_generate(object).is_a?(FalseClass)
-          
-          objout << render_sections(object, &block) 
-
-          if serializer && !ignore_serializer && !objout.empty?
-            serializer.serialize(object, objout) 
-          end
-          output << objout
-        end
-        
-        if serializer && !ignore_serializer
-          serializer.after_serialize(output) 
-        end
-        output
-      end
-      
-      protected
-      
-      def call_verifier(object)
-        if verifier.is_a?(Symbol)
-          send(verifier, object)
-        elsif verifier.respond_to?(:call)
-          verifier.call(self, object)
-        end
-      end
-      
-      def run_before_list(list)
-        self.class.before_list_filters.each do |meth|
-          meth = method(meth) if meth.is_a?(Symbol)
-          result = meth.call *(meth.arity == 0 ? [] : [list])
-          return result if result.is_a?(FalseClass)
-        end
-      end
-      
-      def run_before_generate(object)
-        self.class.before_generate_filters.each do |meth|
-          meth = method(meth) if meth.is_a?(Symbol)
-          result = meth.call *(meth.arity == 0 ? [] : [object])
-          return result if result.is_a?(FalseClass)
-        end
-      end
-
-      def run_before_sections(section, object)
-        result = before_section(section, object)
-        return result if result.is_a?(FalseClass)
-        
-        self.class.before_section_filters.each do |info|
-          result, sec, meth = nil, *info
-          if sec.nil? || sec == section
-            meth = method(meth) if meth.is_a?(Symbol)
-            args = [section, object]
-            if meth.arity == 1 
-              args = [object]
-            elsif meth.arity == 0
-              args = []
-            end
-
-            result = meth.call(*args)
-            log.debug("Calling before section filter for %s%s with `%s`, result = %s" % [
-              self.class.class_name, section.inspect, object, 
-              result.is_a?(FalseClass) ? 'fail' : 'pass'
-            ])
-          end
-
-          return result if result.is_a?(FalseClass)
-        end
-      end
-      
-      def sections_for(object); [] end
-      
-      def before_section(section, object); end
-      
-      def render_sections(object, sections = nil)
-        sections ||= sections_for(object) || []
-
-        data = ""
-        sections.each_with_index do |section, index|
-          next if section.is_a?(Array)
-          
-          data << if sections[index+1].is_a?(Array)
-            render_section(section, object) do |obj|
-              tmp, @current_object = @current_object, obj
-              out = render_sections(obj, sections[index+1])
-              @current_object = tmp
-              out
-            end
-          else
-            render_section(section, object)
-          end
-        end
-        data
-      end
-
-      def render_section(section, object, &block)
-        begin
-          if section.is_a?(Class) && section <= Generators::Base
-            opts = options.dup
-            opts.update(:ignore_serializer => true)
-            sobj = section.new(opts)
-            sobj.generate(object, &block)
-          elsif section.is_a?(Generators::Base)
-            section.generate(object, &block)
-          elsif section.is_a?(Symbol) || section.is_a?(String)
-            return "" if run_before_sections(section, object).is_a?(FalseClass)
-
-            if section.is_a?(Symbol)
-              if respond_to?(section)
-                if method(section).arity != 1
-                  send(section, &block)
-                else
-                  send(section, object, &block) 
-                end || ""
-              else # treat it as a String
-                render(object, section, &block)
-              end
-            else
-              render(object, section, &block)
-            end
-          else
-            type = section.is_a?(String) || section.is_a?(Symbol) ? 'section' : 'generator'
-            log.warn "Ignoring invalid #{type} '#{section}' in #{self.class}"
-            ""
-          end
-        end
-      end
-      
-      def render(object, file = nil, locals = {}, &block)
-        if object.is_a?(Symbol)
-          object, file, locals = current_object, object, (file||{})
-        end
-        
-        path = template_path(file.to_s + '.erb', generator_name)
-        filename = find_template(path)
-        if filename
-          begin
-            render_method(object, filename, locals, &block)           
-          rescue => e
-            log.error "#{e.class.class_name}: #{e.message}"
-            log.error "in generator #{self.class}: #{filename}"
-            log.error e.backtrace[0..10].join("\n")
-            exit
-          end
-        else
-          log.warn "Cannot find template `#{path}`"
-          ""
-        end
-      end
-      
-      def render_method(object, filename, locals = {}, &block)
-        l = locals.map {|k,v| "#{k} = locals[#{k.inspect}]" }.join(";")
-        src = erb("<% #{l} %>" + File.read(filename)).src
-        instance_eval(src, filename, 1)
-      end
-      
-      def erb(str)
-        ERB.new(str, nil, '<>')
-      end
-      
-      def template_path(file, generator = generator_name)
-        File.join(template.to_s, generator, format.to_s, file.to_s)
-      end
-      
-      def find_template(path)
-        self.class.template_paths.each do |basepath| 
-          f = File.join(basepath, path)
-          return f if File.file?(f)
-        end
-        nil
-      end
-    end
-  end
-end