yard-tomdoc 0.5.0 → 0.6.0

data/.index

@@ -0,0 +1,62 @@
+---
+revision: 2013
+type: ruby
+sources:
+- INDEX.yml
+authors:
+- name: Trans
+  email: transfire@gmail.com
+- name: Loren Segal
+organizations: []
+requirements:
+- name: yard
+- version: 0.3.0+
+  name: tomparse
+- name: rc
+- groups:
+  - build
+  development: true
+  name: detroit
+- groups:
+  - test
+  development: true
+  name: spectroscope
+- groups:
+  - test
+  development: true
+  name: ae
+conflicts: []
+alternatives: []
+resources:
+- type: home
+  uri: http://rubyworks.github.com/yard-tomdoc
+  label: Homepage
+- type: code
+  uri: http://github.com/rubyworks/yard-tomdoc
+  label: Source Code
+- type: bugs
+  uri: http://github.com/rubyworks/yard-tomdoc/issues
+  label: Issue Tracker
+- type: docs
+  uri: http://rubydoc.info/gems/yard-tomdoc/frames
+  label: Documentation
+repositories: []
+categories: []
+copyrights:
+- holder: Rubyworks
+  year: '2012'
+  license: MIT
+- holder: Loren Segal
+  year: '2010'
+  license: MIT
+customs: []
+paths:
+  lib:
+  - lib
+version: 0.6.0
+name: yard-tomdoc
+title: YARD TomDoc
+summary: TomDoc for YARD
+description: Use TomDoc documentation format with YARD.
+webcvs: https://github.com/rubyworks/yard-tomdoc/tree/master
+date: '2013-01-22'

data/.rubyrc

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+
+config 'rubytest' do |run|
+  require 'spectroscope'
+  require 'ae'
+
+  $:.unshift 'lib'
+  $:.unshift 'test'
+
+  run.files << 'test/**/test_*.rb'
+end
+
+config 'rubytest', :profile=>:cov do |run|
+  require 'spectroscope'
+  require 'ae'
+  require 'simplecov'
+
+  $:.unshift 'lib'
+  $:.unshift 'test'
+
+  run.files << 'test/**/test_*.rb'
+
+  dir = $properties.coverage_folder
+
+  SimpleCov.command_name 'Ruby Tests'
+
+  SimpleCov.start do
+    coverage_dir(dir || 'log/coverage')
+    #add_group "Label", "lib/qed/directory"
+  end
+end
+

data/.yardopts

@@ -0,0 +1,9 @@
+--title "YARD TomDoc"
+--readme README.md
+--protected
+--private
+--plugin tomdoc
+lib
+-
+*.md
+*.txt

data/HISTORY.md

@@ -1,5 +1,18 @@
 # RELEASE HISTORY
 
+## 0.6.0 / 2013-01-22
+
+This new major release adds support for most YARD tags thanks to TomParse's
+new support of tag markers. It also fixes a few annoying bugs, such a
+options parsing and multi-line paragraph descriptions.
+
+Changes:
+
+* Add support for most YARD tags.
+* Fix support for option hashes.
+* Fix support for multi-paragraph descriptions.
+
+
 ## 0.5.0 / 2012-06-14
 
 Version 0.8.0 of YARD broke the yard-tomdoc plugin. After some discussion with

data/LICENSE.txt

