yard-tomdoc 0.3.1 → 0.4.0
Sign up to get free protection for your applications and to get access to all the features.
- data/HISTORY.md +15 -0
- data/LICENSE.txt +22 -0
- data/README.md +10 -9
- data/lib/yard-tomdoc.rb +70 -5
- data/lib/yard-tomdoc.yml +48 -0
- data/test/helper.rb +0 -4
- data/test/system/test_yardoc.rb +3 -2
- data/test/unit/test_docstring.rb +10 -13
- metadata +28 -20
- data/NOTICE.md +0 -37
- data/lib/yard-tomdoc-intern.rb +0 -3
- data/lib/yard-tomdoc/arg.rb +0 -22
- data/lib/yard-tomdoc/tomdoc.rb +0 -166
- data/lib/yard-tomdoc/version.rb +0 -6
- data/lib/yard-tomdoc/yard.rb +0 -39
data/HISTORY.md
CHANGED
@@ -1,5 +1,19 @@
|
|
1
1
|
# RELEASE HISTORY
|
2
2
|
|
3
|
+
## 0.4.0 2012-03-04
|
4
|
+
|
5
|
+
This major release now uses tomparse gem for parsing TomDoc,
|
6
|
+
instead of the tomdoc gem. This library only handles parsing
|
7
|
+
and none of the other features than the tomdoc gem provides,
|
8
|
+
so it is more suited to yard-tomdoc's needs. In addition,
|
9
|
+
support for the latest TomDoc specification are included in
|
10
|
+
this release.
|
11
|
+
|
12
|
+
Changes:
|
13
|
+
|
14
|
+
* Use tomparse gem for parsing TomDoc.
|
15
|
+
* Improve support for TomDoc features.
|
16
|
+
|
3
17
|
|
4
18
|
## 0.3.1 | 2011-11-10
|
5
19
|
|
@@ -47,3 +61,4 @@ Changes:
|
|
47
61
|
* Depend on `tomdoc` library.
|
48
62
|
* Support YARD's method return object.
|
49
63
|
* Fix args issues when missing section.
|
64
|
+
|
data/LICENSE.txt
ADDED
@@ -0,0 +1,22 @@
|
|
1
|
+
YARD::TomDoc - Use TomDoc with YARD
|
2
|
+
|
3
|
+
Copyright (c) 2010 Loren Segal, Thomas Sawyer (MIT License)
|
4
|
+
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
7
|
+
in the Software without restriction, including without limitation the rights
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
10
|
+
furnished to do so, subject to the following conditions:
|
11
|
+
|
12
|
+
The above copyright notice and this permission notice shall be included in
|
13
|
+
all copies or substantial portions of the Software.
|
14
|
+
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
21
|
+
THE SOFTWARE.
|
22
|
+
|
data/README.md
CHANGED
@@ -1,11 +1,10 @@
|
|
1
|
-
#
|
1
|
+
# YARD::TomDoc
|
2
2
|
|
3
|
-
|
4
|
-
|
5
|
-
|
6
|
-
|
7
|
-
|
8
|
-
| Status: | [![Build Status](https://secure.travis-ci.org/rubyworks/yard-tomdoc.png)](http://travis-ci.org/rubyworks/yard-tomdoc) |
|
3
|
+
[Website](http://rubyworks.github.com/yard-tomdoc) /
|
4
|
+
[Development](http://github.com/rubyworks/yard-tomdoc) /
|
5
|
+
[Issues](http://github.com/rubyworks/yard-tomdoc/issues)
|
6
|
+
|
7
|
+
[![Build Status](https://secure.travis-ci.org/rubyworks/yard-tomdoc.png)](http://travis-ci.org/rubyworks/yard-tomdoc)
|
9
8
|
|
10
9
|
|
11
10
|
## Description
|
@@ -13,7 +12,7 @@
|
|
13
12
|
Implements [TomDoc](http://tomdoc.org) syntax for YARD. 'Nuff said.
|
14
13
|
|
15
14
|
|
16
|
-
##
|
15
|
+
## Instruction
|
17
16
|
|
18
17
|
Since `yard-tomdoc` is a standard YARD plugin, utilize it with yard's
|
19
18
|
`--plugin` option.
|
@@ -31,5 +30,7 @@ and TomDoc syntax [here](http://gnuu.org/2010/05/12/whats-missing-from-tomdoc/).
|
|
31
30
|
|
32
31
|
Copyright (c) 2010 Loren Segal, Thomas Sawyer
|
33
32
|
|
34
|
-
|
33
|
+
YARD::TomDoc is distributable in accordance with the ters of the **MIT** licsnse.
|
34
|
+
|
35
|
+
See the `LICENSE.txt` file for details.
|
35
36
|
|
data/lib/yard-tomdoc.rb
CHANGED
@@ -1,6 +1,71 @@
|
|
1
|
-
|
2
|
-
|
3
|
-
|
4
|
-
|
1
|
+
require 'tomparse'
|
2
|
+
|
3
|
+
module YARD
|
4
|
+
|
5
|
+
module TomDoc
|
6
|
+
# Metadata from the project's `yard-tomdoc.yml` fle.
|
7
|
+
#
|
8
|
+
# Returns [Hash] of metadata.
|
9
|
+
def self.metadata
|
10
|
+
@metadata ||= (
|
11
|
+
require 'yaml'
|
12
|
+
YAML.load_file(File.dirname(__FILE__) + '/yard-tomdoc.yml')
|
13
|
+
)
|
14
|
+
end
|
15
|
+
|
16
|
+
# When a constant is missing, see if it is a metadata entry.
|
17
|
+
#
|
18
|
+
# name - [Symbol] constant name
|
19
|
+
#
|
20
|
+
# Returns metadata value.
|
21
|
+
def self.const_missing(name)
|
22
|
+
metadata[name.to_s.downcase] || super(name)
|
23
|
+
end
|
24
|
+
end
|
25
|
+
|
26
|
+
class Docstring
|
27
|
+
# Parse comments with TomDoc and then provide YARD with results.
|
28
|
+
#
|
29
|
+
# comments - [Array] comment strings
|
30
|
+
#
|
31
|
+
# Returns [String] parsed comments description
|
32
|
+
def parse_comments(comments)
|
33
|
+
comment = [comments].flatten.join("\n")
|
34
|
+
|
35
|
+
tomdoc = TomParse.parse(comment)
|
36
|
+
|
37
|
+
tomdoc.examples.each {|ex| create_tag(:example, "\n" + ex) }
|
38
|
+
|
39
|
+
tomdoc.arguments.each {|arg| create_tag(:param, "#{arg.name} #{arg.description}") }
|
40
|
+
|
41
|
+
if last_argument = tomdoc.arguments.last
|
42
|
+
last_argument.options.each do |opt|
|
43
|
+
create_tag(:option, "#{last_argument.name} #{opt.description}")
|
44
|
+
end
|
45
|
+
end
|
46
|
+
|
47
|
+
tomdoc.raises.each {|r| create_tag(:raise, r.sub(/\ARaises\s+/, '')) }
|
48
|
+
|
49
|
+
tomdoc.returns.each do |r|
|
50
|
+
if md = /\AReturns\s+([A-Z].*?)\s+/.match(r)
|
51
|
+
klass = md[1]
|
52
|
+
desc = md.post_match
|
53
|
+
create_tag(:return, "[#{klass}] #{desc}")
|
54
|
+
else
|
55
|
+
desc = r.sub(/\AReturns\s+/, '')
|
56
|
+
create_tag(:return, desc)
|
57
|
+
end
|
58
|
+
end
|
59
|
+
|
60
|
+
create_tag(:yield, tomdoc.yields) if tomdoc.yields
|
61
|
+
|
62
|
+
create_tag(:deprecated) if tomdoc.deprecated?
|
63
|
+
|
64
|
+
create_tag(:private) if tomdoc.internal?
|
65
|
+
|
66
|
+
# notice we return the modified comment
|
67
|
+
tomdoc.description.to_s
|
68
|
+
end
|
69
|
+
end
|
70
|
+
|
5
71
|
end
|
6
|
-
require 'yard-tomdoc/yard'
|
data/lib/yard-tomdoc.yml
ADDED
@@ -0,0 +1,48 @@
|
|
1
|
+
---
|
2
|
+
source:
|
3
|
+
- Profile
|
4
|
+
authors:
|
5
|
+
- name: Trans
|
6
|
+
email: transfire@gmail.com
|
7
|
+
- name: Loren Segal
|
8
|
+
copyrights:
|
9
|
+
- holder: Rubyworks
|
10
|
+
year: '2012'
|
11
|
+
license: MIT
|
12
|
+
- holder: Loren Segal
|
13
|
+
year: '2010'
|
14
|
+
license: MIT
|
15
|
+
requirements:
|
16
|
+
- name: yard
|
17
|
+
- name: tomparse
|
18
|
+
- name: detroit
|
19
|
+
groups:
|
20
|
+
- build
|
21
|
+
development: true
|
22
|
+
- name: spectroscope
|
23
|
+
groups:
|
24
|
+
- test
|
25
|
+
development: true
|
26
|
+
- name: ae
|
27
|
+
groups:
|
28
|
+
- test
|
29
|
+
development: true
|
30
|
+
dependencies: []
|
31
|
+
alternatives: []
|
32
|
+
conflicts: []
|
33
|
+
repositories: []
|
34
|
+
resources:
|
35
|
+
home: http://rubyworks.github.com/yard-tomdoc
|
36
|
+
code: http://github.com/rubyworks/yard-tomdoc
|
37
|
+
bugs: http://github.com/rubyworks/yard-tomdoc/issues
|
38
|
+
docs: http://rubydoc.info/gems/yard-tomdoc/frames
|
39
|
+
extra: {}
|
40
|
+
load_path:
|
41
|
+
- lib
|
42
|
+
revision: 0
|
43
|
+
name: yard-tomdoc
|
44
|
+
title: YARD TomDoc
|
45
|
+
version: 0.4.0
|
46
|
+
summary: TomDoc for YARD
|
47
|
+
description: Use TomDoc documentation format with YARD.
|
48
|
+
date: '2012-03-04'
|
data/test/helper.rb
CHANGED
data/test/system/test_yardoc.rb
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
dir = File.expand_path(File.dirname(__FILE__))
|
2
|
-
tmp = dir + '/../../tmp'
|
2
|
+
tmp = File.expand_path(dir + '/../../tmp')
|
3
3
|
|
4
|
-
require
|
4
|
+
require "helper"
|
5
5
|
|
6
6
|
# This test is design to run `yard doc` on the sample project and
|
7
7
|
# check to make sure it was produced successufully.
|
@@ -28,3 +28,4 @@ describe "yard doc" do
|
|
28
28
|
end
|
29
29
|
|
30
30
|
end
|
31
|
+
|
data/test/unit/test_docstring.rb
CHANGED
@@ -1,10 +1,7 @@
|
|
1
|
-
require
|
1
|
+
require 'helper.rb'
|
2
2
|
|
3
3
|
require "yard"
|
4
|
-
|
5
|
-
|
6
|
-
# TODO: make separate test for this
|
7
|
-
require "yard-tomdoc-intern"
|
4
|
+
require "yard-tomdoc"
|
8
5
|
|
9
6
|
describe YARD::Docstring do
|
10
7
|
|
@@ -26,26 +23,26 @@ eof
|
|
26
23
|
end
|
27
24
|
|
28
25
|
it "should fill docstring with description" do
|
29
|
-
@docstring.
|
26
|
+
@docstring.assert == "Duplicate some text an arbitrary number of times."
|
30
27
|
end
|
31
28
|
|
32
29
|
it "should fill param tags" do
|
33
30
|
tags = @docstring.tags(:param)
|
34
|
-
tags.size.
|
35
|
-
tags[0].name.
|
36
|
-
tags[1].name.
|
31
|
+
tags.size.assert == 2
|
32
|
+
tags[0].name.assert == 'text'
|
33
|
+
tags[1].name.assert == 'count'
|
37
34
|
end
|
38
35
|
|
39
36
|
it "should fill examples tags" do
|
40
|
-
@docstring.tags(:example).size.
|
41
|
-
@docstring.tag(:example).text.
|
37
|
+
@docstring.tags(:example).size.assert == 1
|
38
|
+
@docstring.tag(:example).text.assert == "multiplex('Tom', 4)\n # => 'TomTomTomTom'"
|
42
39
|
end
|
43
40
|
|
44
41
|
it "should fill return tag" do
|
45
|
-
@docstring.tag(:return).text.
|
42
|
+
@docstring.tag(:return).text.assert == "the duplicated String."
|
46
43
|
end
|
47
44
|
|
48
45
|
it "should fill raise tag" do
|
49
|
-
@docstring.tag(:raise).text.
|
46
|
+
@docstring.tag(:raise).text.assert == "ArgumentError if something bad happened"
|
50
47
|
end
|
51
48
|
end
|
metadata
CHANGED
@@ -1,20 +1,20 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: yard-tomdoc
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.4.0
|
5
5
|
prerelease:
|
6
6
|
platform: ruby
|
7
7
|
authors:
|
8
|
-
-
|
8
|
+
- Trans
|
9
9
|
- Loren Segal
|
10
10
|
autorequire:
|
11
11
|
bindir: bin
|
12
12
|
cert_chain: []
|
13
|
-
date: 2012-
|
13
|
+
date: 2012-03-08 00:00:00.000000000 Z
|
14
14
|
dependencies:
|
15
15
|
- !ruby/object:Gem::Dependency
|
16
16
|
name: yard
|
17
|
-
requirement: &
|
17
|
+
requirement: &18163280 !ruby/object:Gem::Requirement
|
18
18
|
none: false
|
19
19
|
requirements:
|
20
20
|
- - ! '>='
|
@@ -22,10 +22,21 @@ dependencies:
|
|
22
22
|
version: '0'
|
23
23
|
type: :runtime
|
24
24
|
prerelease: false
|
25
|
-
version_requirements: *
|
25
|
+
version_requirements: *18163280
|
26
|
+
- !ruby/object:Gem::Dependency
|
27
|
+
name: tomparse
|
28
|
+
requirement: &18162760 !ruby/object:Gem::Requirement
|
29
|
+
none: false
|
30
|
+
requirements:
|
31
|
+
- - ! '>='
|
32
|
+
- !ruby/object:Gem::Version
|
33
|
+
version: '0'
|
34
|
+
type: :runtime
|
35
|
+
prerelease: false
|
36
|
+
version_requirements: *18162760
|
26
37
|
- !ruby/object:Gem::Dependency
|
27
38
|
name: detroit
|
28
|
-
requirement: &
|
39
|
+
requirement: &18162260 !ruby/object:Gem::Requirement
|
29
40
|
none: false
|
30
41
|
requirements:
|
31
42
|
- - ! '>='
|
@@ -33,10 +44,10 @@ dependencies:
|
|
33
44
|
version: '0'
|
34
45
|
type: :development
|
35
46
|
prerelease: false
|
36
|
-
version_requirements: *
|
47
|
+
version_requirements: *18162260
|
37
48
|
- !ruby/object:Gem::Dependency
|
38
|
-
name:
|
39
|
-
requirement: &
|
49
|
+
name: spectroscope
|
50
|
+
requirement: &18161760 !ruby/object:Gem::Requirement
|
40
51
|
none: false
|
41
52
|
requirements:
|
42
53
|
- - ! '>='
|
@@ -44,10 +55,10 @@ dependencies:
|
|
44
55
|
version: '0'
|
45
56
|
type: :development
|
46
57
|
prerelease: false
|
47
|
-
version_requirements: *
|
58
|
+
version_requirements: *18161760
|
48
59
|
- !ruby/object:Gem::Dependency
|
49
|
-
name:
|
50
|
-
requirement: &
|
60
|
+
name: ae
|
61
|
+
requirement: &18161260 !ruby/object:Gem::Requirement
|
51
62
|
none: false
|
52
63
|
requirements:
|
53
64
|
- - ! '>='
|
@@ -55,34 +66,31 @@ dependencies:
|
|
55
66
|
version: '0'
|
56
67
|
type: :development
|
57
68
|
prerelease: false
|
58
|
-
version_requirements: *
|
69
|
+
version_requirements: *18161260
|
59
70
|
description: Use TomDoc documentation format with YARD.
|
60
71
|
email:
|
61
72
|
- transfire@gmail.com
|
62
73
|
executables: []
|
63
74
|
extensions: []
|
64
75
|
extra_rdoc_files:
|
76
|
+
- LICENSE.txt
|
65
77
|
- HISTORY.md
|
66
78
|
- README.md
|
67
|
-
- NOTICE.md
|
68
79
|
files:
|
69
|
-
- lib/yard-tomdoc/arg.rb
|
70
|
-
- lib/yard-tomdoc/tomdoc.rb
|
71
|
-
- lib/yard-tomdoc/version.rb
|
72
|
-
- lib/yard-tomdoc/yard.rb
|
73
|
-
- lib/yard-tomdoc-intern.rb
|
74
80
|
- lib/yard-tomdoc.rb
|
81
|
+
- lib/yard-tomdoc.yml
|
75
82
|
- test/helper.rb
|
76
83
|
- test/system/sample/lib/example.rb
|
77
84
|
- test/system/sample/lib/hello_world.rb
|
78
85
|
- test/system/test_yardoc.rb
|
79
86
|
- test/unit/test_docstring.rb
|
87
|
+
- LICENSE.txt
|
80
88
|
- HISTORY.md
|
81
89
|
- README.md
|
82
|
-
- NOTICE.md
|
83
90
|
homepage: http://rubyworks.github.com/yard-tomdoc
|
84
91
|
licenses:
|
85
92
|
- MIT
|
93
|
+
- MIT
|
86
94
|
post_install_message:
|
87
95
|
rdoc_options: []
|
88
96
|
require_paths:
|
data/NOTICE.md
DELETED
@@ -1,37 +0,0 @@
|
|
1
|
-
# COPYRIGHT NOTICES
|
2
|
-
|
3
|
-
|
4
|
-
## YARD Tomdoc
|
5
|
-
|
6
|
-
**Copyright (c) 2010 Loren Segal, Thomas Sawyer**
|
7
|
-
|
8
|
-
Distributed under the terms of the MIT License (see below).
|
9
|
-
|
10
|
-
|
11
|
-
## Tomdoc
|
12
|
-
|
13
|
-
**Copyright (c) 2010 Tom Preston-Werner, Chris Wanstrath**
|
14
|
-
|
15
|
-
Distributed under the terms of the MIT License (see below).
|
16
|
-
|
17
|
-
|
18
|
-
## The MIT License
|
19
|
-
|
20
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
21
|
-
of this software and associated documentation files (the "Software"), to deal
|
22
|
-
in the Software without restriction, including without limitation the rights
|
23
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
24
|
-
copies of the Software, and to permit persons to whom the Software is
|
25
|
-
furnished to do so, subject to the following conditions:
|
26
|
-
|
27
|
-
The above copyright notice and this permission notice shall be included in
|
28
|
-
all copies or substantial portions of the Software.
|
29
|
-
|
30
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
31
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
32
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
33
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
34
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
35
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
36
|
-
THE SOFTWARE.
|
37
|
-
|
data/lib/yard-tomdoc-intern.rb
DELETED
data/lib/yard-tomdoc/arg.rb
DELETED
@@ -1,22 +0,0 @@
|
|
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
DELETED
@@ -1,166 +0,0 @@
|
|
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.
|
11
|
-
class InvalidTomDoc < RuntimeError
|
12
|
-
# Create new InvalidTomDoc object.
|
13
|
-
#
|
14
|
-
# doc - document string
|
15
|
-
#
|
16
|
-
def initialize(doc)
|
17
|
-
@doc = doc
|
18
|
-
end
|
19
|
-
|
20
|
-
# Provide access to document string.
|
21
|
-
#
|
22
|
-
# Returns [String] documentation string.
|
23
|
-
def message
|
24
|
-
@doc
|
25
|
-
end
|
26
|
-
|
27
|
-
# Provide access to document string.
|
28
|
-
#
|
29
|
-
# Returns [String] documentation string.
|
30
|
-
def to_s
|
31
|
-
@doc
|
32
|
-
end
|
33
|
-
end
|
34
|
-
|
35
|
-
# Model a TomDoc comment.
|
36
|
-
class TomDoc
|
37
|
-
attr_accessor :raw
|
38
|
-
|
39
|
-
def initialize(text)
|
40
|
-
@raw = text.to_s.strip
|
41
|
-
end
|
42
|
-
|
43
|
-
# Returns [String] raw comment text.
|
44
|
-
def to_s
|
45
|
-
@raw
|
46
|
-
end
|
47
|
-
|
48
|
-
# Returns [Boolean] true if valid TomDoc comment.
|
49
|
-
def self.valid?(text)
|
50
|
-
new(text).valid?
|
51
|
-
end
|
52
|
-
|
53
|
-
# Returns [Boolean] true if valid TomDoc comment, otherwise false.
|
54
|
-
def valid?
|
55
|
-
validate
|
56
|
-
rescue InvalidTomDoc
|
57
|
-
false
|
58
|
-
end
|
59
|
-
|
60
|
-
# Returns [Boolean] true if validation doesn't raise an error.
|
61
|
-
def validate
|
62
|
-
if !raw.include?('Returns')
|
63
|
-
raise InvalidTomDoc.new("No `Returns' statement.")
|
64
|
-
end
|
65
|
-
|
66
|
-
if tomdoc.split("\n\n").size < 2
|
67
|
-
raise InvalidTomDoc.new("No description section found.")
|
68
|
-
end
|
69
|
-
|
70
|
-
true
|
71
|
-
end
|
72
|
-
|
73
|
-
# Returns [String] cleansed comment text.
|
74
|
-
def tomdoc
|
75
|
-
#raw
|
76
|
-
clean = raw.split("\n").map do |line|
|
77
|
-
line =~ /^(\s*# ?)/ ? line.sub($1, '') : nil
|
78
|
-
end.compact.join("\n")
|
79
|
-
clean
|
80
|
-
end
|
81
|
-
|
82
|
-
# Returns [Array] document split into sections.
|
83
|
-
def sections
|
84
|
-
tomdoc.split("\n\n")
|
85
|
-
end
|
86
|
-
|
87
|
-
# Returns [String] first section.
|
88
|
-
def description
|
89
|
-
sections.first
|
90
|
-
end
|
91
|
-
|
92
|
-
# Returns [Array] list of arguments.
|
93
|
-
def args
|
94
|
-
args = []
|
95
|
-
last_indent = nil
|
96
|
-
|
97
|
-
return args unless sections[1]
|
98
|
-
|
99
|
-
sections[1].split("\n").each do |line|
|
100
|
-
next if line.strip.empty?
|
101
|
-
indent = line.scan(/^\s*/)[0].to_s.size
|
102
|
-
|
103
|
-
if last_indent && indent > last_indent
|
104
|
-
args.last.description += line.squeeze(" ")
|
105
|
-
else
|
106
|
-
param, desc = line.split(" - ")
|
107
|
-
args << Arg.new(param.strip, desc.strip) if param && desc
|
108
|
-
end
|
109
|
-
|
110
|
-
last_indent = indent
|
111
|
-
end
|
112
|
-
|
113
|
-
args
|
114
|
-
end
|
115
|
-
|
116
|
-
# Returns [Array] list of examples.
|
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
|
-
# Returns [Array] list of possible returns.
|
126
|
-
def returns
|
127
|
-
if tomdoc =~ /^\s*(Returns.+)/m
|
128
|
-
lines = $1.split("\n")
|
129
|
-
statements = []
|
130
|
-
|
131
|
-
lines.each do |line|
|
132
|
-
next if line =~ /^\s*Raises/
|
133
|
-
if line =~ /^\s+/
|
134
|
-
statements.last << line.squeeze(' ')
|
135
|
-
else
|
136
|
-
statements << line
|
137
|
-
end
|
138
|
-
end
|
139
|
-
|
140
|
-
statements
|
141
|
-
else
|
142
|
-
[]
|
143
|
-
end
|
144
|
-
end
|
145
|
-
|
146
|
-
# Returns [Array] list of possible errors that could be raised.
|
147
|
-
def raises
|
148
|
-
if tomdoc =~ /^\s*(Raises.+)/m
|
149
|
-
lines = $1.split("\n")
|
150
|
-
statements = []
|
151
|
-
|
152
|
-
lines.each do |line|
|
153
|
-
if line =~ /^\s+/
|
154
|
-
statements.last << line.squeeze(' ')
|
155
|
-
else
|
156
|
-
statements << line
|
157
|
-
end
|
158
|
-
end
|
159
|
-
|
160
|
-
statements
|
161
|
-
else
|
162
|
-
[]
|
163
|
-
end
|
164
|
-
end
|
165
|
-
end
|
166
|
-
end
|
data/lib/yard-tomdoc/version.rb
DELETED
data/lib/yard-tomdoc/yard.rb
DELETED
@@ -1,39 +0,0 @@
|
|
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
|
-
|