yard-tomdoc 0.4.0 → 0.5.0

data/Config.rb

@@ -0,0 +1,11 @@
+
+config 'rubytest' do |run|
+  require 'spectroscope'
+  require 'ae'
+
+  $:.unshift 'lib'
+  $:.unshift 'test'
+
+  run.files << 'test/**/test_*.rb'
+end
+

data/HISTORY.md

@@ -1,6 +1,25 @@
 # RELEASE HISTORY
 
-## 0.4.0  2012-03-04
+## 0.5.0 / 2012-06-14
+
+Version 0.8.0 of YARD broke the yard-tomdoc plugin. After some discussion with
+Loren Segal, the developer of YARD, he decided that a new API was needed for
+plugins like yard-tomdoc. So YARD 0.8.1 was born. This release takes advantage
+of the new API. If you are using the latest and greatest version of YARD, you 
+need to upgrade to yard-tomdoc 0.5+ too.
+
+Changes:
+
+* Improved support for YARD 0.8.1+.
+* Support multiple versions of YARD in a nice way.
+* Use @api private tag instead of @private for Internal status.
+* Add support for YARD version 0.8+.
+* Fixes for Internal and Deprecated marks.
+* Fix error for 'Deprecated' description
+* Fix Issue #3, Error for 'Internal' description.
+
+
+## 0.4.0 / 2012-03-04
 
 This major release now uses tomparse gem for parsing TomDoc,
 instead of the tomdoc gem. This library only handles parsing

data/README.md

@@ -20,6 +20,17 @@ Since `yard-tomdoc` is a standard YARD plugin, utilize it with yard's
     $ yard --plugin yard-tomdoc [...]
 
 
