yard-struct 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/.document +5 -0
- data/.gitignore +21 -0
- data/LICENSE +20 -0
- data/README.md +54 -0
- data/Rakefile +46 -0
- data/VERSION +1 -0
- data/lib/yard-struct.rb +5 -0
- data/lib/yard-struct/legacy_handler.rb +61 -0
- data/lib/yard-struct/modern_handler.rb +60 -0
- data/lib/yard-struct/shared_methods.rb +123 -0
- data/lib/yard-struct/tag_handler.rb +3 -0
- data/spec/examples/example_helper.rb +23 -0
- data/spec/examples/examples/simple_struct.rb +4 -0
- data/spec/examples/examples/struct_with_docs.rb +12 -0
- data/spec/spec.opts +1 -0
- data/spec/spec_helper.rb +14 -0
- data/spec/yard-struct_spec.rb +83 -0
- data/yard-struct.gemspec +67 -0
- metadata +111 -0
data/.document
ADDED
data/.gitignore
ADDED
data/LICENSE
ADDED
@@ -0,0 +1,20 @@
|
|
1
|
+
Copyright (c) 2009 Michael Edgar
|
2
|
+
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
4
|
+
a copy of this software and associated documentation files (the
|
5
|
+
"Software"), to deal in the Software without restriction, including
|
6
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
7
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
8
|
+
permit persons to whom the Software is furnished to do so, subject to
|
9
|
+
the following conditions:
|
10
|
+
|
11
|
+
The above copyright notice and this permission notice shall be
|
12
|
+
included in all copies or substantial portions of the Software.
|
13
|
+
|
14
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
15
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
16
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
17
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
18
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
19
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
20
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,54 @@
|
|
1
|
+
# yard-struct
|
2
|
+
|
3
|
+
Plugin for YARD which generates documentation for Struct members.
|
4
|
+
|
5
|
+
## Why?
|
6
|
+
|
7
|
+
Without yard-struct, there's a big difference between these as YARD can see
|
8
|
+
them:
|
9
|
+
|
10
|
+
class A < Struct.new(:foo, :bar)
|
11
|
+
def to_s
|
12
|
+
foo + bar
|
13
|
+
end
|
14
|
+
end
|
15
|
+
|
16
|
+
class B
|
17
|
+
attr_accessor :foo, :bar
|
18
|
+
def to_s
|
19
|
+
foo + bar
|
20
|
+
end
|
21
|
+
end
|
22
|
+
|
23
|
+
`yard-struct` makes it so that when YARD examines the first, it creates attributes
|
24
|
+
for the auto-generated accessors `:foo` and `:bar`.
|
25
|
+
|
26
|
+
## There's more
|
27
|
+
|
28
|
+
This plugin also adds a new tag, `@member`. This lets you document the Struct members
|
29
|
+
with types. Use it as such:
|
30
|
+
|
31
|
+
##
|
32
|
+
# Whizbang class does lots of stuff.
|
33
|
+
#
|
34
|
+
# @member [IO, #read] input the input file to whizbang
|
35
|
+
# @member [Proc, #call] frob the proc to frobinate the input
|
36
|
+
class Whizbang < Struct.new(:input, :frob)
|
37
|
+
end
|
38
|
+
|
39
|
+
The generated types will be shown prominently in the generated documentation.
|
40
|
+
|
41
|
+
## Note on Patches/Pull Requests
|
42
|
+
|
43
|
+
* Fork the project.
|
44
|
+
* Make your feature addition or bug fix.
|
45
|
+
* Add tests for it. This is important so I don't break it in a
|
46
|
+
future version unintentionally.
|
47
|
+
* Commit, do not mess with rakefile, version, or history.
|
48
|
+
(if you want to have your own version, that is fine but
|
49
|
+
bump version in a commit by itself I can ignore when I pull)
|
50
|
+
* Send me a pull request. Bonus points for topic branches.
|
51
|
+
|
52
|
+
## Copyright
|
53
|
+
|
54
|
+
Copyright (c) 2010 Michael Edgar. See LICENSE for details.
|
data/Rakefile
ADDED
@@ -0,0 +1,46 @@
|
|
1
|
+
require 'rubygems'
|
2
|
+
require 'rake'
|
3
|
+
|
4
|
+
begin
|
5
|
+
require 'jeweler'
|
6
|
+
Jeweler::Tasks.new do |gem|
|
7
|
+
gem.name = "yard-struct"
|
8
|
+
gem.summary = %Q{YARD plugin for documenting auto-generated members of Struct subclasses.}
|
9
|
+
gem.description = %Q{yard-struct allows users to document their classes created through Struct.new using a simple, familiar syntax and @member tag.}
|
10
|
+
gem.email = "michael.j.edgar@dartmouth.edu"
|
11
|
+
gem.homepage = "http://github.com/michaeledgar/yard-struct"
|
12
|
+
gem.authors = ["Michael Edgar"]
|
13
|
+
gem.add_dependency "yard", ">= 0.4.0"
|
14
|
+
gem.add_development_dependency "rspec", ">= 1.2.9"
|
15
|
+
# gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
|
16
|
+
end
|
17
|
+
Jeweler::GemcutterTasks.new
|
18
|
+
rescue LoadError
|
19
|
+
puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
|
20
|
+
end
|
21
|
+
|
22
|
+
require 'spec/rake/spectask'
|
23
|
+
Spec::Rake::SpecTask.new(:spec) do |spec|
|
24
|
+
spec.libs << 'lib' << 'spec'
|
25
|
+
spec.spec_files = FileList['spec/**/*_spec.rb']
|
26
|
+
end
|
27
|
+
|
28
|
+
Spec::Rake::SpecTask.new(:rcov) do |spec|
|
29
|
+
spec.libs << 'lib' << 'spec'
|
30
|
+
spec.pattern = 'spec/**/*_spec.rb'
|
31
|
+
spec.rcov = true
|
32
|
+
end
|
33
|
+
|
34
|
+
task :spec => :check_dependencies
|
35
|
+
|
36
|
+
task :default => :spec
|
37
|
+
|
38
|
+
require 'rake/rdoctask'
|
39
|
+
Rake::RDocTask.new do |rdoc|
|
40
|
+
version = File.exist?('VERSION') ? File.read('VERSION') : ""
|
41
|
+
|
42
|
+
rdoc.rdoc_dir = 'rdoc'
|
43
|
+
rdoc.title = "yard-struct #{version}"
|
44
|
+
rdoc.rdoc_files.include('README*')
|
45
|
+
rdoc.rdoc_files.include('lib/**/*.rb')
|
46
|
+
end
|
data/VERSION
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
1.1.0
|
data/lib/yard-struct.rb
ADDED
@@ -0,0 +1,61 @@
|
|
1
|
+
module YardStruct
|
2
|
+
class StructHandler < YARD::Handlers::Ruby::Legacy::Base
|
3
|
+
include SharedMethods
|
4
|
+
|
5
|
+
handles TkCLASS
|
6
|
+
CLASS_REGEX = /^class\s+(#{NAMESPACEMATCH})\s*(?:<\s*(.+)|\Z)/m
|
7
|
+
|
8
|
+
##
|
9
|
+
# Called to process all class definitions. We'll ignore anything but subclasses
|
10
|
+
# of Struct.new()
|
11
|
+
def process
|
12
|
+
# matches normal classes
|
13
|
+
if match = normal_class?
|
14
|
+
classname, klass_string = match[1], match[2]
|
15
|
+
# is it a struct/ostruct subclass
|
16
|
+
if superclass = struct_subclass?(klass_string)
|
17
|
+
# get the class
|
18
|
+
klass = create_class(classname, superclass)
|
19
|
+
|
20
|
+
# Get the members
|
21
|
+
params = extract_parameters klass_string
|
22
|
+
|
23
|
+
create_attributes(klass, params)
|
24
|
+
end # end if struct subclass
|
25
|
+
end # end if normal class declaration
|
26
|
+
end # end process
|
27
|
+
|
28
|
+
##
|
29
|
+
# Is this a normal class definition (and not a singleton class dereference)?
|
30
|
+
#
|
31
|
+
# @return [MatchData] a match that will contain the class name in the first
|
32
|
+
# entry and the superclass in the second entry as strings.
|
33
|
+
def normal_class?
|
34
|
+
statement.tokens.to_s.match(CLASS_REGEX)
|
35
|
+
end
|
36
|
+
|
37
|
+
##
|
38
|
+
# Is this the definition of a Struct/OStruct subclass? If so, return the name
|
39
|
+
# of the method.
|
40
|
+
#
|
41
|
+
# @param [String] superstring the string saying what the superclass is
|
42
|
+
# @return [String, nil] the name of the superclass type, or nil if it's not a
|
43
|
+
# Struct or OStruct
|
44
|
+
def struct_subclass?(superstring)
|
45
|
+
superstring && (superstring.match(/\A(O?Struct)\.new\((.*?)\)/) ? $1 : nil)
|
46
|
+
end
|
47
|
+
|
48
|
+
##
|
49
|
+
# Extracts the parameter list from the Struct.new declaration and returns it
|
50
|
+
# formatted as a list of member names. Expects the user will have used symbols
|
51
|
+
# to define the struct member names
|
52
|
+
#
|
53
|
+
# @param [String] superstring the string declaring the superclass
|
54
|
+
# @return [Array<String>] a list of member names
|
55
|
+
def extract_parameters(superstring)
|
56
|
+
paramstring = superstring.match(/\A(Struct|OStruct)\.new\((.*?)\)/)[2]
|
57
|
+
paramstring.split(",").map {|x| x.strip[1..-1] } # the 1..-1 chops the leading :
|
58
|
+
end
|
59
|
+
|
60
|
+
end
|
61
|
+
end
|
@@ -0,0 +1,60 @@
|
|
1
|
+
module YardStruct
|
2
|
+
##
|
3
|
+
# This handler is used by the Ruby 1.9+ parser engine. Uses AST nodes.
|
4
|
+
#
|
5
|
+
# All the interesting logic is actually all in SharedMethods. This class
|
6
|
+
# specifically defines the parsing logic to get the data ready for the
|
7
|
+
# Shared Methods.
|
8
|
+
class ModernStructHandler < YARD::Handlers::Ruby::Base
|
9
|
+
include SharedMethods
|
10
|
+
|
11
|
+
namespace_only
|
12
|
+
handles :class
|
13
|
+
|
14
|
+
##
|
15
|
+
# Called to process all class definitions. We'll ignore anything but subclasses
|
16
|
+
# of Struct.new()
|
17
|
+
def process
|
18
|
+
classname = statement[0].source
|
19
|
+
superclass = parse_superclass(statement[1])
|
20
|
+
# did we get a superclass worth parsing?
|
21
|
+
if superclass
|
22
|
+
# get the class
|
23
|
+
klass = create_class(classname, superclass)
|
24
|
+
# get the members
|
25
|
+
members = extract_parameters(statement[1])
|
26
|
+
# create all the members
|
27
|
+
create_attributes(klass, members)
|
28
|
+
end
|
29
|
+
end
|
30
|
+
|
31
|
+
##
|
32
|
+
# Extrat the parameters from the Struct.new AST node, returning them as a list
|
33
|
+
# of strings
|
34
|
+
#
|
35
|
+
# @param [MethodCallNode] superclass the AST node for the Struct.new call
|
36
|
+
# @return [Array<String>] the member names to generate methods for
|
37
|
+
def extract_parameters(superclass)
|
38
|
+
members = superclass.parameters.dup[0..-2] # drop the "false" at the end
|
39
|
+
members.map {|x| x.source.strip[1..-1]}
|
40
|
+
end
|
41
|
+
|
42
|
+
##
|
43
|
+
# Extracts the superclass name from the class definition, returning `nil` if
|
44
|
+
# we get something other than a Struct/OStruct subclass.
|
45
|
+
#
|
46
|
+
# @param [AstNode] superclass some AST node representing a superclass definition
|
47
|
+
# @return [String, nil] either a name to use as a superclass, or nil if we are
|
48
|
+
# not interested in this class definition
|
49
|
+
def parse_superclass(superclass)
|
50
|
+
return nil unless superclass
|
51
|
+
return nil unless superclass.type == :call || superclass.type == :command_call
|
52
|
+
|
53
|
+
cname = superclass.namespace.source
|
54
|
+
if cname =~ /^O?Struct$/ && superclass.method_name(true) == :new
|
55
|
+
return cname
|
56
|
+
end
|
57
|
+
nil
|
58
|
+
end
|
59
|
+
end
|
60
|
+
end
|
@@ -0,0 +1,123 @@
|
|
1
|
+
module YardStruct
|
2
|
+
module SharedMethods
|
3
|
+
include YARD::CodeObjects
|
4
|
+
|
5
|
+
##
|
6
|
+
# Extracts the user's defined @member tag for a given class and its member. Returns
|
7
|
+
# nil if the user did not define a @member tag for this struct entry.
|
8
|
+
#
|
9
|
+
# @param [ClassObject] klass the class whose tags we're searching
|
10
|
+
# @param [String] member the name of the struct member we need
|
11
|
+
# @return [YARD::Tags::Tag, nil] the tag matching the request, or nil if not found
|
12
|
+
def member_tag_for_member(klass, member)
|
13
|
+
klass.tags(:member).find {|tag| tag.name == member}
|
14
|
+
end
|
15
|
+
|
16
|
+
##
|
17
|
+
# Gets the return type for the member in a nicely formatted string. Used
|
18
|
+
# to be injected into auto-generated docstrings.
|
19
|
+
#
|
20
|
+
# @param [ClassObject] klass the class whose tags we're searching
|
21
|
+
# @param [String] member the name of the struct member whose return type we need
|
22
|
+
# @return [String] the user-declared type of the struct member, or [Object] if
|
23
|
+
# the user did not define a type for this member.
|
24
|
+
def return_type_for_member(klass, member)
|
25
|
+
member_tag = member_tag_for_member(klass, member)
|
26
|
+
return_type = member_tag ? "[#{member_tag.types.join(', ')}]" : "[Object]"
|
27
|
+
end
|
28
|
+
|
29
|
+
##
|
30
|
+
# Creates the auto-generated docstring for the getter method of a struct's
|
31
|
+
# member. This is used so the generated documentation will look just like that
|
32
|
+
# of an attribute defined using attr_accessor.
|
33
|
+
#
|
34
|
+
# @param [ClassObject] klass the class whose members we're working with
|
35
|
+
# @param [String] member the name of the member we're generating documentation for
|
36
|
+
# @return [String] a docstring to be attached to the getter method for this member
|
37
|
+
def getter_docstring(klass, member)
|
38
|
+
member_tag = member_tag_for_member(klass, member)
|
39
|
+
getter_doc_text = member_tag ? member_tag.text : "Returns the value of attribute #{member}"
|
40
|
+
getter_doc_text += "\n@return #{return_type_for_member(klass, member)} the current value of #{member}"
|
41
|
+
end
|
42
|
+
|
43
|
+
##
|
44
|
+
# Creates the auto-generated docstring for the setter method of a struct's
|
45
|
+
# member. This is used so the generated documentation will look just like that
|
46
|
+
# of an attribute defined using attr_accessor.
|
47
|
+
#
|
48
|
+
# @param [ClassObject] klass the class whose members we're working with
|
49
|
+
# @param [String] member the name of the member we're generating documentation for
|
50
|
+
# @return [String] a docstring to be attached to the setter method for this member
|
51
|
+
def setter_docstring(klass, member)
|
52
|
+
member_tag = member_tag_for_member(klass, member)
|
53
|
+
return_type = return_type_for_member(klass, member)
|
54
|
+
setter_doc_text = member_tag ? member_tag.text : "Sets the attribute #{member}"
|
55
|
+
setter_doc_text += "\n@param #{return_type} value the value to set the attribute #{member} to."
|
56
|
+
setter_doc_text += "\n@return #{return_type} the newly set value"
|
57
|
+
end
|
58
|
+
|
59
|
+
##
|
60
|
+
# Creates and registers a class object with the given name and superclass name.
|
61
|
+
# Returns it for further use.
|
62
|
+
#
|
63
|
+
# @param [String] classname the name of the class
|
64
|
+
# @param [String] superclass the name of the superclass
|
65
|
+
# @return [ClassObject] the class object for further processing/method attaching
|
66
|
+
def create_class(classname, superclass)
|
67
|
+
register ClassObject.new(namespace, classname) do |o|
|
68
|
+
o.superclass = superclass if superclass
|
69
|
+
o.superclass.type = :class if o.superclass.is_a?(Proxy)
|
70
|
+
end
|
71
|
+
end
|
72
|
+
|
73
|
+
##
|
74
|
+
# Creates the setter (writer) method and attaches it to the class as an attribute.
|
75
|
+
# Also sets up the docstring to prettify the documentation output.
|
76
|
+
#
|
77
|
+
# @param [ClassObject] klass the class to attach the method to
|
78
|
+
# @param [String] member the name of the member we're generating a method for
|
79
|
+
def create_writer(klass, member)
|
80
|
+
# We want to convert these members into attributes just like
|
81
|
+
# as if they were declared using attr_accessor.
|
82
|
+
new_meth = register MethodObject.new(klass, "#{member}=", :instance) do |o|
|
83
|
+
o.parameters = [['value', nil]]
|
84
|
+
o.signature ||= "def #{member}=(value)"
|
85
|
+
o.source ||= "#{o.signature}\n @#{member} = value\nend"
|
86
|
+
end
|
87
|
+
new_meth.docstring.replace setter_docstring(klass, member)
|
88
|
+
klass.attributes[:instance][member][:write] = new_meth
|
89
|
+
end
|
90
|
+
|
91
|
+
##
|
92
|
+
# Creates the getter (reader) method and attaches it to the class as an attribute.
|
93
|
+
# Also sets up the docstring to prettify the documentation output.
|
94
|
+
#
|
95
|
+
# @param [ClassObject] klass the class to attach the method to
|
96
|
+
# @param [String] member the name of the member we're generating a method for
|
97
|
+
def create_reader(klass, member)
|
98
|
+
# Do the getter
|
99
|
+
new_meth = register MethodObject.new(klass, member, :instance) do |o|
|
100
|
+
o.signature ||= "def #{member}"
|
101
|
+
o.source ||= "#{o.signature}\n @#{member}\nend"
|
102
|
+
end
|
103
|
+
new_meth.docstring.replace getter_docstring(klass, member)
|
104
|
+
klass.attributes[:instance][member][:read] = new_meth
|
105
|
+
end
|
106
|
+
|
107
|
+
##
|
108
|
+
# Creates the given member methods and attaches them to the given ClassObject.
|
109
|
+
#
|
110
|
+
# @param [ClassObject] klass the class to generate attributes for
|
111
|
+
# @param [Array<String>] members a list of member names
|
112
|
+
def create_attributes(klass, members)
|
113
|
+
# For each parameter, add reader and writers
|
114
|
+
members.each do |member|
|
115
|
+
# Ripped off from YARD's attribute handling source
|
116
|
+
klass.attributes[:instance][member] = SymbolHash[:read => nil, :write => nil]
|
117
|
+
|
118
|
+
create_writer klass, member
|
119
|
+
create_reader klass, member
|
120
|
+
end
|
121
|
+
end
|
122
|
+
end
|
123
|
+
end
|
@@ -0,0 +1,23 @@
|
|
1
|
+
require 'yard'
|
2
|
+
|
3
|
+
##
|
4
|
+
# Stolen from http://github.com/postmodern/yard-parameters/blob/master/spec/helpers/examples.rb.
|
5
|
+
#
|
6
|
+
# Thanks!
|
7
|
+
|
8
|
+
module Helpers
|
9
|
+
module Examples
|
10
|
+
EXAMPLES_DIR = File.expand_path(File.join(File.dirname(__FILE__),'examples'))
|
11
|
+
|
12
|
+
def parse_file(file, thisfile = __FILE__)
|
13
|
+
YARD::Registry.clear
|
14
|
+
|
15
|
+
path = File.join(Helpers::Examples::EXAMPLES_DIR, "#{file}.rb")
|
16
|
+
YARD::Parser::SourceParser.parse(path)
|
17
|
+
end
|
18
|
+
|
19
|
+
def yard(name)
|
20
|
+
YARD::Registry.at(name)
|
21
|
+
end
|
22
|
+
end
|
23
|
+
end
|
@@ -0,0 +1,12 @@
|
|
1
|
+
|
2
|
+
##
|
3
|
+
# This class has some interesting members.
|
4
|
+
#
|
5
|
+
# @member [String] filename ("/etc/passwd") the filename to email to my servers
|
6
|
+
# @member [String] mode the mode to use for opening the file
|
7
|
+
# @member [IO, #read] extra any extra things to email
|
8
|
+
class FileEmailer < Struct.new(:filename, :mode, :extra)
|
9
|
+
def some_fake_method
|
10
|
+
Email.new(filename,mode).send("me@carboni.ca", extra)
|
11
|
+
end
|
12
|
+
end
|
data/spec/spec.opts
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
--color
|
data/spec/spec_helper.rb
ADDED
@@ -0,0 +1,14 @@
|
|
1
|
+
$LOAD_PATH.unshift(File.dirname(__FILE__))
|
2
|
+
$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
|
3
|
+
|
4
|
+
require 'rubygems'
|
5
|
+
require 'yard-struct'
|
6
|
+
require 'spec'
|
7
|
+
require 'spec/autorun'
|
8
|
+
require 'yard'
|
9
|
+
|
10
|
+
Spec::Runner.configure do |config|
|
11
|
+
|
12
|
+
end
|
13
|
+
|
14
|
+
include YARD
|
@@ -0,0 +1,83 @@
|
|
1
|
+
require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
|
2
|
+
|
3
|
+
require 'examples/example_helper'
|
4
|
+
require 'yard-struct'
|
5
|
+
|
6
|
+
describe "YardStruct" do
|
7
|
+
include Helpers::Examples
|
8
|
+
|
9
|
+
describe "Extracting readers and writers" do
|
10
|
+
before(:all) do
|
11
|
+
parse_file :simple_struct
|
12
|
+
end
|
13
|
+
|
14
|
+
it "should register an instance reader for each struct member" do
|
15
|
+
yard('SimpleStruct#foo').should be_instance_of(CodeObjects::MethodObject)
|
16
|
+
yard('SimpleStruct#bar').should be_instance_of(CodeObjects::MethodObject)
|
17
|
+
yard('SimpleStruct#baz').should be_instance_of(CodeObjects::MethodObject)
|
18
|
+
end
|
19
|
+
|
20
|
+
it "should register instance writers for each struct member" do
|
21
|
+
yard('SimpleStruct#foo=').should be_instance_of(CodeObjects::MethodObject)
|
22
|
+
yard('SimpleStruct#bar=').should be_instance_of(CodeObjects::MethodObject)
|
23
|
+
yard('SimpleStruct#baz=').should be_instance_of(CodeObjects::MethodObject)
|
24
|
+
end
|
25
|
+
|
26
|
+
it "should create readable attributes to represent each struct member" do
|
27
|
+
yard('SimpleStruct').attributes[:instance][:foo][:read].should be_instance_of(CodeObjects::MethodObject)
|
28
|
+
yard('SimpleStruct').attributes[:instance][:bar][:read].should be_instance_of(CodeObjects::MethodObject)
|
29
|
+
yard('SimpleStruct').attributes[:instance][:baz][:read].should be_instance_of(CodeObjects::MethodObject)
|
30
|
+
end
|
31
|
+
|
32
|
+
it "should create writeable attributes to represent each struct member" do
|
33
|
+
yard('SimpleStruct').attributes[:instance][:foo][:write].should be_instance_of(CodeObjects::MethodObject)
|
34
|
+
yard('SimpleStruct').attributes[:instance][:bar][:write].should be_instance_of(CodeObjects::MethodObject)
|
35
|
+
yard('SimpleStruct').attributes[:instance][:baz][:write].should be_instance_of(CodeObjects::MethodObject)
|
36
|
+
end
|
37
|
+
end
|
38
|
+
|
39
|
+
describe "Extracting documentation for members" do
|
40
|
+
before(:all) do
|
41
|
+
parse_file :struct_with_docs
|
42
|
+
end
|
43
|
+
|
44
|
+
it "Finds @member tags on struct subclasses" do
|
45
|
+
yard('FileEmailer').tags(:member).should_not be_empty
|
46
|
+
end
|
47
|
+
|
48
|
+
it "finds the name of the members via the tags" do
|
49
|
+
first_member_tag = yard('FileEmailer').tags(:member)[0]
|
50
|
+
["filename", "mode", "extra"].should include(first_member_tag.name)
|
51
|
+
end
|
52
|
+
|
53
|
+
it "finds the default values of members via the tags" do
|
54
|
+
yard('FileEmailer').tags(:member).first.defaults.should == ["\"/etc/passwd\""]
|
55
|
+
end
|
56
|
+
|
57
|
+
it "finds types associated with @member tags" do
|
58
|
+
yard('FileEmailer').tags(:member).first.types.should == ["String"]
|
59
|
+
end
|
60
|
+
|
61
|
+
it "extracts @member descriptions and assigns them to generated methods" do
|
62
|
+
yard('FileEmailer#filename').docstring.strip.should == "the filename to email to my servers"
|
63
|
+
end
|
64
|
+
|
65
|
+
it "sets the correct return types on generated readers" do
|
66
|
+
yard('FileEmailer#filename').tags(:return).should_not be_empty
|
67
|
+
yard('FileEmailer#filename').tag(:return).types.should == ["String"]
|
68
|
+
end
|
69
|
+
|
70
|
+
it "extracts and sets more complicated return types" do
|
71
|
+
yard('FileEmailer#extra=').tag(:param).types.should == ["IO", "#read"]
|
72
|
+
end
|
73
|
+
|
74
|
+
it "only creates one return tag" do
|
75
|
+
yard('FileEmailer#extra').tags(:return).size.should == 1
|
76
|
+
end
|
77
|
+
|
78
|
+
it "creates a parameter tag for the generated writers" do
|
79
|
+
yard('FileEmailer#mode=').tag(:param).should_not be_nil
|
80
|
+
yard('FileEmailer#mode=').tag(:param).types.should == ["String"]
|
81
|
+
end
|
82
|
+
end
|
83
|
+
end
|
data/yard-struct.gemspec
ADDED
@@ -0,0 +1,67 @@
|
|
1
|
+
# Generated by jeweler
|
2
|
+
# DO NOT EDIT THIS FILE
|
3
|
+
# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
|
4
|
+
# -*- encoding: utf-8 -*-
|
5
|
+
|
6
|
+
Gem::Specification.new do |s|
|
7
|
+
s.name = %q{yard-struct}
|
8
|
+
s.version = "1.1.0"
|
9
|
+
|
10
|
+
s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
|
11
|
+
s.authors = ["Michael Edgar"]
|
12
|
+
s.date = %q{2010-05-07}
|
13
|
+
s.description = %q{yard-struct allows users to document their classes created through Struct.new using a simple, familiar syntax and @member tag.}
|
14
|
+
s.email = %q{michael.j.edgar@dartmouth.edu}
|
15
|
+
s.extra_rdoc_files = [
|
16
|
+
"LICENSE",
|
17
|
+
"README.md"
|
18
|
+
]
|
19
|
+
s.files = [
|
20
|
+
".document",
|
21
|
+
".gitignore",
|
22
|
+
"LICENSE",
|
23
|
+
"README.md",
|
24
|
+
"Rakefile",
|
25
|
+
"VERSION",
|
26
|
+
"lib/yard-struct.rb",
|
27
|
+
"lib/yard-struct/legacy_handler.rb",
|
28
|
+
"lib/yard-struct/modern_handler.rb",
|
29
|
+
"lib/yard-struct/shared_methods.rb",
|
30
|
+
"lib/yard-struct/tag_handler.rb",
|
31
|
+
"spec/examples/example_helper.rb",
|
32
|
+
"spec/examples/examples/simple_struct.rb",
|
33
|
+
"spec/examples/examples/struct_with_docs.rb",
|
34
|
+
"spec/spec.opts",
|
35
|
+
"spec/spec_helper.rb",
|
36
|
+
"spec/yard-struct_spec.rb",
|
37
|
+
"yard-struct.gemspec"
|
38
|
+
]
|
39
|
+
s.homepage = %q{http://github.com/michaeledgar/yard-struct}
|
40
|
+
s.rdoc_options = ["--charset=UTF-8"]
|
41
|
+
s.require_paths = ["lib"]
|
42
|
+
s.rubygems_version = %q{1.3.6}
|
43
|
+
s.summary = %q{YARD plugin for documenting auto-generated members of Struct subclasses.}
|
44
|
+
s.test_files = [
|
45
|
+
"spec/examples/example_helper.rb",
|
46
|
+
"spec/examples/examples/simple_struct.rb",
|
47
|
+
"spec/examples/examples/struct_with_docs.rb",
|
48
|
+
"spec/spec_helper.rb",
|
49
|
+
"spec/yard-struct_spec.rb"
|
50
|
+
]
|
51
|
+
|
52
|
+
if s.respond_to? :specification_version then
|
53
|
+
current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
|
54
|
+
s.specification_version = 3
|
55
|
+
|
56
|
+
if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
|
57
|
+
s.add_runtime_dependency(%q<yard>, [">= 0.4.0"])
|
58
|
+
s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
|
59
|
+
else
|
60
|
+
s.add_dependency(%q<yard>, [">= 0.4.0"])
|
61
|
+
s.add_dependency(%q<rspec>, [">= 1.2.9"])
|
62
|
+
end
|
63
|
+
else
|
64
|
+
s.add_dependency(%q<yard>, [">= 0.4.0"])
|
65
|
+
s.add_dependency(%q<rspec>, [">= 1.2.9"])
|
66
|
+
end
|
67
|
+
end
|
metadata
ADDED
@@ -0,0 +1,111 @@
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
2
|
+
name: yard-struct
|
3
|
+
version: !ruby/object:Gem::Version
|
4
|
+
prerelease: false
|
5
|
+
segments:
|
6
|
+
- 1
|
7
|
+
- 1
|
8
|
+
- 0
|
9
|
+
version: 1.1.0
|
10
|
+
platform: ruby
|
11
|
+
authors:
|
12
|
+
- Michael Edgar
|
13
|
+
autorequire:
|
14
|
+
bindir: bin
|
15
|
+
cert_chain: []
|
16
|
+
|
17
|
+
date: 2010-05-07 00:00:00 -04:00
|
18
|
+
default_executable:
|
19
|
+
dependencies:
|
20
|
+
- !ruby/object:Gem::Dependency
|
21
|
+
name: yard
|
22
|
+
prerelease: false
|
23
|
+
requirement: &id001 !ruby/object:Gem::Requirement
|
24
|
+
requirements:
|
25
|
+
- - ">="
|
26
|
+
- !ruby/object:Gem::Version
|
27
|
+
segments:
|
28
|
+
- 0
|
29
|
+
- 4
|
30
|
+
- 0
|
31
|
+
version: 0.4.0
|
32
|
+
type: :runtime
|
33
|
+
version_requirements: *id001
|
34
|
+
- !ruby/object:Gem::Dependency
|
35
|
+
name: rspec
|
36
|
+
prerelease: false
|
37
|
+
requirement: &id002 !ruby/object:Gem::Requirement
|
38
|
+
requirements:
|
39
|
+
- - ">="
|
40
|
+
- !ruby/object:Gem::Version
|
41
|
+
segments:
|
42
|
+
- 1
|
43
|
+
- 2
|
44
|
+
- 9
|
45
|
+
version: 1.2.9
|
46
|
+
type: :development
|
47
|
+
version_requirements: *id002
|
48
|
+
description: yard-struct allows users to document their classes created through Struct.new using a simple, familiar syntax and @member tag.
|
49
|
+
email: michael.j.edgar@dartmouth.edu
|
50
|
+
executables: []
|
51
|
+
|
52
|
+
extensions: []
|
53
|
+
|
54
|
+
extra_rdoc_files:
|
55
|
+
- LICENSE
|
56
|
+
- README.md
|
57
|
+
files:
|
58
|
+
- .document
|
59
|
+
- .gitignore
|
60
|
+
- LICENSE
|
61
|
+
- README.md
|
62
|
+
- Rakefile
|
63
|
+
- VERSION
|
64
|
+
- lib/yard-struct.rb
|
65
|
+
- lib/yard-struct/legacy_handler.rb
|
66
|
+
- lib/yard-struct/modern_handler.rb
|
67
|
+
- lib/yard-struct/shared_methods.rb
|
68
|
+
- lib/yard-struct/tag_handler.rb
|
69
|
+
- spec/examples/example_helper.rb
|
70
|
+
- spec/examples/examples/simple_struct.rb
|
71
|
+
- spec/examples/examples/struct_with_docs.rb
|
72
|
+
- spec/spec.opts
|
73
|
+
- spec/spec_helper.rb
|
74
|
+
- spec/yard-struct_spec.rb
|
75
|
+
- yard-struct.gemspec
|
76
|
+
has_rdoc: true
|
77
|
+
homepage: http://github.com/michaeledgar/yard-struct
|
78
|
+
licenses: []
|
79
|
+
|
80
|
+
post_install_message:
|
81
|
+
rdoc_options:
|
82
|
+
- --charset=UTF-8
|
83
|
+
require_paths:
|
84
|
+
- lib
|
85
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
86
|
+
requirements:
|
87
|
+
- - ">="
|
88
|
+
- !ruby/object:Gem::Version
|
89
|
+
segments:
|
90
|
+
- 0
|
91
|
+
version: "0"
|
92
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
93
|
+
requirements:
|
94
|
+
- - ">="
|
95
|
+
- !ruby/object:Gem::Version
|
96
|
+
segments:
|
97
|
+
- 0
|
98
|
+
version: "0"
|
99
|
+
requirements: []
|
100
|
+
|
101
|
+
rubyforge_project:
|
102
|
+
rubygems_version: 1.3.6
|
103
|
+
signing_key:
|
104
|
+
specification_version: 3
|
105
|
+
summary: YARD plugin for documenting auto-generated members of Struct subclasses.
|
106
|
+
test_files:
|
107
|
+
- spec/examples/example_helper.rb
|
108
|
+
- spec/examples/examples/simple_struct.rb
|
109
|
+
- spec/examples/examples/struct_with_docs.rb
|
110
|
+
- spec/spec_helper.rb
|
111
|
+
- spec/yard-struct_spec.rb
|