tomdoc 0.2.3 → 0.2.4

data/Rakefile

@@ -1,3 +1,5 @@
+require File.dirname(__FILE__) + '/lib/tomdoc/version'
+
 require 'rake/testtask'
 
 def command?(command)
@@ -33,18 +35,18 @@ end
 task :default => :test
 
 if command? :turn
-  desc "Run tests"
-  task :test do
+  desc "Run tests with turn"
+  task :turn do
     suffix = "-n #{ENV['TEST']}" if ENV['TEST']
     sh "turn -Ilib:. test/*.rb #{suffix}"
   end
-else
-  Rake::TestTask.new do |t|
-    t.libs << 'lib'
-    t.libs << '.'
-    t.pattern = 'test/**/*_test.rb'
-    t.verbose = false
-  end
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.libs << '.'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
 end
 
 
@@ -62,20 +64,25 @@ end
 # Gems
 #
 
-begin
-  require 'tomdoc/version'
-  require 'mg'
-  MG.new("tomdoc.gemspec")
+desc "Build gem."
+task :gem do
+  sh "gem build tomdoc.gemspec"
+end
+
+task :push => [:gem] do
+  file = Dir["*-#{TomDoc::VERSION}.gem"].first
+  sh "gem push #{file}"
+end
 
-  desc "Push a new version to Gemcutter and publish docs."
-  task :publish => "gem:publish" do
-    require File.dirname(__FILE__) + '/lib/tomdoc/version'
+desc "tag version"
+task :tag do
+  sh "git tag v#{TomDoc::VERSION}"
+  sh "git push origin master --tags"
+  sh "git clean -fd"
+end
 
-    sh "git tag v#{TomDoc::VERSION}"
-    sh "git push origin master --tags"
-    sh "git clean -fd"
-  end
-rescue LoadError
-  warn "mg not available."
-  warn "Install it with: gem i mg"
+desc "tag version and push gem to server"
+task :release => [:push, :tag] do 
+  puts "And away she goes!"
 end
+

data/lib/tomdoc/tomdoc.rb

@@ -31,62 +31,283 @@ module TomDoc
     end
   end
 
+  #
+  # TODO: Instead of having TomDoc::TomDoc, lets consider renaming this
+  #       class TomDoc::Comment or something.
+  #
   class TomDoc
     attr_accessor :raw
 
-    def initialize(text)
+    # Public: Initialize a TomDoc object.
+    #
+    # text - The raw text of a method or class/module comment.
+    #
+    # Returns new TomDoc instance.
+    def initialize(text, options={})
       @raw = text.to_s.strip
+
+      @arguments        = []
+      @examples         = []
+      @returns          = []
+      @raises           = []
+      @signatures       = []
+      @signature_fields = []
+
+      parse unless @raw.empty?
     end
 
     def to_s
       @raw
     end
 
+    # Validate given comment text.
+    #
+    # Returns true if comment is valid, otherwise false.
     def self.valid?(text)
       new(text).valid?
     end
 
+    # Validate raw comment.
+    #
+    # Returns true if comment is valid, otherwise false.
     def valid?
-      validate
-    rescue InvalidTomDoc
-      false
+      return false if !raw.include?('Returns')
+      return false if sections.size < 2
+      true
     end
 
+    # Validate raw comment.
+    #
+    # Returns true if comment is valid.
+    # Raises InvalidTomDoc if comment is not valid.
     def validate
       if !raw.include?('Returns')
         raise InvalidTomDoc.new("No `Returns' statement.")
       end
 
-      if tomdoc.split("\n\n").size < 2
+      if sections.size < 2
         raise InvalidTomDoc.new("No description section found.")
       end
 
       true
     end
 
+    # The raw comment text cleaned-up and ready for section parsing.
+    #
+    # Returns cleaned-up comment String.
     def tomdoc