+## Documentation
+
+### API
+
+* Shomen -
+  [Rebecca](http://rubyworks.github.com/rebecca?doc=http://rubyworks.github.com/yard-tomdoc/docs/current.json) /
+  [Hypervisor](http://rubyworks.github.com/hypervisor?doc=http://rubyworks.github.com/yard-tomdoc/docs/current.json) /
+  [Rubyfaux](http://rubyworks.github.com/rubyfaux?doc=http://rubyworks.github.com/yard-tomdoc/docs/current.json)
+* YARD - [RubyDoc.info](http://rubydoc.info/gems/yard-tomdoc/frames)
+
+
 ## Limitations
 
 Before you use yard-tomdoc you should read about the differences between YARD

data/lib/yard-tomdoc.rb

@@ -21,51 +21,59 @@ module YARD
     def self.const_missing(name)
       metadata[name.to_s.downcase] || super(name)
     end
-  end
 
-  class Docstring
     # Parse comments with TomDoc and then provide YARD with results. 
     #
-    # comments - [Array] comment strings
+    # yard    - [Docstring,DocstringParser] instance of yard object
+    # comment - [String] comment string
     #
-    # Returns [String] parsed comments description
-    def parse_comments(comments)
-      comment = [comments].flatten.join("\n")
-
+    # Returns [TomDoc] instance of TomDoc 
+    def self.yard_parse(yard, comment)
       tomdoc = TomParse.parse(comment)
 
-      tomdoc.examples.each {|ex| create_tag(:example, "\n" + ex) }
+      # TODO: TomParse should make the `strip` unecessary
+      tomdoc.examples.each {|ex| yard.create_tag(:example, "\n" + ex.strip) }
 
-      tomdoc.arguments.each {|arg| create_tag(:param, "#{arg.name} #{arg.description}") }
+      # TODO: how to figure-out class of argument ?
+      tomdoc.arguments.each {|arg| yard.create_tag(:param, "#{arg.name} #{arg.description}") }
 
       if last_argument = tomdoc.arguments.last
         last_argument.options.each do |opt|
-          create_tag(:option, "#{last_argument.name} #{opt.description}")
+          yard.create_tag(:option, "#{last_argument.name} #{opt.description}")
         end
       end
 
-      tomdoc.raises.each {|r| create_tag(:raise, r.sub(/\ARaises\s+/, '')) }
+      tomdoc.raises.each {|r| yard.create_tag(:raise, r.sub(/\ARaises\s+/, '')) }
 
       tomdoc.returns.each do |r|
+      # TODO: improve how we figure out class of argument
         if md = /\AReturns\s+([A-Z].*?)\s+/.match(r)
           klass = md[1]
           desc  = md.post_match
-          create_tag(:return, "[#{klass}] #{desc}")
+          yard.create_tag(:return, "[#{klass}] #{desc}")
         else
           desc = r.sub(/\AReturns\s+/, '')
-          create_tag(:return, desc)
+          yard.create_tag(:return, desc)
         end
       end
 
-      create_tag(:yield, tomdoc.yields) if tomdoc.yields
+      yard.create_tag(:yield, tomdoc.yields) if tomdoc.yields
 
-      create_tag(:deprecated) if tomdoc.deprecated?
+      yard.create_tag(:deprecated, 'Do not use this in new code, and replace it when updating old code.') if tomdoc.deprecated?
 
-      create_tag(:private) if tomdoc.internal?
+      yard.create_tag(:api, 'public')  if tomdoc.public?
+      yard.create_tag(:api, 'private') if tomdoc.internal?
 
-      # notice we return the modified comment
-      tomdoc.description.to_s
+      tomdoc
     end
   end
 
+  if VERSION > '0.8'
+    require 'yard-tomdoc/yard081'
+  elsif VERSION == '0.8'
+    require 'yard-tomdoc/yard080'
+  else
+    require 'yard-tomdoc/yard070'
+  end
+
 end

data/lib/yard-tomdoc.yml

@@ -15,6 +15,7 @@ copyrights:
 requirements:
 - name: yard
 - name: tomparse
+- name: rc
 - name: detroit
   groups:
   - build
@@ -32,17 +33,27 @@ alternatives: []
 conflicts: []
 repositories: []
 resources:
-  home: http://rubyworks.github.com/yard-tomdoc
-  code: http://github.com/rubyworks/yard-tomdoc
-  bugs: http://github.com/rubyworks/yard-tomdoc/issues
-  docs: http://rubydoc.info/gems/yard-tomdoc/frames
+- uri: http://rubyworks.github.com/yard-tomdoc
+  label: Website
+  type: home
+- uri: http://github.com/rubyworks/yard-tomdoc
+  label: Source Code
+  type: code
+- uri: http://github.com/rubyworks/yard-tomdoc/issues
+  label: Issue Tracker
+  type: bugs
+- uri: http://rubydoc.info/gems/yard-tomdoc/frames
+  label: Documentation
+  type: docs
+categories: []
 extra: {}
 load_path:
 - lib
 revision: 0
 name: yard-tomdoc
 title: YARD TomDoc
-version: 0.4.0
+version: 0.5.0
 summary: TomDoc for YARD
 description: Use TomDoc documentation format with YARD.
-date: '2012-03-04'
+webcvs: https://github.com/rubyworks/yard-tomdoc/tree/master
+date: '2012-06-14'

data/lib/yard-tomdoc/yard070.rb

@@ -0,0 +1,13 @@
+module YARD
+
+  class Docstring
+    def parse_comments(comments)
+      comment = [comments].flatten.join("\n")
+      tomdoc  = TomDoc.yard_parse(self, comment)
+      tomdoc.description.to_s  # return the modified comment
+    end
+
+    public :create_tag
+  end
+
+end

data/lib/yard-tomdoc/yard080.rb

@@ -0,0 +1,32 @@
+module YARD
+
+  class DocstringParser
+    def parse(content, object = nil, handler = nil)
+      @object = object
+      @handler = handler
+      @raw_text = content
+
+      if object
+        text = parse_tomdoc(content)
+      else        
+        text = parse_content(content)
+      end
+
+      # Remove trailing/leading whitespace / newlines
+      @text = text.gsub(/\A[\r\n\s]+|[\r\n\s]+\Z/, '')
+      call_directives_after_parse
+      call_after_parse_callbacks
+
+      self
+    end
+
+    #
+    def parse_tomdoc(content)
+      tomdoc = TomDoc.yard_parse(self, content)
+      tomdoc.description.to_s
+    end
+
+    public :create_tag
+  end
+
+end

data/lib/yard-tomdoc/yard081.rb

@@ -0,0 +1,25 @@
+module YARD
+
+  # Plugin parser for parsing TomDoc formatted comments.
+  #
+  class TomDocParser < DocstringParser
+
+    #
+    def parse_content(content)
+      # TODO: move TomDoc.yard_parse code to here when old versions are no longer supported
+      tomdoc = TomDoc.yard_parse(self, content)
+      text   = tomdoc.description.to_s
+
+      # Remove trailing/leading whitespace / newlines
+      @text = text.gsub(/\A[\r\n\s]+|[\r\n\s]+\Z/, '')
+    end
+
+    public :create_tag
+  end
+
+  # Set the parser as default when parsing
+  YARD::Docstring.default_parser = TomDocParser
+
+  # TODO: what about reset callbacks ?
+end
+

data/test/unit/test_docstring.rb

@@ -5,8 +5,16 @@ require "yard-tomdoc"
 
 describe YARD::Docstring do
 
+  make_docstring = Proc.new do |comment|
+    if YARD::VERSION == '0.8.0'
+      YARD::DocstringParser.new.parse(comment, self).to_docstring
+    else
+      YARD::Docstring.new(comment)
+    end
+  end
+
   before do
-    @docstring = YARD::Docstring.new <<-eof
+    comment = <<-eof
 # Duplicate some text an arbitrary number of times.
 # 
 # text  - The String to be duplicated.
@@ -20,6 +28,8 @@ describe YARD::Docstring do
 #
 # Raises ArgumentError if something bad happened
 eof
+
+    @docstring = make_docstring[comment]
   end
 
   it "should fill docstring with description" do
@@ -32,10 +42,10 @@ eof
     tags[0].name.assert == 'text'
     tags[1].name.assert == 'count'
   end
-  
+
   it "should fill examples tags" do
     @docstring.tags(:example).size.assert == 1
-    @docstring.tag(:example).text.assert == "multiplex('Tom', 4)\n  # => 'TomTomTomTom'"
+    @docstring.tag(:example).text.assert == "multiplex('Tom', 4)\n# => 'TomTomTomTom'"
   end
   
   it "should fill return tag" do
@@ -45,4 +55,24 @@ eof
   it "should fill raise tag" do
     @docstring.tag(:raise).text.assert == "ArgumentError if something bad happened"
   end
+
+  describe "Internal description" do
+
+    it "should fill api private tag" do
+      docstring = make_docstring["# Internal: It will do a big things in future"]
+      docstring.tag(:api).text.assert == "private"
+    end
+
+  end
+
+  describe "Deprecated description" do
+
+    it "should fill deprecated tag" do
+      docstring = make_docstring["# Deprecated: Some description."]
+      docstring.tag(:deprecated).text.assert == "Do not use this in new code, and replace it when updating old code."
+    end
+
+  end
+
 end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-tomdoc
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-08 00:00:00.000000000 Z
+date: 2012-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &18163280 !ruby/object:Gem::Requirement
+  requirement: &22873120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *18163280
+  version_requirements: *22873120
 - !ruby/object:Gem::Dependency
   name: tomparse
-  requirement: &18162760 !ruby/object:Gem::Requirement
+  requirement: &22872480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,10 +33,21 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *18162760
+  version_requirements: *22872480
+- !ruby/object:Gem::Dependency
+  name: rc
+  requirement: &22871820 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *22871820
 - !ruby/object:Gem::Dependency
   name: detroit
-  requirement: &18162260 !ruby/object:Gem::Requirement
+  requirement: &22871280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +55,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *18162260
+  version_requirements: *22871280
 - !ruby/object:Gem::Dependency
   name: spectroscope
-  requirement: &18161760 !ruby/object:Gem::Requirement
+  requirement: &22870680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,10 +66,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *18161760
+  version_requirements: *22870680
 - !ruby/object:Gem::Dependency
   name: ae
-  requirement: &18161260 !ruby/object:Gem::Requirement
+  requirement: &22870080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -66,7 +77,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *18161260
+  version_requirements: *22870080
 description: Use TomDoc documentation format with YARD.
 email:
 - transfire@gmail.com
@@ -77,6 +88,9 @@ extra_rdoc_files:
 - HISTORY.md
 - README.md
 files:
+- lib/yard-tomdoc/yard070.rb
+- lib/yard-tomdoc/yard080.rb
+- lib/yard-tomdoc/yard081.rb
 - lib/yard-tomdoc.rb
 - lib/yard-tomdoc.yml
 - test/helper.rb
@@ -87,6 +101,7 @@ files:
 - LICENSE.txt
 - HISTORY.md
 - README.md
+- Config.rb
 homepage: http://rubyworks.github.com/yard-tomdoc
 licenses:
 - MIT