yard-tomdoc 0.2.1 → 0.3.0
Sign up to get free protection for your applications and to get access to all the features.
- data/HISTORY.md +11 -0
- data/lib/yard-tomdoc/arg.rb +22 -0
- data/lib/yard-tomdoc/tomdoc.rb +27 -25
- data/lib/yard-tomdoc/yard.rb +39 -0
- data/lib/yard-tomdoc-intern.rb +2 -0
- data/lib/yard-tomdoc.rb +5 -41
- data/test/test_docstring.rb +53 -0
- metadata +9 -7
- data/Version +0 -1
- data/test/case_docstring.rb +0 -48
data/HISTORY.md
CHANGED
@@ -1,5 +1,16 @@
|
|
1
1
|
# RELEASE HISTORY
|
2
2
|
|
3
|
+
## 0.3.0 | 2011-06-08
|
4
|
+
|
5
|
+
Okay,looks like tomdoc is ready to handle the dependency. If there
|
6
|
+
are any problems with this there is a fallback plugin, `tomdoc-intern`.
|
7
|
+
|
8
|
+
Changes:
|
9
|
+
|
10
|
+
* Depend on tomdoc proper.
|
11
|
+
* Add fallback `yard-tomdoc-intern.rb`
|
12
|
+
|
13
|
+
|
3
14
|
## 0.2.1 | 2011-05-23
|
4
15
|
|
5
16
|
There is an as-of-yet undetermined issue with running yard-tomdoc under
|
@@ -0,0 +1,22 @@
|
|
1
|
+
module TomDoc
|
2
|
+
class Arg
|
3
|
+
attr_accessor :name, :description
|
4
|
+
|
5
|
+
# Create new Arg object.
|
6
|
+
#
|
7
|
+
# name - name of argument
|
8
|
+
# description - arguments description
|
9
|
+
#
|
10
|
+
def initialize(name, description = '')
|
11
|
+
@name = name.to_s.intern
|
12
|
+
@description = description
|
13
|
+
end
|
14
|
+
|
15
|
+
# Is this an optional argument?
|
16
|
+
#
|
17
|
+
# Returns Boolean.
|
18
|
+
def optional?
|
19
|
+
@description.downcase.include? 'optional'
|
20
|
+
end
|
21
|
+
end
|
22
|
+
end
|
data/lib/yard-tomdoc/tomdoc.rb
CHANGED
@@ -1,6 +1,13 @@
|
|
1
|
-
#require 'yard'
|
2
|
-
|
3
1
|
module TomDoc
|
2
|
+
|
3
|
+
# TomDoc class needs Arg class.
|
4
|
+
if RUBY_VERSION > '1.9'
|
5
|
+
require_relative 'arg'
|
6
|
+
else
|
7
|
+
require 'yard-tomdoc/arg'
|
8
|
+
end
|
9
|
+
|
10
|
+
# This error is raised if comment is not valid TomDoc format.
|
4
11
|
class InvalidTomDoc < RuntimeError
|
5
12
|
# Create new InvalidTomDoc object.
|
6
13
|
#
|
@@ -12,40 +19,20 @@ module TomDoc
|
|
12
19
|
|
13
20
|
# Provide access to document string.
|
14
21
|
#
|
15
|
-
# Returns String.
|
22
|
+
# Returns [String] documentation string.
|
16
23
|
def message
|
17
24
|
@doc
|
18
25
|
end
|
19
26
|
|
20
27
|
# Provide access to document string.
|
21
28
|
#
|
22
|
-
# Returns String.
|
29
|
+
# Returns [String] documentation string.
|
23
30
|
def to_s
|
24
31
|
@doc
|
25
32
|
end
|
26
33
|
end
|
27
|
-
|
28
|
-
class Arg
|
29
|
-
attr_accessor :name, :description
|
30
|
-
|
31
|
-
# Create new Arg object.
|
32
|
-
#
|
33
|
-
# name - name of argument
|
34
|
-
# description - arguments description
|
35
|
-
#
|
36
|
-
def initialize(name, description = '')
|
37
|
-
@name = name.to_s.intern
|
38
|
-
@description = description
|
39
|
-
end
|
40
|
-
|
41
|
-
# Is this an optional argument?
|
42
|
-
#
|
43
|
-
# Returns Boolean.
|
44
|
-
def optional?
|
45
|
-
@description.downcase.include? 'optional'
|
46
|
-
end
|
47
|
-
end
|
48
34
|
|
35
|
+
# Model a TomDoc comment.
|
49
36
|
class TomDoc
|
50
37
|
attr_accessor :raw
|
51
38
|
|
@@ -53,20 +40,24 @@ module TomDoc
|
|
53
40
|
@raw = text.to_s.strip
|
54
41
|
end
|
55
42
|
|
43
|
+
# Returns [String] raw comment text.
|
56
44
|
def to_s
|
57
45
|
@raw
|
58
46
|
end
|
59
47
|
|
48
|
+
# Returns [Boolean] true if valid TomDoc comment.
|
60
49
|
def self.valid?(text)
|
61
50
|
new(text).valid?
|
62
51
|
end
|
63
52
|
|
53
|
+
# Returns [Boolean] true if valid TomDoc comment, otherwise false.
|
64
54
|
def valid?
|
65
55
|
validate
|
66
56
|
rescue InvalidTomDoc
|
67
57
|
false
|
68
58
|
end
|
69
59
|
|
60
|
+
# Returns [Boolean] true if validation doesn't raise an error.
|
70
61
|
def validate
|
71
62
|
if !raw.include?('Returns')
|
72
63
|
raise InvalidTomDoc.new("No `Returns' statement.")
|
@@ -79,18 +70,26 @@ module TomDoc
|
|
79
70
|
true
|
80
71
|
end
|
81
72
|
|
73
|
+
# Returns [String] cleansed comment text.
|
82
74
|
def tomdoc
|
83
75
|
raw
|
76
|
+
#clean = raw.split("\n").map do |line|
|
77
|
+
# line =~ /^(\s*# ?)/ ? line.sub($1, '') : line
|
78
|
+
#end.compact.join("\n")
|
79
|
+
#clean
|
84
80
|
end
|
85
81
|
|
82
|
+
# Returns [Array] document split into sections.
|
86
83
|
def sections
|
87
84
|
tomdoc.split("\n\n")
|
88
85
|
end
|
89
86
|
|
87
|
+
# Returns [String] first section.
|
90
88
|
def description
|
91
89
|
sections.first
|
92
90
|
end
|
93
91
|
|
92
|
+
# Returns [Array] list of arguments.
|
94
93
|
def args
|
95
94
|
args = []
|
96
95
|
last_indent = nil
|
@@ -114,6 +113,7 @@ module TomDoc
|
|
114
113
|
args
|
115
114
|
end
|
116
115
|
|
116
|
+
# Returns [Array] list of examples.
|
117
117
|
def examples
|
118
118
|
if tomdoc =~ /(\s*Examples\s*(.+?)\s*(?:Returns|Raises))/m
|
119
119
|
$2.split("\n\n")
|
@@ -122,6 +122,7 @@ module TomDoc
|
|
122
122
|
end
|
123
123
|
end
|
124
124
|
|
125
|
+
# Returns [Array] list of possible returns.
|
125
126
|
def returns
|
126
127
|
if tomdoc =~ /^\s*(Returns.+)/m
|
127
128
|
lines = $1.split("\n")
|
@@ -142,6 +143,7 @@ module TomDoc
|
|
142
143
|
end
|
143
144
|
end
|
144
145
|
|
146
|
+
# Returns [Array] list of possible errors that could be raised.
|
145
147
|
def raises
|
146
148
|
if tomdoc =~ /^\s*(Raises.+)/m
|
147
149
|
lines = $1.split("\n")
|
@@ -0,0 +1,39 @@
|
|
1
|
+
module YARD
|
2
|
+
|
3
|
+
class Docstring
|
4
|
+
|
5
|
+
# Parse comments with TomDoc and then provide YARD with results.
|
6
|
+
#
|
7
|
+
# comments - comment String
|
8
|
+
#
|
9
|
+
# Returns [String] of parsed comments description.
|
10
|
+
def parse_comments(comments)
|
11
|
+
comment = [comments].flatten.join("\n")
|
12
|
+
|
13
|
+
tomdoc = TomDoc::TomDoc.new(comment)
|
14
|
+
|
15
|
+
tomdoc.examples.each {|ex| create_tag(:example, "\n" + ex) }
|
16
|
+
|
17
|
+
tomdoc.args.each {|arg| create_tag(:param, "#{arg.name} #{arg.description}") }
|
18
|
+
|
19
|
+
tomdoc.raises.each {|r| create_tag(:raise, r.sub(/\ARaises\s+/, '')) }
|
20
|
+
|
21
|
+
tomdoc.returns.each do |r|
|
22
|
+
if md = /\AReturns\s+([A-Z].*?)\s+/.match(r)
|
23
|
+
klass = md[1]
|
24
|
+
desc = md.post_match
|
25
|
+
create_tag(:return, "[#{klass}] #{desc}")
|
26
|
+
else
|
27
|
+
desc = r.sub(/\AReturns\s+/, '')
|
28
|
+
create_tag(:return, desc)
|
29
|
+
end
|
30
|
+
end
|
31
|
+
|
32
|
+
# notice we return the modified comment
|
33
|
+
tomdoc.description.to_s
|
34
|
+
end
|
35
|
+
|
36
|
+
end
|
37
|
+
|
38
|
+
end
|
39
|
+
|
data/lib/yard-tomdoc.rb
CHANGED
@@ -1,42 +1,6 @@
|
|
1
|
-
|
2
|
-
require '
|
3
|
-
|
4
|
-
|
5
|
-
|
6
|
-
class Docstring
|
7
|
-
|
8
|
-
# Parse comments with TomDoc and then provide YARD with results.
|
9
|
-
#
|
10
|
-
# comments - comment String
|
11
|
-
#
|
12
|
-
# Returns a String of parsed comments description.
|
13
|
-
def parse_comments(comments)
|
14
|
-
comment = [comments].flatten.join("\n")
|
15
|
-
|
16
|
-
tomdoc = TomDoc::TomDoc.new(comment)
|
17
|
-
|
18
|
-
tomdoc.examples.each {|ex| create_tag(:example, "\n" + ex) }
|
19
|
-
|
20
|
-
tomdoc.args.each {|arg| create_tag(:param, "#{arg.name} #{arg.description}") }
|
21
|
-
|
22
|
-
tomdoc.raises.each {|r| create_tag(:raise, r.sub(/\ARaises\s+/, '')) }
|
23
|
-
|
24
|
-
tomdoc.returns.each do |r|
|
25
|
-
if md = /\AReturns\s+([A-Z].*?)\s+/.match(r)
|
26
|
-
klass = md[1]
|
27
|
-
desc = md.post_match
|
28
|
-
create_tag(:return, "[#{klass}] #{desc}")
|
29
|
-
else
|
30
|
-
desc = r.sub(/\AReturns\s+/, '')
|
31
|
-
create_tag(:return, desc)
|
32
|
-
end
|
33
|
-
end
|
34
|
-
|
35
|
-
# notice we return the modified comment
|
36
|
-
tomdoc.description.to_s
|
37
|
-
end
|
38
|
-
|
39
|
-
end
|
40
|
-
|
1
|
+
begin
|
2
|
+
require 'tomdoc/tomdoc'
|
3
|
+
rescue LoadError
|
4
|
+
require 'yard-tomdoc/tomdoc'
|
41
5
|
end
|
42
|
-
|
6
|
+
require 'yard-tomdoc/yard'
|
@@ -0,0 +1,53 @@
|
|
1
|
+
$:.unshift File.expand_path(File.dirname(__FILE__)) + "/../lib"
|
2
|
+
|
3
|
+
require 'minitest/autorun'
|
4
|
+
|
5
|
+
require "yard"
|
6
|
+
require "yard-tomdoc"
|
7
|
+
|
8
|
+
# TODO: make separate test for this
|
9
|
+
#require "yard-tomdoc-intern"
|
10
|
+
|
11
|
+
describe YARD::Docstring do
|
12
|
+
|
13
|
+
before do
|
14
|
+
@docstring = YARD::Docstring.new <<-eof
|
15
|
+
Duplicate some text an arbitrary number of times.
|
16
|
+
|
17
|
+
text - The String to be duplicated.
|
18
|
+
count - The Integer number of times to duplicate the text.
|
19
|
+
|
20
|
+
Examples
|
21
|
+
multiplex('Tom', 4)
|
22
|
+
# => 'TomTomTomTom'
|
23
|
+
|
24
|
+
Returns the duplicated String.
|
25
|
+
|
26
|
+
Raises ArgumentError if something bad happened
|
27
|
+
eof
|
28
|
+
end
|
29
|
+
|
30
|
+
it "should fill docstring with description" do
|
31
|
+
@docstring.must_equal "Duplicate some text an arbitrary number of times."
|
32
|
+
end
|
33
|
+
|
34
|
+
it "should fill param tags" do
|
35
|
+
tags = @docstring.tags(:param)
|
36
|
+
tags.size.must_equal 2
|
37
|
+
tags[0].name.must_equal 'text'
|
38
|
+
tags[1].name.must_equal 'count'
|
39
|
+
end
|
40
|
+
|
41
|
+
it "should fill examples tags" do
|
42
|
+
@docstring.tags(:example).size.must_equal 1
|
43
|
+
@docstring.tag(:example).text.must_equal "multiplex('Tom', 4)\n # => 'TomTomTomTom'"
|
44
|
+
end
|
45
|
+
|
46
|
+
it "should fill return tag" do
|
47
|
+
@docstring.tag(:return).text.must_equal "the duplicated String."
|
48
|
+
end
|
49
|
+
|
50
|
+
it "should fill raise tag" do
|
51
|
+
@docstring.tag(:raise).text.must_equal "ArgumentError if something bad happened"
|
52
|
+
end
|
53
|
+
end
|
metadata
CHANGED
@@ -1,13 +1,13 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: yard-tomdoc
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
hash:
|
4
|
+
hash: 19
|
5
5
|
prerelease:
|
6
6
|
segments:
|
7
7
|
- 0
|
8
|
-
-
|
9
|
-
-
|
10
|
-
version: 0.
|
8
|
+
- 3
|
9
|
+
- 0
|
10
|
+
version: 0.3.0
|
11
11
|
platform: ruby
|
12
12
|
authors:
|
13
13
|
- Loren Segal
|
@@ -16,7 +16,7 @@ autorequire:
|
|
16
16
|
bindir: bin
|
17
17
|
cert_chain: []
|
18
18
|
|
19
|
-
date: 2011-
|
19
|
+
date: 2011-06-08 00:00:00 Z
|
20
20
|
dependencies:
|
21
21
|
- !ruby/object:Gem::Dependency
|
22
22
|
name: ko
|
@@ -55,12 +55,14 @@ extensions: []
|
|
55
55
|
extra_rdoc_files:
|
56
56
|
- README.md
|
57
57
|
files:
|
58
|
+
- lib/yard-tomdoc/arg.rb
|
58
59
|
- lib/yard-tomdoc/tomdoc.rb
|
60
|
+
- lib/yard-tomdoc/yard.rb
|
61
|
+
- lib/yard-tomdoc-intern.rb
|
59
62
|
- lib/yard-tomdoc.rb
|
60
|
-
- test/
|
63
|
+
- test/test_docstring.rb
|
61
64
|
- HISTORY.md
|
62
65
|
- README.md
|
63
|
-
- Version
|
64
66
|
- MIT.txt
|
65
67
|
- NOTICE.md
|
66
68
|
homepage: http://rubyworks.github.com/yard-tomdoc
|
data/Version
DELETED
@@ -1 +0,0 @@
|
|
1
|
-
0.2.1
|
data/test/case_docstring.rb
DELETED
@@ -1,48 +0,0 @@
|
|
1
|
-
$:.unshift File.dirname(__FILE__) + "/../lib"
|
2
|
-
|
3
|
-
require "yard"
|
4
|
-
require "yard-tomdoc"
|
5
|
-
|
6
|
-
KO.case 'YARD::Docstring' do
|
7
|
-
|
8
|
-
setup do
|
9
|
-
@docstring = ::YARD::Docstring.new <<-eof
|
10
|
-
Duplicate some text an arbitrary number of times.
|
11
|
-
|
12
|
-
text - The String to be duplicated.
|
13
|
-
count - The Integer number of times to duplicate the text.
|
14
|
-
|
15
|
-
Examples
|
16
|
-
multiplex('Tom', 4)
|
17
|
-
# => 'TomTomTomTom'
|
18
|
-
|
19
|
-
Returns the duplicated String.
|
20
|
-
|
21
|
-
Raises ArgumentError if something bad happened
|
22
|
-
eof
|
23
|
-
end
|
24
|
-
|
25
|
-
test "should fill docstring with description" do
|
26
|
-
@docstring == "Duplicate some text an arbitrary number of times."
|
27
|
-
end
|
28
|
-
|
29
|
-
test "should fill param tags" do
|
30
|
-
tags = @docstring.tags(:param)
|
31
|
-
tags.size == 2 &&
|
32
|
-
tags[0].name == 'text' &&
|
33
|
-
tags[1].name == 'count'
|
34
|
-
end
|
35
|
-
|
36
|
-
test "should fill examples tags" do
|
37
|
-
@docstring.tags(:example).size == 1 &&
|
38
|
-
@docstring.tag(:example).text == "multiplex('Tom', 4)\n # => 'TomTomTomTom'"
|
39
|
-
end
|
40
|
-
|
41
|
-
test "should fill return tag" do
|
42
|
-
@docstring.tag(:return).text == "the duplicated String."
|
43
|
-
end
|
44
|
-
|
45
|
-
test "should fill raise tag" do
|
46
|
-
@docstring.tag(:raise).text == "ArgumentError if something bad happened"
|
47
|
-
end
|
48
|
-
end
|