yard-tomdoc 0.2.1 → 0.3.0

data/HISTORY.md

@@ -1,5 +1,16 @@
 # RELEASE HISTORY
 
+## 0.3.0 | 2011-06-08
+
+Okay,looks like tomdoc is ready to handle the dependency. If there
+are any problems with this there is a fallback plugin, `tomdoc-intern`.
+
+Changes:
+
+* Depend on tomdoc proper.
+* Add fallback `yard-tomdoc-intern.rb`
+
+
 ## 0.2.1 | 2011-05-23
 
 There is an as-of-yet undetermined issue with running yard-tomdoc under

data/lib/yard-tomdoc/arg.rb

@@ -0,0 +1,22 @@
+module TomDoc
+  class Arg
+    attr_accessor :name, :description
+
+    # Create new Arg object.
+    #
+    # name        - name of argument
+    # description - arguments description
+    #
+    def initialize(name, description = '')
+      @name = name.to_s.intern
+      @description = description
+    end
+
+    # Is this an optional argument?
+    #
+    # Returns Boolean.
+    def optional?
+      @description.downcase.include? 'optional'
+    end
+  end
+end

data/lib/yard-tomdoc/tomdoc.rb

@@ -1,6 +1,13 @@
-#require 'yard'
-
 module TomDoc
+
+  # TomDoc class needs Arg class.
+  if RUBY_VERSION > '1.9'
+    require_relative 'arg'
+  else
+    require 'yard-tomdoc/arg'
+  end
+
+  # This error is raised if comment is not valid TomDoc format.
   class InvalidTomDoc < RuntimeError
     # Create new InvalidTomDoc object.
     #
@@ -12,40 +19,20 @@ module TomDoc
 
     # Provide access to document string.
     #
-    # Returns String.
+    # Returns [String] documentation string.
     def message
       @doc
     end
 
     # Provide access to document string.
     #
-    # Returns String.
+    # Returns [String] documentation string.
     def to_s
       @doc
     end
   end
-  
-  class Arg
-    attr_accessor :name, :description
-
-    # Create new Arg object.
-    #
-    # name        - name of argument
-    # description - arguments description
-    #
-    def initialize(name, description = '')
-      @name = name.to_s.intern
-      @description = description
-    end
-
-    # Is this an optional argument?
-    #
-    # Returns Boolean.
-    def optional?
-      @description.downcase.include? 'optional'
-    end
-  end
 
+  # Model a TomDoc comment.
   class TomDoc
     attr_accessor :raw
 
@@ -53,20 +40,24 @@ module TomDoc
       @raw = text.to_s.strip
     end
 
+    # Returns [String] raw comment text.
     def to_s
       @raw
     end
 
+    # Returns [Boolean] true if valid TomDoc comment.
     def self.valid?(text)
       new(text).valid?
     end
 
+    # Returns [Boolean] true if valid TomDoc comment, otherwise false.
     def valid?
       validate
     rescue InvalidTomDoc
       false
     end
 
+    # Returns [Boolean] true if validation doesn't raise an error.
     def validate
       if !raw.include?('Returns')
         raise InvalidTomDoc.new("No `Returns' statement.")
@@ -79,18 +70,26 @@ module TomDoc
       true
     end
 
+    # Returns [String] cleansed comment text.
     def tomdoc
       raw
+      #clean = raw.split("\n").map do |line|
+      #  line =~ /^(\s*# ?)/ ? line.sub($1, '') : line
+      #end.compact.join("\n")
+      #clean
     end
 
+    # Returns [Array] document split into sections.
     def sections
       tomdoc.split("\n\n")
     end
 
+    # Returns [String] first section.
     def description
       sections.first
     end
 
+    # Returns [Array] list of arguments.
     def args
       args = []
       last_indent = nil
@@ -114,6 +113,7 @@ module TomDoc
       args
     end
 
+    # Returns [Array] list of examples.
     def examples
       if tomdoc =~ /(\s*Examples\s*(.+?)\s*(?:Returns|Raises))/m
         $2.split("\n\n")
@@ -122,6 +122,7 @@ module TomDoc
       end
     end
 
+    # Returns [Array] list of possible returns.
     def returns
       if tomdoc =~ /^\s*(Returns.+)/m
         lines = $1.split("\n")
@@ -142,6 +143,7 @@ module TomDoc
       end
     end
 
+    # Returns [Array] list of possible errors that could be raised.
     def raises
       if tomdoc =~ /^\s*(Raises.+)/m
         lines = $1.split("\n")

data/lib/yard-tomdoc/yard.rb

@@ -0,0 +1,39 @@
+module YARD
+
+  class Docstring
+
+    # Parse comments with TomDoc and then provide YARD with results. 
+    #
+    # comments - comment String
+    #
+    # Returns [String] of parsed comments description.
+    def parse_comments(comments)
+      comment = [comments].flatten.join("\n")
+
+      tomdoc = TomDoc::TomDoc.new(comment)
+
+      tomdoc.examples.each {|ex| create_tag(:example, "\n" + ex) }
+
+      tomdoc.args.each {|arg| create_tag(:param, "#{arg.name} #{arg.description}") }
+
+      tomdoc.raises.each {|r| create_tag(:raise, r.sub(/\ARaises\s+/, '')) }
+
+      tomdoc.returns.each do |r|
+        if md = /\AReturns\s+([A-Z].*?)\s+/.match(r)
+          klass = md[1]
+          desc  = md.post_match
+          create_tag(:return, "[#{klass}] #{desc}")
+        else
+          desc = r.sub(/\AReturns\s+/, '')
+          create_tag(:return, desc)
+        end
+      end
+
+      # notice we return the modified comment
+      tomdoc.description.to_s
+    end
+
+  end
+
+end
+

