yard-tomdoc 0.2.0

data/HISTORY.md

@@ -0,0 +1,13 @@
+# RELEASE HISTORY
+
+## 0.2.0 | 2011-05-22
+
+This is first packaged release of YARD-TomDoc. Some minor
+improvements have been made from the original version and
+the project now actually depends on the `tomdoc` library.
+
+Changes:
+
+* Depend on `tomdoc` library.
+* Support YARD's method return object.
+* Fix args issues when missing section.

data/MIT.txt

@@ -0,0 +1,20 @@
+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/NOTICE.md

@@ -0,0 +1,17 @@
+COPYRIGHT NOTICES
+=================
+
+Yard TomDoc
+-----------
+
+Copyright (c) 2010 Loren Segal, Thomas Sawyer
+
+Distributed under the terms of the MIT License (see MIT.txt).
+
+
+TomDoc
+------
+
+Copyright (c) 2010 Tom Preston-Werner, Chris Wanstrath
+
+Distributed under the terms of the MIT License (see MIT.txt).

data/README.md

@@ -0,0 +1,28 @@
+# yard-tomdoc
+
+
+## Description
+
+Implements [TomDoc](http://tomdoc.org) syntax for YARD. 'Nuff said.
+
+
+## Usage
+
+Since `yard-tomdoc` is a standard YARD plugin, utilize it with yard's
+`--plugin` option.
+
+    $ yard --plugin yard-tomdoc [...]
+
+
+## Limitations
+
+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/).
+
+
+## Licensing
+
+Copyright (c) 2010 Loren Segal, Thomas Sawyer
+
+See the `NOTICE` file for license information on TomDoc.
+

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/yard-tomdoc.rb

@@ -0,0 +1,42 @@
+#require File.dirname(__FILE__) + "/yard-tomdoc/tomdoc"  #require 'tomdoc/tomdoc'
+require '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
+
+end
+

data/lib/yard-tomdoc/tomdoc.rb

@@ -0,0 +1,164 @@
+#require 'yard'
+
+module TomDoc
+  class InvalidTomDoc < RuntimeError
+    # Create new InvalidTomDoc object.
+    #
+    # doc - document string
+    #
+    def initialize(doc)
+      @doc = doc
+    end
+
+    # Provide access to document string.
+    #
+    # Returns String.
+    def message
+      @doc
+    end
+
+    # Provide access to document string.
+    #
+    # Returns 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
+
+  class TomDoc
+    attr_accessor :raw
+
+    def initialize(text)
+      @raw = text.to_s.strip
+    end
+
+    def to_s
+      @raw
+    end
+
+    def self.valid?(text)
+      new(text).valid?
+    end
+
+    def valid?
+      validate
+    rescue InvalidTomDoc
+      false
+    end
+
+    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
+
+    def tomdoc
+      raw
+    end
+
+    def sections
+      tomdoc.split("\n\n")
+    end
+
+    def description
+      sections.first
+    end
+
+    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
+
+    def examples
+      if tomdoc =~ /(\s*Examples\s*(.+?)\s*(?:Returns|Raises))/m
+        $2.split("\n\n")
+      else
+        []
+      end
+    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
+        end
+
+        statements
+      else
+        []
+      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
+        end
+
+        statements
+      else
+        []
+      end
+    end
+  end
+end

data/test/case_docstring.rb

@@ -0,0 +1,48 @@
+$:.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

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification 
+name: yard-tomdoc
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
+platform: ruby
+authors: 
+- Loren Segal
+- Thomas Sawyer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-05-22 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: tomdoc
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 0
+        - 2
+        - 0
+        version: 0.2.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: ko
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: redline
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: Implements [TomDoc](http://tomdoc.org) syntax for YARD. 'Nuff said.
+email: transfire@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- lib/.yardoc/checksums
+- lib/.yardoc/objects/root.dat
+- lib/.yardoc/proxy_types
+- lib/yard-tomdoc/tomdoc.rb
+- lib/yard-tomdoc.rb
+- test/case_docstring.rb
+- HISTORY.md
+- README.md
+- VERSION
+- MIT.txt
+- NOTICE.md
+homepage: http://rubyworks.github.com/yard-tomdoc
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: 
+- --title
+- YARD-TomDoc API
+- --main
+- README.md
+require_paths: 
+- lib
+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 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: yard-tomdoc
+rubygems_version: 1.8.2
+signing_key: 
+specification_version: 3
+summary: TomDoc for YARD
+test_files: []
+