@@ -1,6 +1,4 @@
-YARD::TomDoc - Use TomDoc with YARD
-
-Copyright (c) 2010 Loren Segal, Thomas Sawyer  (MIT License)
+(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

data/README.md

@@ -5,6 +5,7 @@
 [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)
+[![Gem Version](https://badge.fury.io/rb/yard-tomdoc.png)](http://badge.fury.io/rb/yard-tomdoc)
 
 
 ## Description
@@ -37,11 +38,18 @@ Before you use yard-tomdoc you should read about the differences between YARD
 and TomDoc syntax [here](http://gnuu.org/2010/05/12/whats-missing-from-tomdoc/).
 
 
+## Acknowledgements
+
+Huge thanks to Loren Segal, the creator of YARD and the original author of this plugin.
+Without his patient assistance and coding genius, this library would not have been possible.
+
+
 ## Licensing
 
-Copyright (c) 2010 Loren Segal, Thomas Sawyer
+Yard::TomDoc is copyrighted open-source software.
 
-YARD::TomDoc is distributable in accordance with the ters of the **MIT** licsnse.
+Copyright (c) 2010 Rubyworks. All rights reserved.
 
-See the `LICENSE.txt` file for details.
+YARD::TomDoc can be modified and redistributed in accordance with the ters of the **MIT** licsnse.
 
+See the `LICENSE.txt` file for details.

data/lib/yard-tomdoc.rb

@@ -3,24 +3,11 @@ 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
+    # Distribution name of this program.
+    NAME = 'yard-tomdoc'
 
-    # 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
+    # Tags supported by YARD that Tomparse can handle.
+    TAGS = %w{abstract attr attr_reader attr_writer attribute author deprecated note see since todo version}
 
     # Parse comments with TomDoc and then provide YARD with results. 
     #
@@ -37,16 +24,16 @@ module YARD
       # 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|
-          yard.create_tag(:option, "#{last_argument.name} #{opt.description}")
+      tomdoc.arguments.each do |arg|
+        arg.options.each do |opt|
+          yard.create_tag(:option, "#{arg.name} #{opt.name} #{opt.description}")
         end
       end
 
       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
+        # 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
@@ -64,8 +51,49 @@ module YARD
       yard.create_tag(:api, 'public')  if tomdoc.public?
       yard.create_tag(:api, 'private') if tomdoc.internal?
 
+      tomdoc.tags.each do |label, desc|
+        if TAGS.include?(label.to_s)
+          yard.create_tag(label.to_sym, desc.to_s)
+        end
+      end
+
       tomdoc
     end
+
+    #
+    def self.const_missing(name)
+      metadata[name.to_s.downcase] || super(name)
+    end
+
+    # TODO: The #to_s on the gemspec return value is a bit too simplistic. But how to fix?
+    #       The goal is reduce the value to a basic type (String, Hash, Array, Numeric).
+
+    # When a constant is missing, see if it is a metadata entry.
+    # Metadata comes from the RubyGem, and fallsback to project index file.
+    #
+    # name - [Symbol] constant name
+    #
+    # Returns metadata value.
+    def self.const_missing(const_name)
+      name = const_name.to_s.downcase
+      #begin
+      #  Gem.loaded_specs[NAME].send(name).to_s
+      #rescue StandardError
+        index[name] || super(const_name)
+      #end
+    end
+
+    # Metadata from the `yard-tomdoc.yml` or `.index` file.
+    # 
+    # Returns [Hash] of metadata.
+    def self.index
+      @index ||= (
+        require 'yaml'
+        dir  = File.dirname(__FILE__)
+        file = Dir[File.join(dir, "{#{NAME}.yml,../.index}")].first
+        file ? YAML.load_file(file) : {}
+      )
+    end
   end
 
   if VERSION > '0.8'
@@ -75,5 +103,4 @@ module YARD
   else
     require 'yard-tomdoc/yard070'
   end
-
 end

data/lib/yard-tomdoc.yml

@@ -1,59 +1,62 @@
 ---
-source:
-- Profile
+revision: 2013
+type: ruby
+sources:
+- INDEX.yml
 authors:
 - name: Trans
   email: transfire@gmail.com
 - name: Loren Segal
-copyrights:
-- holder: Rubyworks
-  year: '2012'
-  license: MIT
-- holder: Loren Segal
-  year: '2010'
-  license: MIT
+organizations: []
 requirements:
 - name: yard
-- name: tomparse
+- version: 0.3.0+
+  name: tomparse
 - name: rc
-- name: detroit
-  groups:
+- groups:
   - build
   development: true
-- name: spectroscope
-  groups:
+  name: detroit
+- groups:
   - test
   development: true
-- name: ae
-  groups:
+  name: spectroscope
+- groups:
   - test
   development: true
-dependencies: []
-alternatives: []
+  name: ae
 conflicts: []
-repositories: []
+alternatives: []
 resources:
-- uri: http://rubyworks.github.com/yard-tomdoc
-  label: Website
-  type: home
-- uri: http://github.com/rubyworks/yard-tomdoc
+- type: home
+  uri: http://rubyworks.github.com/yard-tomdoc
+  label: Homepage
+- type: code
+  uri: http://github.com/rubyworks/yard-tomdoc
   label: Source Code
-  type: code
-- uri: http://github.com/rubyworks/yard-tomdoc/issues
+- type: bugs
+  uri: http://github.com/rubyworks/yard-tomdoc/issues
   label: Issue Tracker
-  type: bugs
-- uri: http://rubydoc.info/gems/yard-tomdoc/frames
+- type: docs
+  uri: http://rubydoc.info/gems/yard-tomdoc/frames
   label: Documentation
-  type: docs
+repositories: []
 categories: []
-extra: {}
-load_path:
-- lib
-revision: 0
+copyrights:
+- holder: Rubyworks
+  year: '2012'
+  license: MIT
+- holder: Loren Segal
+  year: '2010'
+  license: MIT
+customs: []
+paths:
+  lib:
+  - lib
+version: 0.6.0
 name: yard-tomdoc
 title: YARD TomDoc
-version: 0.5.0
 summary: TomDoc for YARD
 description: Use TomDoc documentation format with YARD.
 webcvs: https://github.com/rubyworks/yard-tomdoc/tree/master
-date: '2012-06-14'
+date: '2013-01-22'

data/test/unit/test_docstring.rb

@@ -19,6 +19,9 @@ describe YARD::Docstring do
 # 
 # text  - The String to be duplicated.
 # count - The Integer number of times to duplicate the text.
+# options - Options (default: {})
+#         :a - Option a
+#         :b - Option b
 # 
 # Examples
 #   multiplex('Tom', 4)
@@ -38,9 +41,21 @@ eof
 
   it "should fill param tags" do
     tags = @docstring.tags(:param)
-    tags.size.assert == 2
+    tags.size.assert == 3
     tags[0].name.assert == 'text'
     tags[1].name.assert == 'count'
+    tags[2].name.assert == 'options'
+  end
+
+  it "should fill options tags" do
+    tags = @docstring.tags(:option)
+    tags.size.assert == 2
+    tags[0].name.assert == 'options'
+    tags[0].pair.name.assert == ':a'
+    tags[0].pair.text.assert == 'Option a'
+    tags[1].name.assert == 'options'
+    tags[1].pair.name.assert == ':b'
+    tags[1].pair.text.assert == 'Option b'
   end
 
   it "should fill examples tags" do

data/test/unit/test_tags.rb

@@ -0,0 +1,101 @@
+require 'helper.rb'
+
+require "yard"
+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
+    comment = <<-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.
+# options - Options (default: {})
+#         :a - Option a
+#         :b - Option b
+# 
+# Examples
+#   multiplex('Tom', 4)
+#   # => 'TomTomTomTom'
+#
+# TODO: There something important to be done!
+#
+# Returns the duplicated String.
+#
+# Raises ArgumentError if something bad happened
+eof
+
+    @docstring = make_docstring[comment]
+  end
+
+  it "should fill todo tags" do
+    tags = @docstring.tags(:todo)
+    tags.size.assert == 1
+    tags[0].text.assert == 'There something important to be done!'
+  end
+
+  it "should fill docstring with description" do
+    @docstring.assert == "Duplicate some text an arbitrary number of times."
+  end
+
+  it "should fill param tags" do
+    tags = @docstring.tags(:param)
+    tags.size.assert == 3
+    tags[0].name.assert == 'text'
+    tags[1].name.assert == 'count'
+    tags[2].name.assert == 'options'
+  end
+
+  it "should fill options tags" do
+    tags = @docstring.tags(:option)
+    tags.size.assert == 2
+    tags[0].name.assert == 'options'
+    tags[0].pair.name.assert == ':a'
+    tags[0].pair.text.assert == 'Option a'
+    tags[1].name.assert == 'options'
+    tags[1].pair.name.assert == ':b'
+    tags[1].pair.text.assert == 'Option b'
+  end
+
+  it "should fill examples tags" do
+    @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.assert == "the duplicated String."
+  end
+
+  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.5.0
+  version: 0.6.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-14 00:00:00.000000000 Z
+date: 2013-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &22873120 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,21 +22,31 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *22873120
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: tomparse
-  requirement: &22872480 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.3.0
   type: :runtime
   prerelease: false
-  version_requirements: *22872480
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
   name: rc
-  requirement: &22871820 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +54,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *22871820
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: detroit
-  requirement: &22871280 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,10 +70,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *22871280
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: spectroscope
-  requirement: &22870680 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -66,10 +86,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *22870680
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: ae
-  requirement: &22870080 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -77,7 +102,12 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *22870080
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Use TomDoc documentation format with YARD.
 email:
 - transfire@gmail.com
@@ -88,6 +118,9 @@ extra_rdoc_files:
 - HISTORY.md
 - README.md
 files:
+- .index
+- .rubyrc
+- .yardopts
 - lib/yard-tomdoc/yard070.rb
 - lib/yard-tomdoc/yard080.rb
 - lib/yard-tomdoc/yard081.rb
@@ -98,10 +131,10 @@ files:
 - test/system/sample/lib/hello_world.rb
 - test/system/test_yardoc.rb
 - test/unit/test_docstring.rb
-- LICENSE.txt
+- test/unit/test_tags.rb
 - HISTORY.md
 - README.md
-- Config.rb
+- LICENSE.txt
 homepage: http://rubyworks.github.com/yard-tomdoc
 licenses:
 - MIT
@@ -124,8 +157,15 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.11
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: TomDoc for YARD
-test_files: []
+test_files:
+- test/system/test_yardoc.rb
+- test/system/sample/lib/example.rb
+- test/system/sample/lib/hello_world.rb
+- test/helper.rb
+- test/unit/test_docstring.rb
+- test/unit/test_tags.rb
+has_rdoc: 

data/Config.rb

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