data/lib/yard-tomdoc-intern.rb

@@ -0,0 +1,2 @@
+require 'yard-tomdoc/tomdoc'
+require 'yard-tomdoc/yard'

data/lib/yard-tomdoc.rb

@@ -1,42 +1,6 @@
-#require 'tomdoc/tomdoc'
-require 'yard-tomdoc/tomdoc'
-
-module YARD
-
-  class Docstring
-
-    # Parse comments with TomDoc and then provide YARD with results. 
-    #
-    # comments - comment String
-    #
-    # Returns a String of parsed comments description.
-    def parse_comments(comments)
-      comment = [comments].flatten.join("\n")
-
-      tomdoc = TomDoc::TomDoc.new(comment)
-
-      tomdoc.examples.each {|ex| create_tag(:example, "\n" + ex) }
-
-      tomdoc.args.each {|arg| create_tag(:param, "#{arg.name} #{arg.description}") }
-
-      tomdoc.raises.each {|r| create_tag(:raise, r.sub(/\ARaises\s+/, '')) }
-
-      tomdoc.returns.each do |r|
-        if md = /\AReturns\s+([A-Z].*?)\s+/.match(r)
-          klass = md[1]
-          desc  = md.post_match
-          create_tag(:return, "[#{klass}] #{desc}")
-        else
-          desc = r.sub(/\AReturns\s+/, '')
-          create_tag(:return, desc)
-        end
-      end
-
-      # notice we return the modified comment
-      tomdoc.description.to_s
-    end
-
-  end
-
+begin
+  require 'tomdoc/tomdoc'
+rescue LoadError
+  require 'yard-tomdoc/tomdoc'
 end
-
+require 'yard-tomdoc/yard'

data/test/test_docstring.rb

@@ -0,0 +1,53 @@
+$:.unshift File.expand_path(File.dirname(__FILE__)) + "/../lib"
+
+require 'minitest/autorun'
+
+require "yard"
+require "yard-tomdoc"
+
+# TODO: make separate test for this
+#require "yard-tomdoc-intern"
+
+describe YARD::Docstring do
+
+  before do
+    @docstring = YARD::Docstring.new <<-eof
+Duplicate some text an arbitrary number of times.
+
+text  - The String to be duplicated.
+count - The Integer number of times to duplicate the text.
+
+Examples
+  multiplex('Tom', 4)
+  # => 'TomTomTomTom'
+
+Returns the duplicated String.
+
+Raises ArgumentError if something bad happened
+eof
+  end
+
+  it "should fill docstring with description" do
+    @docstring.must_equal "Duplicate some text an arbitrary number of times."
+  end
+
+  it "should fill param tags" do
+    tags = @docstring.tags(:param)
+    tags.size.must_equal 2
+    tags[0].name.must_equal 'text'
+    tags[1].name.must_equal 'count'
+  end
+  
+  it "should fill examples tags" do
+    @docstring.tags(:example).size.must_equal 1
+    @docstring.tag(:example).text.must_equal "multiplex('Tom', 4)\n  # => 'TomTomTomTom'"
+  end
+  
+  it "should fill return tag" do
+    @docstring.tag(:return).text.must_equal "the duplicated String."
+  end
+
+  it "should fill raise tag" do
+    @docstring.tag(:raise).text.must_equal "ArgumentError if something bad happened"
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: yard-tomdoc
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: 
   segments: 
   - 0
-  - 2
-  - 1
-  version: 0.2.1
+  - 3
+  - 0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Loren Segal
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-24 00:00:00 Z
+date: 2011-06-08 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: ko
@@ -55,12 +55,14 @@ extensions: []
 extra_rdoc_files: 
 - README.md
 files: 
+- lib/yard-tomdoc/arg.rb
 - lib/yard-tomdoc/tomdoc.rb
+- lib/yard-tomdoc/yard.rb
+- lib/yard-tomdoc-intern.rb
 - lib/yard-tomdoc.rb
-- test/case_docstring.rb
+- test/test_docstring.rb
 - HISTORY.md
 - README.md
-- Version
 - MIT.txt
 - NOTICE.md
 homepage: http://rubyworks.github.com/yard-tomdoc

data/Version

@@ -1 +0,0 @@
-0.2.1

data/test/case_docstring.rb

@@ -1,48 +0,0 @@
-$:.unshift File.dirname(__FILE__) + "/../lib"
-
-require "yard"
-require "yard-tomdoc"
-
-KO.case 'YARD::Docstring' do
-
-  setup do
-    @docstring = ::YARD::Docstring.new <<-eof
-Duplicate some text an arbitrary number of times.
-
-text  - The String to be duplicated.
-count - The Integer number of times to duplicate the text.
-
-Examples
-  multiplex('Tom', 4)
-  # => 'TomTomTomTom'
-
-Returns the duplicated String.
-
-Raises ArgumentError if something bad happened
-eof
-  end
-
-  test "should fill docstring with description" do
-    @docstring == "Duplicate some text an arbitrary number of times."
-  end
-
-  test "should fill param tags" do
-    tags = @docstring.tags(:param)
-    tags.size    == 2      &&
-    tags[0].name == 'text' &&
-    tags[1].name == 'count'
-  end
-  
-  test "should fill examples tags" do
-    @docstring.tags(:example).size == 1 &&
-    @docstring.tag(:example).text  == "multiplex('Tom', 4)\n  # => 'TomTomTomTom'"
-  end
-  
-  test "should fill return tag" do
-    @docstring.tag(:return).text == "the duplicated String."
-  end
-
-  test "should fill raise tag" do
-    @docstring.tag(:raise).text == "ArgumentError if something bad happened"
-  end
-end