yard 0.2.2 → 0.2.3

data/README

@@ -1,211 +0,0 @@
-= YARD Release 0.2.2 (June 16th 2008) 
-Copyright 2007-2008 Loren Segal
-
-== SYNOPSIS
-
-YARD is a documentation generation tool for the Ruby programming language
-(http://www.ruby-lang.org). It enables the user to generate consistent, usable
-documentation that can be exported to a number of formats very easily, and
-also supports extending for custom Ruby constructs such as custom class level 
-definitions. Below is a summary of some of YARD's notable features.
-
-
-== FEATURE LIST
-                                                                              
-1. <b>RDoc/SimpleMarkup Formatting Compatibility</b>: YARD is made to be compatible   
-   with RDoc formatting. In fact, YARD does no processing on RDoc documentation  
-   strings, and leaves this up to the output generation tool to decide how to    
-   render the documentation.                                                     
-
-2. <b>Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other        
-   languages</b>: YARD uses a '@tag' style definition syntax for meta tags alongside 
-   regular code documentation. These tags should be able to happily sit side by  
-   side RDoc formatted documentation, but provide a much more consistent and     
-   usable way to describe important information about objects, such as what      
-   parameters they take and what types they are expected to be, what type a      
-   method should return, what exceptions it can raise, if it is deprecated, etc..
-   It also allows information to be better (and more consistently) organized     
-   during the output generation phase. Some of the main tags are listed below:   
-                                                                              
-   <b>Table 1. Meta-tags and their descriptions</b>                                    
-                                                                              
-   <tt>@param [Types] name description</tt>::
-     Description Allows for the definition of a method parameter with 
-     optional type information.
-                                                                              
-   <tt>@yieldparam [Types] name description</tt>::
-     Description Allows for the definition of a method parameter to a
-     yield block with optional type information.
-   
-   <tt>@yield description</tt>::                                        
-     Allows the developer to document the purpose of a yield block in 
-     a method.
-   
-   @return [Types] description</tt>::
-     Describes what the method returns with optional type information.
-
-   <tt>@deprecated description</tt>::
-     Informs the developer that a method is deprecated and should no 
-     longer be used. The description offers the developer an alternative 
-     solution or method for the problem.
-                                                 
-   <tt>@raise class description</tt>::
-     Tells the developer that the method may raise an exception and of 
-     what type. 
-   
-   <tt>@see name</tt>::
-     References another object, URL, or other for extra information. 
-
-   <tt>@since number</tt>::
-     Lists the version number in which the object first appeared. 
-
-   <tt>@version number</tt>::
-     Lists the current version of the documentation for the object. 
-
-   <tt>@author name</tt>::
-     The authors responsible for the module
-
-   You might have noticed the optional "types" declarations for certain tags.    
-   This allows the developer to document type signatures for ruby methods and    
-   parameters in a non intrusive but helpful and consistent manner. Instead of   
-   describing this data in the body of the description, a developer may formally 
-   declare the parameter or return type(s) in a single line. Consider the        
-   following Yardoc'd method:                                                    
-
-     ## 
-     # Reverses the contents of a String or IO object. 
-     # 
-     # @param [String, #read] contents the contents to reverse 
-     # @return [String] the contents reversed lexically 
-     def reverse(contents) 
-       contents = contents.read if respond_to? :read 
-       contents.reverse 
-     end                                        
-                                                                               
-   With the above @param tag, we learn that the contents parameter can either be
-   a String or any object that responds to the 'read' method, which is more      
-   powerful than the textual description, which says it should be an IO object.  
-   This also informs the developer that they should expect to receive a String   
-   object returned by the method, and although this may be obvious for a         
-   'reverse' method, it becomes very useful when the method name may not be as   
-   descriptive.                                                                  
-                                                                              
-3. <b>Custom Constructs and Extensibility of YARD</b>: Take for instance the example:        
-   
-     class A 
-       class << self 
-         def define_name(name, value) 
-           class_eval "def #{name}; #{value.inspect} end" 
-         end 
-       end 
-    
-       # Documentation string for this name 
-       define_name :publisher, "O'Reilly"
-     end
-                                                                              
-   This custom declaration provides dynamically generated code that is hard for a
-   documentation tool to properly document without help from the developer. To   
-   ease the pains of manually documenting the procedure, YARD can be extended by 
-   the developer to handled the 'define_name' construct and add the required     
-   method to the defined methods of the class with its documentation. This makes 
-   documenting external API's, especially dynamic ones, a lot more consistent for
-   consumption by the users.                                                     
-                                                                              
-4. <b>Raw Data Output</b>: YARD also outputs documented objects as raw data (the      
-   dumped Namespace) which can be reloaded to do generation at a later date, or  
-   even auditing on code. This means that any developer can use the raw data to  
-   perform output generation for any custom format, such as YAML, for instance.  
-   While YARD plans to support XHTML style documentation output as well as       
-   command line (text based) and possibly XML, this may still be useful for those
-   who would like to reap the benefits of YARD's processing in other forms, such 
-   as throwing all the documentation into a database. Another useful way of      
-   exploiting this raw data format would be to write tools that can auto generate
-   test cases, for example, or show possible unhandled exceptions in code.       
-                                                                              
-
-== USAGE                                                                        
-
-There are a couple of ways to use YARD. The first is via command-line, and the
-second is the Rake task. There are also the +yard-graph+ and +yri+ binaries to
-look at, if you want to poke around.
-
-=== 1. yardoc Command-line Tool
-
-The most obvious way to run YARD is to run the +yardoc+ binary file that comes
-with YARD. This will, among other things, generate the HTML documentation for
-your project code. You can type <tt>yardoc --help</tt> to see the options
-that YARD provides, but the easiest way to generate docs for your code is to
-simply type +yardoc+ in your project root. This will assume your files are
-located in the +lib/+ directory. If they are located elsewhere, you can specify
-paths and globs from the commandline via:
-
-  yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...
-  
-The tool will generate a +.yardoc+ file which will store the cached database
-of your source code and documentation. If you want to re-generate your docs
-with another template you can simply use the <tt>--use-cache</tt> (or -c) 
-option to speed up the generation process by skipping source parsing.
-
-YARD will by default only document code in your public visibility. You can
-document your protected and private code by adding <tt>--protected</tt> or
-<tt>--private</tt> to the option switches.
-
-=== 2. Rake Task
-
-The second most obvious is to generate docs via a Rake task. You can do this by 
-adding the following to your +Rakefile+:
-
-  YARD::Rake::YardocTask.new do |t|
-    t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
-    t.options = ['--any', '--extra', '--opts'] # optional
-  end
-  
-both the +files+ and +options+ settings are optional. +files+ will default to
-<tt>lib/**/*.rb</tt> and +options+ will represents any options you might want
-to add. Again, a full list of options is available by typing <tt>yardoc --help</tt>
-in a shell. You can also override the options at the Rake command-line with the
-OPTS environment variable:
-
-  > rake yardoc OPTS='--any --extra --opts'
-                                                                              
-=== 3. yri RI Implementation
-
-The yri binary will use the cached .yardoc database to give you quick ri-style
-access to your documentation. It's way faster than ri but currently does not
-work with the stdlib or core Ruby libraries, only the active project. Example:
-
-  > yri YARD::Handlers::Base#register
-  > yri File::relative_path
-
-=== 4. yard-graph Graphviz Generator
-
-You can use +yard-graph+ to generate dot graphs of your code. This, of course,
-requires Graphviz (http://www.graphviz.org) and the +dot+ binary. By default
-this will generate a graph of the classes and modules in the best UML2 notation
-that Graphviz can support, but without any methods listed. With the <tt>--full</tt>
-option, methods and attributes will be listed. There is also a <tt>--dependencies</tt>
-option to show mixin inclusions. You can output to stdout or a file, or pipe directly
-to +dot+. The same public, protected and private visibility rules apply to yard-graph.
-More options can be seen by typing <tt>yard-graph --help</tt>, but here is an example:
-
-  > yard-graph --protected --full --dependencies
-
-
-== CHANGELOG
-
-- <b>Jun.16.08</b>: 0.2.2 release. This is the largest changset since yard's 
-  conception and involves a complete overhaul of the parser and API to make it
-  more robust and far easier to extend and use for the developer.
-
-- <b>Feb.20.08</b>: 0.2.1 release. 
-
-- <b>Feb.24.07</b>: Released 0.1a experimental version for testing. The goal here is
-  to get people testing YARD on their code because there are too many possible  
-  code styles to fit into a sane amount of test cases. It also demonstrates the 
-  power of YARD and what to expect from the syntax (Yardoc style meta tags).    
-                                                                              
-
-== COPYRIGHT                                                                    
-
-YARD was created in 2007-2008 by Loren Segal (lsegal -AT- soen -DOT- ca) and is    
-licensed under the MIT license. Please see the LICENSE.txt for more information.

data/lib/yard/handlers/method_handler.rb

@@ -1,27 +0,0 @@
-class YARD::Handlers::MethodHandler < YARD::Handlers::Base
-  handles TkDEF
-    
-  def process
-    nobj = namespace
-    mscope = scope
-
-    if meth = statement.tokens.to_s[/^def\s+(#{METHODMATCH})/m, 1]
-      meth.gsub!(/\s+/,'')
-    else
-      raise YARD::Handlers::UndocumentableError, "method: invalid name"
-    end
-    
-    # Class method if prefixed by self(::|.) or Module(::|.)
-    if meth =~ /(?:#{NSEP}|\.)([^#{NSEP}\.]+)$/
-      mscope, meth = :class, $1
-      nobj = P(namespace, $`) unless $` == "self"
-    end
-    
-    obj = register MethodObject.new(nobj, meth, mscope) do |o| 
-      o.visibility = visibility 
-      o.source = statement
-      o.explicit = true
-    end
-    parse_block(:owner => obj) # mainly for yield/exceptions
-  end
-end

data/lib/yard/handlers/mixin_handler.rb

@@ -1,16 +0,0 @@
-class YARD::Handlers::MixinHandler < YARD::Handlers::Base
-  handles /\Ainclude(\s|\()/
-  
-  def process
-    statement.tokens[1..-1].to_s.split(/\s*,\s*/).each do |mixin|
-      mixin.strip!
-      if mixmatch = mixin[/\A(#{NAMESPACEMATCH})\s*/, 1] 
-        obj = Proxy.new(namespace, mixmatch)
-        obj.type = :module if obj.is_a?(Proxy)
-        namespace.mixins << obj
-      else
-        raise YARD::Handlers::UndocumentableError, "mixin #{mixin} for class #{namespace.path}"
-      end
-    end
-  end
-end

data/lib/yard/parser/statement_list.rb

@@ -1,167 +0,0 @@
-module YARD
-  module Parser
-    class StatementList < Array
-      include RubyToken
-
-      # The following list of tokens will require a block to be opened 
-      # if used at the beginning of a statement.
-      OPEN_BLOCK_TOKENS = [TkCLASS, TkDEF, TkMODULE, TkUNTIL,
-                           TkIF, TkUNLESS, TkWHILE, TkFOR, TkCASE]
-      COLON_TOKENS = [TkUNTIL, TkIF, TkUNLESS, TkWHILE, TkCASE, TkWHEN]
-
-      ##
-      # Creates a new statement list
-      #
-      # @param [TokenList, String] content the tokens to create the list from
-      def initialize(content)
-        if content.is_a? TokenList
-          @tokens = content.dup
-        elsif content.is_a? String
-          @tokens = TokenList.new(content)
-        else 
-          raise ArgumentError, "Invalid content for StatementList: #{content.inspect}:#{content.class}"
-        end
-
-        parse_statements
-      end
-
-      private
-
-      def parse_statements
-        while stmt = next_statement do self << stmt end
-      end
-
-      # MUST REFACTOR THIS CODE
-      # WARNING WARNING WARNING             WARNING
-      # MUST REFACTOR THIS CODE                |
-      # OR CHILDREN WILL DIE                   V
-      # WARNING WARNING WARNING             WARNING
-      # THIS IS MEANT TO BE UGLY.
-      def next_statement
-        statement, block, comments = TokenList.new, nil, nil
-        stmt_number, level = 0, 0
-        new_statement, open_block = true, false
-        last_tk, last_ns_tk, before_last_tk = nil, nil, nil
-        open_parens = 0
-
-        while tk = @tokens.shift
-          #p tk.class
-          # !!!!!!!!!!!!!!!!!!!! REMOVED TkfLPAREN, TkfLBRACK
-          open_parens += 1 if [TkLPAREN, TkLBRACK].include? tk.class
-          open_parens -= 1 if [TkRPAREN, TkRBRACK].include?(tk.class) 
-      
-          #if open_parens < 0 || level < 0
-          #  STDERR.puts block.to_s + " TOKEN #{tk.inspect}"
-          #  exit
-          #end
-
-          # Get the initial comments
-          if statement.empty?
-            # Two new-lines in a row will destroy any comment blocks
-            if [TkCOMMENT].include?(tk.class)  && last_tk.class == TkNL && 
-              (before_last_tk && (before_last_tk.class == TkNL || before_last_tk.class == TkSPACE))
-              comments = nil
-            elsif tk.class == TkCOMMENT
-              # Remove the "#" and up to 1 space before the text
-              # Since, of course, the convention is to have "# text"
-              # and not "#text", which I deem ugly (you heard it here first)
-              comments ||= []
-              comments << tk.text.gsub(/^#+\s{0,1}/, '') 
-              comments.pop if comments.size == 1 && comments.first =~ /^\s*$/
-            end
-          end
-                
-          # Ignore any initial comments or whitespace
-          unless statement.empty? && [TkSPACE, TkNL, TkCOMMENT].include?(tk.class)
-            # Decrease if end or '}' is seen
-            level -= 1 if [TkEND, TkRBRACE].include?(tk.class)
-        
-            # If the level is greater than 0, add the code to the block text
-            # otherwise it's part of the statement text
-            if stmt_number > 0
-              #puts "Block of #{statement}"
-              #puts "#{stmt_number} #{tk.line_no} #{level} #{open_parens} #{tk.class.class_name} \t#{tk.text.inspect} #{tk.lex_state} #{open_block.inspect}" 
-              block ||= TokenList.new
-              block << tk
-            elsif stmt_number == 0 && tk.class != TkNL && tk.class != TkSEMICOLON && tk.class != TkCOMMENT
-              statement << tk 
-            end
-
-            #puts "#{tk.line_no} #{level} #{open_parens} #{tk.class.class_name} \t#{tk.text.inspect} #{tk.lex_state} #{open_block.inspect}" 
-
-            # Increase level if we have a 'do' or block opening
-            if tk.class == TkLBRACE #|| tk.class == TkfLBRACE
-              level += 1    
-            elsif [TkDO, TkBEGIN].include?(tk.class) 
-              #p "#{tk.line_no} #{level} #{tk} \t#{tk.text} #{tk.lex_state}" 
-              level += 1    
-              open_block = false  # Cancel our wish to open a block for the if, we're doing it now
-            end
-
-            # Vouch to open a block when this statement would otherwise end
-            open_block = [level, tk.class] if (new_statement || 
-                                (last_tk && last_tk.lex_state == EXPR_BEG)) && 
-                                 OPEN_BLOCK_TOKENS.include?(tk.class)
-
-            # Check if this token creates a new statement or not
-            #puts "#{open_parens} open brackets for: #{statement.to_s}"
-            if open_parens == 0 && ((last_tk && [TkSEMICOLON, TkNL, TkEND_OF_SCRIPT].include?(tk.class)) ||
-              (open_block && open_block.last == TkDEF && tk.class == TkRPAREN))
-              
-              # Make sure we don't have any running expressions
-              # This includes things like
-              #
-              # class <
-              #   Foo
-              # 
-              # if a ||
-              #    b
-              if (last_tk && [EXPR_END, EXPR_ARG].include?(last_tk.lex_state)) || 
-                  (open_block && [TkNL, TkSEMICOLON].include?(tk.class) && last_ns_tk.class != open_block.last)
-                stmt_number += 1
-                new_statement = true
-                #p "NEW STATEMENT #{block.to_s}"
-
-                # The statement started with a if/while/begin, so we must go to the next level now
-                if open_block && open_block.first == level
-                  if tk.class == TkNL && block.nil?
-                    block = TokenList.new
-                    block << tk
-                  end
-
-                  open_block = false
-                  level += 1
-                end
-              end
-            elsif tk.class != TkSPACE
-              new_statement = false 
-            end
-
-            # Else keyword is kind of weird
-            if tk.is_a? TkELSE
-              new_statement = true
-              stmt_number += 1
-              open_block = false
-            end
-
-            # We're done if we've ended a statement and we're at level 0
-            break if new_statement && level == 0
-        
-            #raise "Unexpected end" if level < 0
-          end
-      
-          #break if new_statement && level == 0
-
-          before_last_tk = last_tk
-          last_tk = tk # Save last token
-          last_ns_tk = tk unless [TkSPACE, TkNL, TkEND_OF_SCRIPT].include? tk.class
-        end
-
-        # Return the code block with starting token and initial comments
-        # If there is no code in the block, return nil
-        comments = comments.compact if comments
-        statement.empty? ? nil : Statement.new(statement, block, comments)
-      end
-    end
-  end
-end

data/lib/yard/tags/merbdoc_factory.rb

@@ -1,47 +0,0 @@
-module YARD
-  module Tags
-    class MerbdocFactory < DefaultFactory
-      ##
-      # Parses tag text and creates a new tag with formally declared types and 
-      # descriptive text
-      #
-      # @param tag_name        the name of the tag to parse
-      # @param text<String>    the raw tag text
-      # @return <Tag>          a tag object with the tag_name, types and text values filled
-      def parse_tag_with_types(tag_name, text)
-        _, types, text = *extract_types_from_text(text)
-        # TODO warn if name value ('_') is not nil, because that's invalid syntax
-        Tag.new(tag_name, text, types)
-      end
-      
-      ##
-      # Parses tag text and creates a new tag with formally declared types, a key 
-      # name and descriptive text
-      #
-      # @param tag_name        the name of the tag to parse
-      # @param text<String>    the raw tag text
-      # @return <Tag>          a tag object with the tag_name, name, types and text values filled
-      def parse_tag_with_types_and_name(tag_name, text)
-        name, types, text = *extract_types_from_text(text)
-        name, text = *extract_name_from_text(text) if name.nil?
-        Tag.new(tag_name, text, types, name)
-      end
-      
-      private
-      
-      ##
-      # Extracts the type signatures with an optional name from the raw tag text
-      #
-      # @param text<String> the raw tag text
-      # @return <Array> an array holding the name as the first element (nil if empty),
-      #                 array of types as the second element and the raw text as the last.
-      def extract_types_from_text(text)
-        name, types, text = nil, [], text.strip
-        if text =~ /^\s*(\S*)\s*<(.+?)>\s*(.*)/
-          name, text, types = $1, $3, $2.split(",").collect {|e| e.strip }
-        end
-        [name, types, text]
-      end
-    end
-  end
-end