-      #raw
-      clean = raw.split("\n").map do |line|
-        line =~ /^(\s*# ?)/ ? line.sub($1, '') : nil
-      end.compact.join("\n")
-      clean
+      lines = raw.split("\n")
+
+      # remove remark symbol
+      if lines.all?{ |line| /^\s*#/ =~ line }   
+        lines = lines.map do |line|
+          line =~ /^(\s*#)/ ? line.sub($1, '') : nil
+        end
+      end
+
+      # for some reason the first line is coming in without indention
+      # regardless.
+      first = lines.shift
+
+      # remove indention
+      spaces = lines.map do |line|
+        next if line.strip.empty?
+        md = /^(\s*)/.match(line)
+        md ? md[1].size : nil
+      end.compact
+
+      space = spaces.min
+      lines = lines.map do |line|
+        if line.empty?
+          line.strip
+        else
+          line[space..-1]
+        end
+      end
+
+      # put first line back
+      lines.unshift(first.sub(/^\s*/,''))
+
+      lines.compact.join("\n")
     end
 
+    # List of comment sections. These are divided simply on "\n\n".
+    #
+    # Returns Array of comment sections.
     def sections
-      tomdoc.split("\n\n")
+      parsed {
+        @sections
+      }
     end
 
+    # Description of method or class/module.
+    #
+    # Returns description String.
     def description
-      sections.first
+      parsed {
+        @description
+      }
+    end
+
+    # Description of method or class/module.
+    #
+    # Returns description String.
+    def arguments
+      parsed {
+        @arguments
+      }
+    end
+    alias args arguments
+
+    # List of use examples of a method or class/module.
+    #
+    # Returns String of examples.
+    def examples
+      parsed {
+        @examples
+      }
+    end
+
+    # Description of a methods yield procedure.
+    #
+    # Returns String decription of yield procedure.
+    def yields
+      parsed {
+        @yields
+      }
+    end
+
+    # The list of retrun values a method can return.
+    #
+    # Returns Array of method return descriptions.
+    def returns
+      parsed {
+        @returns
+      }
+    end
+
+    # A list of errors a method might raise.
+    #
+    # Returns Array of method raises descriptions.
+    def raises
+      parsed {
+        @raises
+      }
+    end
+
+    # A list of alternate method signatures.
+    #
+    # Returns Array of signatures.
+    def signatures
+      parsed {
+        @signatures 
+      }
+    end
+
+    # A list of signature fields.
+    #
+    # Returns Array of field definitions.
+    def signature_fields
+      parsed {
+        @signature_fields
+      }
+    end
+
+    # Check if method is public.
+    #
+    # Returns true if method is public.
+    def public?
+      parsed {
+        @status == 'Public'
+      }
+    end
+
+    # Check if method is internal.
+    #
+    # Returns true if method is internal.
+    def internal?
+      parsed {
+        @status == 'Internal'
+      }
+    end
+
+    # Check if method is deprecated.
+    #
+    # Returns true if method is deprecated.
+    def deprecated?
+      parsed {
+        @status == 'Deprecated'
+      }
+    end
+
+  private
+
+    # Has the comment been parsed yet?
+    def parsed(&block)
+      parse unless @parsed
+      block.call
+    end
+
+    # Internal: Parse the Tomdoc formatted comment.
+    #
+    # Returns true if there was a comment to parse.
+    def parse
+      @parsed = true
+
+      @sections = tomdoc.split("\n\n")
+      sections  = @sections.dup
+
+      return false if sections.empty?
+
+      parse_description(sections.shift)
+
+      if sections.first && sections.first =~ /^\w+\s+\-/m
+        parse_arguments(sections.shift)
+      end
+
+      current = sections.shift
+      while current
+        case current
+        when /^Examples/
+          parse_examples(current, sections)
+        when /^Yields/
+          parse_yields(current)
+        when /^(Returns|Raises)/
+          parse_returns(current)
+        when /^Signature/
+          parse_signature(current, sections)
+        end
+        current = sections.shift
+      end
+
+      return @parsed
     end
 
-    def args
+    # Parse description.
+    #
+    # section - String containig description.
+    #
+    # Returns nothing.
+    def parse_description(section)
+      if md = /^([A-Z]\w+\:)/.match(section)
+        @status      = md[1].chomp(':')
+        @description = md.post_match.strip
+      else
+        @description = section.strip
+      end   
+    end
+
+    # Parse arguments section. Arguments occur subsequent to
+    # the description.
+    #
+    # section - String contaning agument definitions.
+    #
+    # Returns nothing.
+    def parse_arguments(section)
       args = []
       last_indent = nil
 
-      return args unless sections[1]
-
-      sections[1].split("\n").each do |line|
+      section.split("\n").each do |line|
         next if line.strip.empty?
         indent = line.scan(/^\s*/)[0].to_s.size
 
@@ -100,54 +321,117 @@ module TomDoc
         last_indent = indent
       end
 
-      args
+      @arguments = args
     end
 
-    def examples
-      if tomdoc =~ /(\s*Examples\s*(.+?)\s*(?:Returns|Raises))/m
-        $2.split("\n\n")
-      else
-        []
+    # Parse examples.
+    #
+    # section  - String starting with `Examples`.
+    # sections - All sections subsequent to section.
+    #
+    # Returns nothing.
+    def parse_examples(section, sections)
+      examples = []
+
+      section = section.sub('Examples', '').strip
+
+      examples << section unless section.empty?
+      while sections.first && sections.first !~ /^\S/
+        examples << sections.shift.strip
       end
+
+      @examples = examples
     end
 
-    def returns
-      if tomdoc =~ /^\s*(Returns.+)/m
-        lines = $1.split("\n")
-        statements = []
-
-        lines.each do |line|
-          next if line =~ /^\s*Raises/
-          if line =~ /^\s+/
-            statements.last << line.squeeze(' ')
-          else
-            statements << line
-          end
+    # Parse yields section.
+    #
+    # section - String contaning Yields line.
+    #
+    # Returns nothing.
+    def parse_yields(section)
+      @yields = section.strip
+    end
+
+    # Parse returns section.
+    #
+    # section - String contaning Returns and/or Raises lines.
+    #
+    # Returns nothing.
+    def parse_returns(section)
+      returns, raises, current = [], [], []
+
+      lines = section.split("\n")  
+      lines.each do |line|
+        case line
+        when /^Returns/
+          returns << line
+          current = returns
+        when /^Raises/
+          raises << line
+          current = raises
+        when /^\s+/
+          current.last << line.squeeze(' ')
+        else
+          current << line  # TODO: What to do with non-compliant line?
         end
+      end
 
-        statements
-      else
-        []
+      @returns, @raises = returns, raises
+    end
+
+    # Parse signature section.
+    #
+    # section  - String starting with `Signature`.
+    # sections - All sections subsequent to section.
+    #
+    # Returns nothing.
+    def parse_signature(section, sections=[])
+      signatures = []
+
+      section = section.sub('Signature', '').strip
+
+      signatures << section unless section.empty?
+
+      while sections.first && sections.first !~ /^\S/
+        sigs = sections.shift
+        sigs.split("\n").each do |s|
+          signatures << s.strip
+        end
+      end
+
+      @signatures = signatures
+
+      if sections.first && sections.first =~ /^\w+\s*\-/m
+        parse_signature_fields(sections.shift)
       end
     end
 
-    def raises
-      if tomdoc =~ /^\s*(Raises.+)/m
-        lines = $1.split("\n")
-        statements = []
-
-        lines.each do |line|
-          if line =~ /^\s+/
-            statements.last << line.squeeze(' ')
-          else
-            statements << line
-          end
+    # Subsequent to Signature section there can be field
+    # definitions.
+    #
+    # section  - String subsequent to signatures.
+    #
+    # Returns nothing.
+    def parse_signature_fields(section)
+      args = []
+      last_indent = nil
+
+      section.split("\n").each do |line|
+        next if line.strip.empty?
+        indent = line.scan(/^\s*/)[0].to_s.size
+
+        if last_indent && indent > last_indent
+          args.last.description += line.squeeze(" ")
+        else
+          param, desc = line.split(" - ")
+          args << Arg.new(param.strip, desc.strip) if param && desc
         end
 
-        statements
-      else
-        []
+        last_indent = indent
       end
+
+      @signature_fields = args
     end
+
   end
 end

data/lib/tomdoc/version.rb

@@ -1,3 +1,3 @@
 module TomDoc
-  VERSION = '0.2.3'
+  VERSION = '0.2.4'
 end

data/test/tomdoc_parser_test.rb

@@ -46,6 +46,31 @@ comment2
     #   multiplex('Bo', 2)
     #   # => 'BoBo'
 comment3
+
+    @comment4 = TomDoc::TomDoc.new(<<comment4)
+    # Duplicate some text an abitrary number of times.
+    #
+    # Yields the Integer index of the iteration.
+    #
+    # Signature
+    #
+    #   find_by_<field>[_and_<field>...](args)
+    #
+    # field - A field name.
+comment4
+
+    @comment5 = TomDoc::TomDoc.new(<<comment5)
+    Duplicate some text an abitrary number of times.
+    
+    Yields the Integer index of the iteration.
+    
+    Signature
+    
+      find_by_<field>[_and_<field>...](args)
+    
+    field - A field name.
+comment5
+
   end
 
   test "knows when TomDoc is invalid" do
@@ -92,7 +117,7 @@ comment3
   end
 
   test "knows each example" do
-    assert_equal "  multiplex('Bo', 2)\n  # => 'BoBo'",
+    assert_equal "multiplex('Bo', 2)\n  # => 'BoBo'",
       @comment.examples[1].to_s
   end
 
@@ -124,4 +149,26 @@ comment3
   test "knows what to do when there are no return examples" do
     assert_equal 0, @comment2.examples.size
   end
+
+  test "knows what the method yields" do
+    assert_equal "Yields the Integer index of the iteration.", @comment4.yields
+  end
+
+  test "knows if the method has alternate signatures" do
+    assert_equal 1, @comment4.signatures.size
+    assert_equal "find_by_<field>[_and_<field>...](args)", @comment4.signatures.first
+  end
+
+  test "knows the fields associated with signatures" do
+    assert_equal 1, @comment4.signature_fields.size
+
+    arg = @comment4.signature_fields.first
+    assert_equal :field, arg.name
+    assert_equal "A field name.", arg.description
+  end
+
+  test "can hande comments without comment marker" do
+    assert_equal "Duplicate some text an abitrary number of times.",
+      @comment5.description
+  end
 end

metadata

@@ -1,62 +1,51 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: tomdoc
-version: !ruby/object:Gem::Version 
-  hash: 17
+version: !ruby/object:Gem::Version
+  version: 0.2.4
   prerelease: 
-  segments: 
-  - 0
-  - 2
-  - 3
-  version: 0.2.3
 platform: ruby
-authors: 
+authors:
 - Tom Preston-Werner
 - Chris Wanstrath
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-06-10 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-02-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: ruby_parser
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &18375600 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 7
-        segments: 
-        - 2
-        - 0
-        - 4
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 2.0.4
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: colored
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *18375600
+- !ruby/object:Gem::Dependency
+  name: colored
+  requirement: &18375180 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id002
-description: "  TomDoc is flexible code documentation with human readers in\n  mind. The tomdoc gem is a Ruby library to discover and display\n  TomDoc'd methods and classes.\n\n  Given a Ruby file with TomDoc'd methods, tomdoc can generate HTML or\n  print to the console. You can use it to query up a single method or\n  a group of methods, and it's usable from irb.\n\n  If you're using TomDoc, tomdoc is for you.\n"
+  prerelease: false
+  version_requirements: *18375180
+description: ! "  TomDoc is flexible code documentation with human readers in\n  mind.
+  The tomdoc gem is a Ruby library to discover and display\n  TomDoc'd methods and
+  classes.\n\n  Given a Ruby file with TomDoc'd methods, tomdoc can generate HTML
+  or\n  print to the console. You can use it to query up a single method or\n  a group
+  of methods, and it's usable from irb.\n\n  If you're using TomDoc, tomdoc is for
+  you.\n"
 email: chris@ozmm.org
-executables: 
+executables:
 - tomdoc
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - README.md
 - Rakefile
 - LICENSE
@@ -86,36 +75,27 @@ files:
 - test/fixtures/simple.rb
 homepage: http://github.com/defunkt/tomdoc
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.2
+rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
 summary: A TomDoc library for Ruby.
 test_files: []
-
+has_rdoc: false