yard-tomdoc 0.2.0
Sign up to get free protection for your applications and to get access to all the features.
- data/HISTORY.md +13 -0
- data/MIT.txt +20 -0
- data/NOTICE.md +17 -0
- data/README.md +28 -0
- data/VERSION +1 -0
- data/lib/.yardoc/checksums +0 -0
- data/lib/.yardoc/objects/root.dat +0 -0
- data/lib/.yardoc/proxy_types +0 -0
- data/lib/yard-tomdoc.rb +42 -0
- data/lib/yard-tomdoc/tomdoc.rb +164 -0
- data/test/case_docstring.rb +48 -0
- metadata +122 -0
data/HISTORY.md
ADDED
@@ -0,0 +1,13 @@
|
|
1
|
+
# RELEASE HISTORY
|
2
|
+
|
3
|
+
## 0.2.0 | 2011-05-22
|
4
|
+
|
5
|
+
This is first packaged release of YARD-TomDoc. Some minor
|
6
|
+
improvements have been made from the original version and
|
7
|
+
the project now actually depends on the `tomdoc` library.
|
8
|
+
|
9
|
+
Changes:
|
10
|
+
|
11
|
+
* Depend on `tomdoc` library.
|
12
|
+
* Support YARD's method return object.
|
13
|
+
* Fix args issues when missing section.
|
data/MIT.txt
ADDED
@@ -0,0 +1,20 @@
|
|
1
|
+
The MIT License
|
2
|
+
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
4
|
+
of this software and associated documentation files (the "Software"), to deal
|
5
|
+
in the Software without restriction, including without limitation the rights
|
6
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
7
|
+
copies of the Software, and to permit persons to whom the Software is
|
8
|
+
furnished to do so, subject to the following conditions:
|
9
|
+
|
10
|
+
The above copyright notice and this permission notice shall be included in
|
11
|
+
all copies or substantial portions of the Software.
|
12
|
+
|
13
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
14
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
15
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
16
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
17
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
18
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
19
|
+
THE SOFTWARE.
|
20
|
+
|
data/NOTICE.md
ADDED
@@ -0,0 +1,17 @@
|
|
1
|
+
COPYRIGHT NOTICES
|
2
|
+
=================
|
3
|
+
|
4
|
+
Yard TomDoc
|
5
|
+
-----------
|
6
|
+
|
7
|
+
Copyright (c) 2010 Loren Segal, Thomas Sawyer
|
8
|
+
|
9
|
+
Distributed under the terms of the MIT License (see MIT.txt).
|
10
|
+
|
11
|
+
|
12
|
+
TomDoc
|
13
|
+
------
|
14
|
+
|
15
|
+
Copyright (c) 2010 Tom Preston-Werner, Chris Wanstrath
|
16
|
+
|
17
|
+
Distributed under the terms of the MIT License (see MIT.txt).
|
data/README.md
ADDED
@@ -0,0 +1,28 @@
|
|
1
|
+
# yard-tomdoc
|
2
|
+
|
3
|
+
|
4
|
+
## Description
|
5
|
+
|
6
|
+
Implements [TomDoc](http://tomdoc.org) syntax for YARD. 'Nuff said.
|
7
|
+
|
8
|
+
|
9
|
+
## Usage
|
10
|
+
|
11
|
+
Since `yard-tomdoc` is a standard YARD plugin, utilize it with yard's
|
12
|
+
`--plugin` option.
|
13
|
+
|
14
|
+
$ yard --plugin yard-tomdoc [...]
|
15
|
+
|
16
|
+
|
17
|
+
## Limitations
|
18
|
+
|
19
|
+
Before you use yard-tomdoc you should read about the differences between YARD
|
20
|
+
and TomDoc syntax [here](http://gnuu.org/2010/05/12/whats-missing-from-tomdoc/).
|
21
|
+
|
22
|
+
|
23
|
+
## Licensing
|
24
|
+
|
25
|
+
Copyright (c) 2010 Loren Segal, Thomas Sawyer
|
26
|
+
|
27
|
+
See the `NOTICE` file for license information on TomDoc.
|
28
|
+
|
data/VERSION
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
0.2.0
|
File without changes
|
Binary file
|
Binary file
|
data/lib/yard-tomdoc.rb
ADDED
@@ -0,0 +1,42 @@
|
|
1
|
+
#require File.dirname(__FILE__) + "/yard-tomdoc/tomdoc" #require 'tomdoc/tomdoc'
|
2
|
+
require 'tomdoc/tomdoc'
|
3
|
+
|
4
|
+
module YARD
|
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
|
+
|
41
|
+
end
|
42
|
+
|
@@ -0,0 +1,164 @@
|
|
1
|
+
#require 'yard'
|
2
|
+
|
3
|
+
module TomDoc
|
4
|
+
class InvalidTomDoc < RuntimeError
|
5
|
+
# Create new InvalidTomDoc object.
|
6
|
+
#
|
7
|
+
# doc - document string
|
8
|
+
#
|
9
|
+
def initialize(doc)
|
10
|
+
@doc = doc
|
11
|
+
end
|
12
|
+
|
13
|
+
# Provide access to document string.
|
14
|
+
#
|
15
|
+
# Returns String.
|
16
|
+
def message
|
17
|
+
@doc
|
18
|
+
end
|
19
|
+
|
20
|
+
# Provide access to document string.
|
21
|
+
#
|
22
|
+
# Returns String.
|
23
|
+
def to_s
|
24
|
+
@doc
|
25
|
+
end
|
26
|
+
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
|
+
|
49
|
+
class TomDoc
|
50
|
+
attr_accessor :raw
|
51
|
+
|
52
|
+
def initialize(text)
|
53
|
+
@raw = text.to_s.strip
|
54
|
+
end
|
55
|
+
|
56
|
+
def to_s
|
57
|
+
@raw
|
58
|
+
end
|
59
|
+
|
60
|
+
def self.valid?(text)
|
61
|
+
new(text).valid?
|
62
|
+
end
|
63
|
+
|
64
|
+
def valid?
|
65
|
+
validate
|
66
|
+
rescue InvalidTomDoc
|
67
|
+
false
|
68
|
+
end
|
69
|
+
|
70
|
+
def validate
|
71
|
+
if !raw.include?('Returns')
|
72
|
+
raise InvalidTomDoc.new("No `Returns' statement.")
|
73
|
+
end
|
74
|
+
|
75
|
+
if tomdoc.split("\n\n").size < 2
|
76
|
+
raise InvalidTomDoc.new("No description section found.")
|
77
|
+
end
|
78
|
+
|
79
|
+
true
|
80
|
+
end
|
81
|
+
|
82
|
+
def tomdoc
|
83
|
+
raw
|
84
|
+
end
|
85
|
+
|
86
|
+
def sections
|
87
|
+
tomdoc.split("\n\n")
|
88
|
+
end
|
89
|
+
|
90
|
+
def description
|
91
|
+
sections.first
|
92
|
+
end
|
93
|
+
|
94
|
+
def args
|
95
|
+
args = []
|
96
|
+
last_indent = nil
|
97
|
+
|
98
|
+
return args unless sections[1]
|
99
|
+
|
100
|
+
sections[1].split("\n").each do |line|
|
101
|
+
next if line.strip.empty?
|
102
|
+
indent = line.scan(/^\s*/)[0].to_s.size
|
103
|
+
|
104
|
+
if last_indent && indent > last_indent
|
105
|
+
args.last.description += line.squeeze(" ")
|
106
|
+
else
|
107
|
+
param, desc = line.split(" - ")
|
108
|
+
args << Arg.new(param.strip, desc.strip) if param && desc
|
109
|
+
end
|
110
|
+
|
111
|
+
last_indent = indent
|
112
|
+
end
|
113
|
+
|
114
|
+
args
|
115
|
+
end
|
116
|
+
|
117
|
+
def examples
|
118
|
+
if tomdoc =~ /(\s*Examples\s*(.+?)\s*(?:Returns|Raises))/m
|
119
|
+
$2.split("\n\n")
|
120
|
+
else
|
121
|
+
[]
|
122
|
+
end
|
123
|
+
end
|
124
|
+
|
125
|
+
def returns
|
126
|
+
if tomdoc =~ /^\s*(Returns.+)/m
|
127
|
+
lines = $1.split("\n")
|
128
|
+
statements = []
|
129
|
+
|
130
|
+
lines.each do |line|
|
131
|
+
next if line =~ /^\s*Raises/
|
132
|
+
if line =~ /^\s+/
|
133
|
+
statements.last << line.squeeze(' ')
|
134
|
+
else
|
135
|
+
statements << line
|
136
|
+
end
|
137
|
+
end
|
138
|
+
|
139
|
+
statements
|
140
|
+
else
|
141
|
+
[]
|
142
|
+
end
|
143
|
+
end
|
144
|
+
|
145
|
+
def raises
|
146
|
+
if tomdoc =~ /^\s*(Raises.+)/m
|
147
|
+
lines = $1.split("\n")
|
148
|
+
statements = []
|
149
|
+
|
150
|
+
lines.each do |line|
|
151
|
+
if line =~ /^\s+/
|
152
|
+
statements.last << line.squeeze(' ')
|
153
|
+
else
|
154
|
+
statements << line
|
155
|
+
end
|
156
|
+
end
|
157
|
+
|
158
|
+
statements
|
159
|
+
else
|
160
|
+
[]
|
161
|
+
end
|
162
|
+
end
|
163
|
+
end
|
164
|
+
end
|
@@ -0,0 +1,48 @@
|
|
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
|
metadata
ADDED
@@ -0,0 +1,122 @@
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
2
|
+
name: yard-tomdoc
|
3
|
+
version: !ruby/object:Gem::Version
|
4
|
+
hash: 23
|
5
|
+
prerelease:
|
6
|
+
segments:
|
7
|
+
- 0
|
8
|
+
- 2
|
9
|
+
- 0
|
10
|
+
version: 0.2.0
|
11
|
+
platform: ruby
|
12
|
+
authors:
|
13
|
+
- Loren Segal
|
14
|
+
- Thomas Sawyer
|
15
|
+
autorequire:
|
16
|
+
bindir: bin
|
17
|
+
cert_chain: []
|
18
|
+
|
19
|
+
date: 2011-05-22 00:00:00 Z
|
20
|
+
dependencies:
|
21
|
+
- !ruby/object:Gem::Dependency
|
22
|
+
name: tomdoc
|
23
|
+
prerelease: false
|
24
|
+
requirement: &id001 !ruby/object:Gem::Requirement
|
25
|
+
none: false
|
26
|
+
requirements:
|
27
|
+
- - ">="
|
28
|
+
- !ruby/object:Gem::Version
|
29
|
+
hash: 23
|
30
|
+
segments:
|
31
|
+
- 0
|
32
|
+
- 2
|
33
|
+
- 0
|
34
|
+
version: 0.2.0
|
35
|
+
type: :runtime
|
36
|
+
version_requirements: *id001
|
37
|
+
- !ruby/object:Gem::Dependency
|
38
|
+
name: ko
|
39
|
+
prerelease: false
|
40
|
+
requirement: &id002 !ruby/object:Gem::Requirement
|
41
|
+
none: false
|
42
|
+
requirements:
|
43
|
+
- - ">="
|
44
|
+
- !ruby/object:Gem::Version
|
45
|
+
hash: 3
|
46
|
+
segments:
|
47
|
+
- 0
|
48
|
+
version: "0"
|
49
|
+
type: :development
|
50
|
+
version_requirements: *id002
|
51
|
+
- !ruby/object:Gem::Dependency
|
52
|
+
name: redline
|
53
|
+
prerelease: false
|
54
|
+
requirement: &id003 !ruby/object:Gem::Requirement
|
55
|
+
none: false
|
56
|
+
requirements:
|
57
|
+
- - ">="
|
58
|
+
- !ruby/object:Gem::Version
|
59
|
+
hash: 3
|
60
|
+
segments:
|
61
|
+
- 0
|
62
|
+
version: "0"
|
63
|
+
type: :development
|
64
|
+
version_requirements: *id003
|
65
|
+
description: Implements [TomDoc](http://tomdoc.org) syntax for YARD. 'Nuff said.
|
66
|
+
email: transfire@gmail.com
|
67
|
+
executables: []
|
68
|
+
|
69
|
+
extensions: []
|
70
|
+
|
71
|
+
extra_rdoc_files:
|
72
|
+
- README.md
|
73
|
+
files:
|
74
|
+
- lib/.yardoc/checksums
|
75
|
+
- lib/.yardoc/objects/root.dat
|
76
|
+
- lib/.yardoc/proxy_types
|
77
|
+
- lib/yard-tomdoc/tomdoc.rb
|
78
|
+
- lib/yard-tomdoc.rb
|
79
|
+
- test/case_docstring.rb
|
80
|
+
- HISTORY.md
|
81
|
+
- README.md
|
82
|
+
- VERSION
|
83
|
+
- MIT.txt
|
84
|
+
- NOTICE.md
|
85
|
+
homepage: http://rubyworks.github.com/yard-tomdoc
|
86
|
+
licenses:
|
87
|
+
- MIT
|
88
|
+
post_install_message:
|
89
|
+
rdoc_options:
|
90
|
+
- --title
|
91
|
+
- YARD-TomDoc API
|
92
|
+
- --main
|
93
|
+
- README.md
|
94
|
+
require_paths:
|
95
|
+
- lib
|
96
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
97
|
+
none: false
|
98
|
+
requirements:
|
99
|
+
- - ">="
|
100
|
+
- !ruby/object:Gem::Version
|
101
|
+
hash: 3
|
102
|
+
segments:
|
103
|
+
- 0
|
104
|
+
version: "0"
|
105
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
106
|
+
none: false
|
107
|
+
requirements:
|
108
|
+
- - ">="
|
109
|
+
- !ruby/object:Gem::Version
|
110
|
+
hash: 3
|
111
|
+
segments:
|
112
|
+
- 0
|
113
|
+
version: "0"
|
114
|
+
requirements: []
|
115
|
+
|
116
|
+
rubyforge_project: yard-tomdoc
|
117
|
+
rubygems_version: 1.8.2
|
118
|
+
signing_key:
|
119
|
+
specification_version: 3
|
120
|
+
summary: TomDoc for YARD
|
121
|
+
test_files: []
|
122
|
+
|