1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
|
require 'pp'
require 'json'
$bad_input = false
def bad_input file, text
$bad_input = true
$stderr.puts "#{file}: unrecognized input: #{text}"
end
def parse_dir dirname
Dir.entries(dirname).map{|filename|
if filename == '.' || filename == '..'
nil
else
parse_any_path "#{dirname}/#{filename}"
end
}.compact.inject(:+)
end
def cleanup_class_name class_name
class_name.sub(/OO\.ui\./, '')
end
def parse_file filename
if filename !~ /\.(php|js)$/
return nil
end
filetype = filename[/\.(php|js)$/, 1].to_sym
text = File.read filename, encoding: 'utf-8'
# ewwww
# some docblocks are missing and we really need them
text = text.sub(/(?<!\*\/\n)^class/, "/**\n*/\nclass")
# text = text.sub('public static $targetPropertyName', "/**\n*/\npublic static $targetPropertyName")
# find all documentation blocks, together with the following line (unless it contains another docblock)
docblocks = text.scan(/\/\*\*[\s\S]+?\*\/\n[ \t]*(?:(?=\/\*\*)|.*)/)
current_class = nil
output = []
previous_item = {} # dummy
docblocks.each{|d|
kind = nil
previous_item = data = {
name: nil,
description: '',
parent: nil,
mixins: [],
methods: [],
properties: [],
events: [],
params: [],
config: [],
visibility: :public,
type: nil,
}
valid_for_all = %w[name description].map(&:to_sym)
valid_per_kind = {
class: valid_for_all + %w[parent mixins methods properties events abstract].map(&:to_sym),
method: valid_for_all + %w[params config return visibility static].map(&:to_sym),
property: valid_for_all + %w[type static].map(&:to_sym),
event: valid_for_all + %w[params].map(&:to_sym),
}
js_class_constructor = false
js_class_constructor_desc = ''
ignore = false
comment, code_line = d.split '*/'
comment.split("\n").each{|comment_line|
next if comment_line.strip == '/**'
comment_line.sub!(/^[ \t]*\*[ \t]?/, '') # strip leading '*' and whitespace
m = comment_line.match(/^@(\w+)[ \t]*(.*)/)
if !m
previous_item[:description] << comment_line + "\n"
next
end
keyword, content = m.captures
# handle JS class/constructor conundrum
if keyword == 'class' || keyword == 'constructor'
js_class_constructor = true
end
case keyword
when 'constructor'
# handle JS class/constructor conundrum
js_class_constructor_desc = data[:description]
data[:description] = ''
kind = :method
when 'class'
kind = :class
when 'method'
kind = :method
when 'property', 'var'
kind = :property
m = content.match(/^\{?(.+?)\}?( .+)?$/)
if !m
bad_input filename, comment_line
next
end
type, description = m.captures
data[:type] = type
data[:description] = description if description
when 'event'
kind = :event
data[:name] = content.strip
when 'extends'
data[:parent] = cleanup_class_name(content.strip)
when 'mixins'
data[:mixins] << cleanup_class_name(content.strip)
when 'param'
case filetype
when :js
type, name, default, description = content.match(/^\{(.+?)\} \[?([\w.$]+?)(?:=(.+?))?\]?( .+)?$/).captures
next if type == 'Object' && name == 'config'
data[:params] << {name: name, type: cleanup_class_name(type), description: description || '', default: default}
previous_item = data[:params][-1]
when :php
type, name, config, description = content.match(/^(\S+) \&?\$(\w+)(?:\['(\w+)'\])?( .+)?$/).captures
next if type == 'array' && name == 'config' && !config
if config && name == 'config'
data[:config] << {name: config, type: cleanup_class_name(type), description: description || ''}
previous_item = data[:config][-1]
else
data[:params] << {name: name, type: cleanup_class_name(type), description: description || ''}
previous_item = data[:params][-1]
end
end
when 'cfg' # JS only
m = content.match(/^\{(.+?)\} \[?([\w.$]+?)(?:=(.+?))?\]?( .+)?$/)
if !m
bad_input filename, comment_line
next
end
type, name, default, description = m.captures
data[:config] << {name: name, type: cleanup_class_name(type), description: description || '', default: default}
previous_item = data[:config][-1]
when 'return'
case filetype
when :js
m = content.match(/^\{(.+?)\}( .+)?$/)
when :php
m = content.match(/^(\S+)( .+)?$/)
end
if !m
bad_input filename, comment_line
next
end
type, description = m.captures
data[:return] = {type: cleanup_class_name(type), description: description || ''}
previous_item = data[:return]
when 'private'
data[:visibility] = :private
when 'protected'
data[:visibility] = :protected
when 'static'
data[:static] = true
when 'abstract'
data[:abstract] = true
when 'ignore'
ignore = true
when 'inheritable', 'deprecated', 'singleton', 'throws',
'chainable', 'fires', 'localdoc', 'inheritdoc', 'member',
'see'
# skip
else
bad_input filename, comment_line
next
end
}
next if ignore
if code_line && code_line.strip != ''
case filetype
when :js
m = code_line.match(/(?:(static|prototype)\.)?(\w+) =/)
if !m
bad_input filename, code_line.strip
next
end
kind_, name = m.captures
data[:static] = true if kind_ == 'static'
kind = {'static' => :property, 'prototype' => :method}[ kind_.strip ] if kind_ && !kind
data[:name] = cleanup_class_name(name)
when :php
m = code_line.match(/
\s*
(?:(public|protected|private)\s)?
(?:(static)\s)?(function\s|class\s|\$)
(\w+)
(?:\sextends\s(\w+))?
/x)
if !m
bad_input filename, code_line.strip
next
end
visibility, static, kind_, name, parent = m.captures
kind = {'$' => :property, 'function' => :method, 'class' => :class}[ kind_.strip ]
data[:visibility] = {'private' => :private, 'protected' => :protected, 'public' => :public}[ visibility ] || :public
data[:static] = true if static
data[:parent] = cleanup_class_name(parent) if parent
data[:name] = cleanup_class_name(name)
end
end
# handle JS class/constructor conundrum
if kind == :class || js_class_constructor
if current_class
output << current_class
end
current_class = data.select{|k, _v| valid_per_kind[:class].include? k }
current_class[:description] = js_class_constructor_desc if js_class_constructor_desc != ''
previous_item = current_class
end
# standardize
if data[:name] == '__construct' || js_class_constructor
data[:name] = '#constructor'
end
# put into the current class
if kind && kind != :class
keys = {
method: :methods,
property: :properties,
event: :events,
}
current_class[keys[kind]] << data.select{|k, _v| valid_per_kind[kind].include? k }
previous_item = current_class[keys[kind]]
end
}
# this is evil, assumes we only have one class in a file, but we'd need a proper parser to do it better
if current_class
current_class[:mixins] +=
text.scan(/\$this->mixin\( .*?new (\w+)\( \$this/).flatten.map(&method(:cleanup_class_name))
end
output << current_class if current_class
output
end
def parse_any_path path
if File.directory? path
result = parse_dir path
else
result = parse_file path
end
if $bad_input
$stderr.puts 'Unrecognized inputs encountered, stopping.'
exit 1
end
result
end
if __FILE__ == $PROGRAM_NAME
if ARGV.empty? || ARGV == ['-h'] || ARGV == ['--help']
$stderr.puts "usage: ruby #{$PROGRAM_NAME} <files...>"
$stderr.puts " ruby #{$PROGRAM_NAME} src > docs-js.json"
$stderr.puts " ruby #{$PROGRAM_NAME} php > docs-php.json"
else
out = JSON.pretty_generate ARGV.map{|a| parse_any_path a }.inject(:+)
# ew
out = out.gsub(/\{\s+\}/, '{}').gsub(/\[\s+\]/, '[]')
puts out
end
end
|