yard-tomdoc 0.3.1 → 0.4.0

data/HISTORY.md

@@ -1,5 +1,19 @@
 # RELEASE HISTORY
 
+## 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
+and none of the other features than the tomdoc gem provides,
+so it is more suited to yard-tomdoc's needs. In addition,
+support for the latest TomDoc specification are included in
+this release.
+
+Changes:
+
+* Use tomparse gem for parsing TomDoc.
+* Improve support for TomDoc features.
+
 
 ## 0.3.1 | 2011-11-10
 
@@ -47,3 +61,4 @@ Changes:
 * Depend on `tomdoc` library.
 * Support YARD's method return object.
 * Fix args issues when missing section.
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+YARD::TomDoc - Use TomDoc with YARD
+
+Copyright (c) 2010 Loren Segal, Thomas Sawyer  (MIT License)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/README.md

@@ -1,11 +1,10 @@
-# yard-tomdoc
+# YARD::TomDoc
 
-| Author:    | Thomas Sawyer <transfire@gmail.com>      |
-|------------|------------------------------------------------|
-| Copyright: | (c) 2010 Loren Segal, Thomas Sawyer            |
-| Home:      | http://rubyworks.github.com/yard-tomdoc        |
-| Issues:    | http://github.com/rubyworks/yard-tomdoc/issues |
-| Status:    | [![Build Status](https://secure.travis-ci.org/rubyworks/yard-tomdoc.png)](http://travis-ci.org/rubyworks/yard-tomdoc) |
+[Website](http://rubyworks.github.com/yard-tomdoc) /
+[Development](http://github.com/rubyworks/yard-tomdoc) /
+[Issues](http://github.com/rubyworks/yard-tomdoc/issues)
+
+[![Build Status](https://secure.travis-ci.org/rubyworks/yard-tomdoc.png)](http://travis-ci.org/rubyworks/yard-tomdoc)
 
 
 ## Description
@@ -13,7 +12,7 @@
 Implements [TomDoc](http://tomdoc.org) syntax for YARD. 'Nuff said.
 
 
-## Usage
+## Instruction
 
 Since `yard-tomdoc` is a standard YARD plugin, utilize it with yard's
 `--plugin` option.
@@ -31,5 +30,7 @@ and TomDoc syntax [here](http://gnuu.org/2010/05/12/whats-missing-from-tomdoc/).
 
 Copyright (c) 2010 Loren Segal, Thomas Sawyer
 
-See the `NOTICE` file for license information on TomDoc.
+YARD::TomDoc is distributable in accordance with the ters of the **MIT** licsnse.
+
+See the `LICENSE.txt` file for details.
 

data/lib/yard-tomdoc.rb

@@ -1,6 +1,71 @@
-begin
-  require 'tomdoc/tomdoc'
-rescue LoadError
-  require 'yard-tomdoc/tomdoc'
+require 'tomparse'
+
+module YARD
+
+  module TomDoc
+    # Metadata from the project's `yard-tomdoc.yml` fle.
+    # 
+    # Returns [Hash] of metadata.
+    def self.metadata
+      @metadata ||= (
+        require 'yaml'
+        YAML.load_file(File.dirname(__FILE__) + '/yard-tomdoc.yml')
+      )
+    end
+
+    # When a constant is missing, see if it is a metadata entry.
+    #
+    # name - [Symbol] constant name
+    #
+    # Returns metadata value.
+    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
+    #
+    # Returns [String] parsed comments description
+    def parse_comments(comments)
+      comment = [comments].flatten.join("\n")
+
+      tomdoc = TomParse.parse(comment)
+
+      tomdoc.examples.each {|ex| create_tag(:example, "\n" + ex) }
+
+      tomdoc.arguments.each {|arg| 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}")
+        end
+      end
+
+      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
+
+      create_tag(:yield, tomdoc.yields) if tomdoc.yields
+
+      create_tag(:deprecated) if tomdoc.deprecated?
+
+      create_tag(:private) if tomdoc.internal?
+
+      # notice we return the modified comment
+      tomdoc.description.to_s
+    end
+  end
+
 end
-require 'yard-tomdoc/yard'

data/lib/yard-tomdoc.yml

@@ -0,0 +1,48 @@
+---
+source:
+- Profile
+authors:
+- name: Trans
+  email: transfire@gmail.com
+- name: Loren Segal
+copyrights:
+- holder: Rubyworks
+  year: '2012'
+  license: MIT
+- holder: Loren Segal
+  year: '2010'
+  license: MIT
+requirements:
+- name: yard
+- name: tomparse
+- name: detroit
+  groups:
+  - build
+  development: true
+- name: spectroscope
+  groups:
+  - test
+  development: true
+- name: ae
+  groups:
+  - test
+  development: true
+dependencies: []
+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
+extra: {}
+load_path:
+- lib
+revision: 0
+name: yard-tomdoc
+title: YARD TomDoc
+version: 0.4.0
+summary: TomDoc for YARD
+description: Use TomDoc documentation format with YARD.
+date: '2012-03-04'

data/test/helper.rb

@@ -1,6 +1,2 @@
-$:.unshift File.expand_path(File.dirname(__FILE__)) + "/../lib"
-
 require 'fileutils'
-require 'minitest/spec'
-require 'minitest/autorun'
 

data/test/system/test_yardoc.rb

@@ -1,7 +1,7 @@
 dir = File.expand_path(File.dirname(__FILE__))
-tmp = dir + '/../../tmp'
+tmp = File.expand_path(dir + '/../../tmp')
 
-require dir + "/../helper.rb"
+require "helper"
 
 # This test is design to run `yard doc` on the sample project and
 # check to make sure it was produced successufully.
@@ -28,3 +28,4 @@ describe "yard doc" do
   end
 
 end
+

data/test/unit/test_docstring.rb

@@ -1,10 +1,7 @@
-require File.expand_path(File.dirname(__FILE__)) + "/../helper.rb"
+require 'helper.rb'
 
 require "yard"
-#require "yard-tomdoc"
-
-# TODO: make separate test for this
-require "yard-tomdoc-intern"
+require "yard-tomdoc"
 
 describe YARD::Docstring do
 
@@ -26,26 +23,26 @@ eof
   end
 
   it "should fill docstring with description" do
-    @docstring.must_equal "Duplicate some text an arbitrary number of times."
+    @docstring.assert == "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'
+    tags.size.assert == 2
+    tags[0].name.assert == 'text'
+    tags[1].name.assert == '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'"
+    @docstring.tags(:example).size.assert == 1
+    @docstring.tag(:example).text.assert == "multiplex('Tom', 4)\n  # => 'TomTomTomTom'"
   end
   
   it "should fill return tag" do
-    @docstring.tag(:return).text.must_equal "the duplicated String."
+    @docstring.tag(:return).text.assert == "the duplicated String."
   end
 
   it "should fill raise tag" do
-    @docstring.tag(:raise).text.must_equal "ArgumentError if something bad happened"
+    @docstring.tag(:raise).text.assert == "ArgumentError if something bad happened"
   end
 end

metadata

@@ -1,20 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: yard-tomdoc
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
-- Thomas Sawyer
+- Trans
 - Loren Segal
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-04 00:00:00.000000000 Z
+date: 2012-03-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &30272280 !ruby/object:Gem::Requirement
+  requirement: &18163280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,21 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *30272280
+  version_requirements: *18163280
+- !ruby/object:Gem::Dependency
+  name: tomparse
+  requirement: &18162760 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *18162760
 - !ruby/object:Gem::Dependency
   name: detroit
-  requirement: &30271760 !ruby/object:Gem::Requirement
+  requirement: &18162260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,10 +44,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *30271760
+  version_requirements: *18162260
 - !ruby/object:Gem::Dependency
-  name: rake
-  requirement: &30271260 !ruby/object:Gem::Requirement
+  name: spectroscope
+  requirement: &18161760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +55,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *30271260
+  version_requirements: *18161760
 - !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: &30270760 !ruby/object:Gem::Requirement
+  name: ae
+  requirement: &18161260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,34 +66,31 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *30270760
+  version_requirements: *18161260
 description: Use TomDoc documentation format with YARD.
 email:
 - transfire@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files:
+- LICENSE.txt
 - HISTORY.md
 - README.md
-- NOTICE.md
 files:
-- lib/yard-tomdoc/arg.rb
-- lib/yard-tomdoc/tomdoc.rb
-- lib/yard-tomdoc/version.rb
-- lib/yard-tomdoc/yard.rb
-- lib/yard-tomdoc-intern.rb
 - lib/yard-tomdoc.rb
+- lib/yard-tomdoc.yml
 - test/helper.rb
 - test/system/sample/lib/example.rb
 - test/system/sample/lib/hello_world.rb
 - test/system/test_yardoc.rb
 - test/unit/test_docstring.rb
+- LICENSE.txt
 - HISTORY.md
 - README.md
-- NOTICE.md
 homepage: http://rubyworks.github.com/yard-tomdoc
 licenses:
 - MIT
+- MIT
 post_install_message: 
 rdoc_options: []
 require_paths:

data/NOTICE.md

@@ -1,37 +0,0 @@
-# COPYRIGHT NOTICES
-
-
-## YARD Tomdoc 
-
-**Copyright (c) 2010 Loren Segal, Thomas Sawyer**
-
-Distributed under the terms of the MIT License (see below).
-
-
-## Tomdoc 
-
-**Copyright (c) 2010 Tom Preston-Werner, Chris Wanstrath**
-
-Distributed under the terms of the MIT License (see below).
-
-
-## The MIT License
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in
-    all copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-    THE SOFTWARE.
-

data/lib/yard-tomdoc-intern.rb

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

data/lib/yard-tomdoc/arg.rb

@@ -1,22 +0,0 @@
-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,166 +0,0 @@
-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.
-    #
-    # doc - document string
-    #
-    def initialize(doc)
-      @doc = doc
-    end
-
-    # Provide access to document string.
-    #
-    # Returns [String] documentation string.
-    def message
-      @doc
-    end
-
-    # Provide access to document string.
-    #
-    # Returns [String] documentation string.
-    def to_s
-      @doc
-    end
-  end
-
-  # Model a TomDoc comment.
-  class TomDoc
-    attr_accessor :raw
-
-    def initialize(text)
-      @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.")
-      end
-
-      if tomdoc.split("\n\n").size < 2
-        raise InvalidTomDoc.new("No description section found.")
-      end
-
-      true
-    end
-
-    # Returns [String] cleansed comment text.
-    def tomdoc
-      #raw
-      clean = raw.split("\n").map do |line|
-        line =~ /^(\s*# ?)/ ? line.sub($1, '') : nil
-      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
-
-      return args unless sections[1]
-
-      sections[1].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
-
-        last_indent = indent
-      end
-
-      args
-    end
-
-    # Returns [Array] list of examples.
-    def examples
-      if tomdoc =~ /(\s*Examples\s*(.+?)\s*(?:Returns|Raises))/m
-        $2.split("\n\n")
-      else
-        []
-      end
-    end
-
-    # Returns [Array] list of possible returns.
-    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
-        end
-
-        statements
-      else
-        []
-      end
-    end
-
-    # Returns [Array] list of possible errors that could be raised.
-    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
-        end
-
-        statements
-      else
-        []
-      end
-    end
-  end
-end

data/lib/yard-tomdoc/version.rb

@@ -1,6 +0,0 @@
-module YARD
-  module TomDoc
-    VERSION = "0.3.1"
-  end
-end
-

data/lib/yard-tomdoc/yard.rb

@@ -1,39 +0,0 @@
-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
-