yard 0.8.0 → 0.8.1

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of yard might be problematic. Click here for more details.

data/ChangeLog CHANGED
@@ -1,6 +1,72 @@
1
+ 2012-05-02 Loren Segal <lsegal@soen.ca>
2
+
3
+ * ChangeLog, README.md, docs/WhatsNew.md, lib/yard.rb: Bump to 0.8.1, update
4
+ README, WhatsNew
5
+
6
+ * lib/yard/tags/library.rb: Update note about transitive tags to include info
7
+ about overriding
8
+
9
+ * lib/yard/cli/yardoc.rb, spec/cli/yardoc_spec.rb: Add --no-api to allow
10
+ including of objects with undefined API
11
+
12
+ * lib/yard/i18n/message.rb: Fix typo, references #534
13
+
14
+ * lib/yard/i18n/message.rb, lib/yard/i18n/messages.rb: Various minor
15
+ documentation formatting and text fixes References #534
16
+
17
+ * spec/i18n/messages_spec.rb: Sort results in I18n::Messages#each spec to fix
18
+ compare for 1.8.6
19
+
20
+ * spec/cli/yardoc_spec.rb: Fix spec errors in 1.8.x
21
+
22
+ * spec/cli/stats_spec.rb, spec/cli/yardoc_spec.rb: Allow verifier to treat
23
+ all objects as having visibility, so --no-public should hide constants too,
24
+ now
25
+
26
+ * lib/yard/cli/yardoc.rb, spec/cli/yardoc_spec.rb: Add `--api` switch to
27
+ yardoc in order to generate docs for API tags without needing `--query`
28
+ syntax. Multiple `--api` switches can be used to generate docs for multiple
29
+ APIs at once (they are logically OR'd together). Closes #532
30
+
31
+ * lib/yard/verifier.rb, spec/verifier_spec.rb: Fix verifier supporting
32
+ namespaced tags with special @{tag} syntax
33
+
34
+ * lib/yard/cli/stats.rb: Show 0% documented if total == 0
35
+
36
+ * lib/yard/cli/list.rb, spec/cli/list_spec.rb: yard list command should use
37
+ cache by default Closes #533
38
+
39
+ * lib/yard/verifier.rb, spec/verifier_spec.rb: Allow namespaced tags
40
+
41
+ 2012-05-01 Loren Segal <lsegal@soen.ca>
42
+
43
+ * lib/yard/code_objects/macro_object.rb, lib/yard/docstring.rb,
44
+ lib/yard/docstring_parser.rb, lib/yard/handlers/base.rb,
45
+ lib/yard/tags/directives.rb: Add Docstring.default_parser and
46
+ Docstring.parser Plugin developers can now specify custom parser classes to
47
+ be used when parsing docstrings. These classes must inherit from
48
+ DocstringParser. This changeset also exposes public methods to
49
+ DocstringParser for better use with subclasses. References #529
50
+
51
+ * lib/yard/tags/library.rb: Update documentation for `@private` tag
52
+
53
+ * lib/yard/tags/library.rb: Update Tags::Library documentation
54
+
55
+ * lib/yard/docstring_parser.rb, spec/docstring_parser_spec.rb: Add specs for
56
+ after_parse parameter checking and fix broken duplicate param tag
57
+ functionality
58
+
59
+ * templates/default/tags/html/option.erb: Remove trailing mdash from options
60
+ listing if no description is present Closes #522
61
+
62
+ * .../default/fulldoc/html/full_list_method.erb,
63
+ .../default/fulldoc/html/full_list_methods.erb,
64
+ templates/default/fulldoc/html/setup.rb: Serialize method_list with proper
65
+ filename Closes #528
66
+
1
67
  2012-04-30 Loren Segal <lsegal@soen.ca>
2
68
 
3
- * ChangeLog, lib/yard.rb: Update ChangeLog
69
+ * ChangeLog, lib/yard.rb: Bump version to 0.8.0
4
70
 
5
71
  * README.md, docs/WhatsNew.md: Update README/WhatsNew
6
72
 
data/README.md CHANGED
@@ -8,8 +8,8 @@ YARD: Yay! A Ruby Documentation Tool
8
8
  **Contributors**: See Contributors section below
9
9
  **Copyright**: 2007-2012
10
10
  **License**: MIT License
11
- **Latest Version**: 0.8.0 (codename "Shave It")
12
- **Release Date**: April 30th 2012
11
+ **Latest Version**: 0.8.1 (codename "Shave It")
12
+ **Release Date**: May 2nd 2012
13
13
 
14
14
  Synopsis
15
15
  --------
@@ -286,6 +286,12 @@ More options can be seen by typing `yard graph --help`, but here is an example:
286
286
 
287
287
  ## Changelog
288
288
 
289
+ - **May.2.12**: 0.8.1 release
290
+ - Added `--[no-]api` switch to generate docs for API sets (see {file:docs/WhatsNew.md} for details) (#532)
291
+ - The `yard list` command now uses cache by default (#533)
292
+ - Fix `yardoc` generating incorrectly named method list file (#528)
293
+ - Fix HTML output occasionally showing trailing mdash on options list (#522)
294
+
289
295
  - **April.30.12**: 0.8.0 release
290
296
  - See {file:docs/WhatsNew.md} for a list of added features
291
297
  - Over 20 bug fixes:
@@ -15,6 +15,7 @@
15
15
  11. **Server now displays README on index route like static docs** (0.8.0)
16
16
  12. **Added line numbers to `yard stats --list-undoc --compact`** (0.8.0)
17
17
  13. **Single object db now default (multi-object db unsupported)** (0.8.0)
18
+ 14. **Added `--api` tag to generate documentation for API sets** (0.8.1)
18
19
 
19
20
  ## Directives (new behavioural tag syntax) (0.8.0)
20
21
 
@@ -244,6 +245,39 @@ option to split your database into multiple files, but note that this
244
245
  can cause problems with certain codebases (specifically, if you
245
246
  have class methods using the same name as a module/class).
246
247
 
248
+ ## Added `--api` tag to generate documentation for API sets (0.8.1)
249
+
250
+ You can now use `yardoc --api APINAME` to generate documentation only
251
+ for objects with the `@api APINAME` tag (or any parent namespace objects,
252
+ since this tag is transitive). Multiple `--api` switches may be used to
253
+ generate documentation for multiple APIs together. The following generates
254
+ documentation for both the "public" and "developer" APIs, also including
255
+ any objects with undefined API (via `--no-api`):
256
+
257
+ $ yard doc --api public --api developer --no-api
258
+
259
+ Note that if you use `--api`, you must ensure that you also add `@api`
260
+ tags to your namespace objects (modules and classes), not just your methods.
261
+ If you do not want to do this, you can also include all objects with *no*
262
+ `@api` tag by using `--no-api` as shown above.
263
+
264
+ Remember that applying an `@api` tag to a class or module will apply it
265
+ to all children that do not have this tag already defined, so you can
266
+ declare an entire class public by applying it to the class itself. Note
267
+ also that these tags can be overridden by child elements if the tag is
268
+ re-applied to the individual object.
269
+
270
+ This feature is a simplified version of the more powerful `--query`
271
+ switch. The query to display the same API documentation as the
272
+ above example would be:
273
+
274
+ $ yard doc --query '!@api || @api.text =~ /^(public|private)$/'
275
+
276
+ But note that `--query` does not work when YARD is in "safe mode"
277
+ due to security concerns, whereas `--api` works in either mode.
278
+ This enables `--api` to function on remote documentation sites like
279
+ [rubydoc.info](http://rubydoc.info).
280
+
247
281
 
248
282
  # What's New in 0.7.x?
249
283
 
@@ -1,5 +1,5 @@
1
1
  module YARD
2
- VERSION = "0.8.0"
2
+ VERSION = "0.8.1"
3
3
 
4
4
  # The root path for YARD source libraries
5
5
  ROOT = File.expand_path(File.dirname(__FILE__))
@@ -135,6 +135,8 @@ module YARD
135
135
  module I18n
136
136
  autoload :PotGenerator, __p('i18n/pot_generator')
137
137
  autoload :Text, __p('i18n/text')
138
+ autoload :Messages, __p('i18n/messages')
139
+ autoload :Message, __p('i18n/message')
138
140
  end
139
141
 
140
142
  # The parser namespace holds all parsing engines used by YARD.
@@ -14,7 +14,7 @@ module YARD
14
14
  puts "Usage: yard list [yardoc_options]"
15
15
  puts "Takes the same arguments as yardoc. See yardoc --help"
16
16
  else
17
- Yardoc.run('--list', *args)
17
+ Yardoc.run('-c', '--list', *args)
18
18
  end
19
19
  end
20
20
  end
@@ -59,7 +59,11 @@ module YARD
59
59
  end
60
60
  end
61
61
  meths.each {|m| send(m) }
62
- total = (@total - @undocumented).to_f / @total.to_f * 100
62
+ if @total == 0
63
+ total = 0
64
+ else
65
+ total = (@total - @undocumented).to_f / @total.to_f * 100
66
+ end
63
67
  puts("% 3.2f%% documented" % total)
64
68
  end
65
69
 
@@ -183,6 +183,11 @@ module YARD
183
183
  # @since 0.5.6
184
184
  attr_accessor :visibilities
185
185
 
186
+ # Keep track of which APIs are to be shown
187
+ # @return [Array<String>] a list of APIs
188
+ # @since 0.8.1
189
+ attr_accessor :apis
190
+
186
191
  # @return [Array<Symbol>] a list of tags to hide from templates
187
192
  # @since 0.6.0
188
193
  attr_accessor :hidden_tags
@@ -205,6 +210,7 @@ module YARD
205
210
  @options = YardocOptions.new
206
211
  @options.reset_defaults
207
212
  @visibilities = [:public]
213
+ @apis = []
208
214
  @assets = {}
209
215
  @excluded = []
210
216
  @files = []
@@ -287,6 +293,7 @@ module YARD
287
293
 
288
294
  Tags::Library.visible_tags -= hidden_tags
289
295
  add_visibility_verifier
296
+ add_api_verifier
290
297
 
291
298
  # US-ASCII is invalid encoding for onefile
292
299
  if defined?(::Encoding) && options.onefile
@@ -464,10 +471,21 @@ module YARD
464
471
  # @return [void]
465
472
  # @since 0.5.6
466
473
  def add_visibility_verifier
467
- vis_expr = "object.type != :method || #{visibilities.uniq.inspect}.include?(object.visibility)"
474
+ vis_expr = "#{visibilities.uniq.inspect}.include?(object.visibility)"
468
475
  options.verifier.add_expressions(vis_expr)
469
476
  end
470
477
 
478
+ # Adds verifier rule for APIs
479
+ # @return [void]
480
+ # @since 0.8.1
481
+ def add_api_verifier
482
+ return if apis.empty?
483
+ no_api = true if apis.delete('')
484
+ expr = "#{apis.uniq.inspect}.include?(@api.text)"
485
+ expr += " || !@api" if no_api
486
+ options.verifier.add_expressions(expr)
487
+ end
488
+
471
489
  # (see Templates::Helpers::BaseHelper#run_verifier)
472
490
  def run_verifier(list)
473
491
  options.verifier ? options.verifier.run(list) : list
@@ -598,6 +616,14 @@ module YARD
598
616
  (object.namespace.is_a?(CodeObjects::Proxy) || !object.namespace.tag(:private))'
599
617
  end
600
618
 
619
+ opts.on('--[no-]api API', 'Generates documentation for a given API',
620
+ '(objects which define the correct @api tag).',
621
+ 'If --no-api is given, displays objects with',
622
+ 'no @api tag.') do |api|
623
+ api = '' if api == false
624
+ apis.push(api)
625
+ end
626
+
601
627
  opts.on('--embed-mixins', "Embeds mixin methods into class documentation") do
602
628
  options.embed_mixins << '*'
603
629
  end
@@ -119,7 +119,7 @@ module YARD
119
119
  # @see find_or_create
120
120
  def apply(docstring, call_params = [], full_source = '', block_source = '', method_object = nil)
121
121
  docstring = docstring.all if Docstring === docstring
122
- parser = DocstringParser.new
122
+ parser = Docstring.parser
123
123
  handler = OpenStruct.new
124
124
  handler.call_params = call_params[1..-1]
125
125
  handler.caller_method = call_params.first
@@ -13,6 +13,32 @@ module YARD
13
13
  # Tags can be nested in a documentation string, though the {Tags::Tag}
14
14
  # itself is responsible for parsing the inner tags.
15
15
  class Docstring < String
16
+ class << self
17
+ # @note Plugin developers should make sure to reset this value
18
+ # after parsing finishes. This can be done via the
19
+ # {Parser::SourceParser.after_parse_list} callback. This will
20
+ # ensure that YARD can properly parse multiple projects in
21
+ # the same process.
22
+ # @return [Class<DocstringParser>] the parser class used to parse
23
+ # text and optional meta-data from docstrings. Defaults to
24
+ # {DocstringParser}.
25
+ # @see DocstringParser
26
+ # @see Parser::SourceParser.after_parse_list
27
+ attr_accessor :default_parser
28
+
29
+ # Creates a parser object using the current {default_parser}.
30
+ # Equivalent to:
31
+ # Docstring.default_parser.new(*args)
32
+ # @param args arguments are passed to the {DocstringParser}
33
+ # class. See {DocstringParser#initialize} for details on
34
+ # arguments.
35
+ # @return [DocstringParser] the parser object used to parse a
36
+ # docstring.
37
+ def parser(*args) default_parser.new(*args) end
38
+ end
39
+
40
+ self.default_parser = DocstringParser
41
+
16
42
  # @return [Array<Tags::RefTag>] the list of reference tags
17
43
  attr_reader :ref_tags
18
44
 
@@ -59,7 +85,7 @@ module YARD
59
85
  #
60
86
  # @note To properly parse directives with proper parser context within
61
87
  # handlers, you should not use this method to create a Docstring.
62
- # Instead, use {DocstringParser}, which takes a handler object that
88
+ # Instead, use the {parser}, which takes a handler object that
63
89
  # can pass parser state onto directives. If a Docstring is created
64
90
  # with this method, directives do not have access to any parser
65
91
  # state, and may not function as expected.
@@ -282,7 +308,7 @@ module YARD
282
308
  # @return [String] the non-metadata portion of the comments to
283
309
  # be used as a docstring
284
310
  def parse_comments(comments)
285
- parser = DocstringParser.new
311
+ parser = self.class.parser
286
312
  parser.parse(comments, object)
287
313
  add_tag(*parser.tags)
288
314
  parser.text
@@ -5,29 +5,28 @@ module YARD
5
5
  # for a {CodeObjects::Base}. To create a new docstring, you should initialize
6
6
  # the parser and call {#parse} followed by {#to_docstring}.
7
7
  #
8
+ # == Subclassing Notes
9
+ #
10
+ # The DocstringParser can be subclassed and subtituted during parsing by
11
+ # setting the {Docstring.default_parser} attribute with the name of the
12
+ # subclass. This allows developers to change the way docstrings are
13
+ # parsed, allowing for completely different docstring syntaxes.
14
+ #
8
15
  # @example Creating a Docstring with a DocstringParser
9
16
  # DocstringParser.new.parse("text here").to_docstring
17
+ # @example Creating a Custom DocstringParser
18
+ # # Parses docstrings backwards!
19
+ # class ReverseDocstringParser
20
+ # def parse_content(content)
21
+ # super(content.reverse)
22
+ # end
23
+ # end
24
+ #
25
+ # # Set the parser as default when parsing
26
+ # YARD::Docstring.default_parser = ReverseDocstringParser
27
+ # @see #parse_content
10
28
  # @since 0.8.0
11
29
  class DocstringParser
12
- # Creates a callback that is called after a docstring is successfully
13
- # parsed. Use this method to perform sanity checks on a docstring's
14
- # tag data, or add any extra tags automatically to a docstring.
15
- #
16
- # @yield [parser] a block to be called after a docstring is parsed
17
- # @yieldparam [DocstringParser] parser the docstring parser object
18
- # with all directives and tags created.
19
- # @yieldreturn [void]
20
- # @return [void]
21
- def self.after_parse(&block)
22
- self.after_parse_callbacks << block
23
- end
24
-
25
- # @return [Array<Proc>] the {#after_parse} callback proc objects
26
- # @private
27
- def self.after_parse_callbacks
28
- @after_parse_callbacks ||= []
29
- end
30
-
31
30
  # @return [String] the parsed text portion of the docstring,
32
31
  # with tags removed.
33
32
  attr_reader :text
@@ -67,6 +66,8 @@ module YARD
67
66
  # The regular expression to match the tag syntax
68
67
  META_MATCH = /^@(!)?((?:\w\.?)+)(?:\s+(.*))?$/i
69
68
 
69
+ # @!group Creation and Conversion Methods
70
+
70
71
  # Creates a new parser to parse docstring data
71
72
  #
72
73
  # @param [Tags::Library] library a tag library for recognizing
@@ -82,6 +83,14 @@ module YARD
82
83
  @state = OpenStruct.new
83
84
  end
84
85
 
86
+ # @return [Docstring] translates parsed text into
87
+ # a Docstring object.
88
+ def to_docstring
89
+ Docstring.new!(text, tags, object, raw_text)
90
+ end
91
+
92
+ # @!group Parsing Methods
93
+
85
94
  # Parses all content and returns itself.
86
95
  #
87
96
  # @param [String] content the docstring text to parse
@@ -106,15 +115,11 @@ module YARD
106
115
  self
107
116
  end
108
117
 
109
- # @return [Docstring] translates parsed text into
110
- # a Docstring object.
111
- def to_docstring
112
- Docstring.new!(text, tags, object, raw_text)
113
- end
114
-
115
- private
116
-
117
- # Parses all text and tags
118
+ # Parses a given block of text.
119
+ #
120
+ # @param [String] content the content to parse
121
+ # @note Subclasses can override this method to perform custom
122
+ # parsing of content data.
118
123
  def parse_content(content)
119
124
  content = content.split(/\r?\n/) if content.is_a?(String)
120
125
  return '' if !content || content.empty?
@@ -168,7 +173,7 @@ module YARD
168
173
  docstring
169
174
  end
170
175
 
171
- private
176
+ # @!group Tag Manipulation Methods
172
177
 
173
178
  # Creates a tag from the {Tags::DefaultFactory tag factory}.
174
179
  #
@@ -177,7 +182,7 @@ module YARD
177
182
  # @param [String] tag_name the tag name
178
183
  # @param [String] tag_buf the text attached to the tag with newlines removed.
179
184
  # @return [Tags::Tag, Tags::RefTag] a tag
180
- def create_tag(tag_name, tag_buf)
185
+ def create_tag(tag_name, tag_buf = '')
181
186
  if tag_buf =~ /\A\s*(?:(\S+)\s+)?\(\s*see\s+(\S+)\s*\)\s*\Z/
182
187
  return create_ref_tag(tag_name, $1, $2)
183
188
  end
@@ -218,6 +223,17 @@ module YARD
218
223
  nil
219
224
  end
220
225
 
226
+ # Backward compatibility to detect old tags that should be specified
227
+ # as directives in 0.8 and onward.
228
+ def tag_is_directive?(tag_name)
229
+ list = %w(attribute endgroup group macro method scope visibility)
230
+ list.include?(tag_name)
231
+ end
232
+
233
+ private
234
+
235
+ # @!group Parser Callback Methods
236
+
221
237
  # Calls the {Directive#after_parse} callback on all the
222
238
  # created directives.
223
239
  def call_directives_after_parse
@@ -226,13 +242,6 @@ module YARD
226
242
  end
227
243
  end
228
244
 
229
- # Backward compatibility to detect old tags that should be specified
230
- # as directives in 0.8 and onward.
231
- def tag_is_directive?(tag_name)
232
- list = %w(attribute endgroup group macro method scope visibility)
233
- list.include?(tag_name)
234
- end
235
-
236
245
  # Calls all {after_parse} callbacks
237
246
  def call_after_parse_callbacks
238
247
  self.class.after_parse_callbacks.each do |cb|
@@ -240,6 +249,26 @@ module YARD
240
249
  end
241
250
  end
242
251
 
252
+ public
253
+
254
+ # Creates a callback that is called after a docstring is successfully
255
+ # parsed. Use this method to perform sanity checks on a docstring's
256
+ # tag data, or add any extra tags automatically to a docstring.
257
+ #
258
+ # @yield [parser] a block to be called after a docstring is parsed
259
+ # @yieldparam [DocstringParser] parser the docstring parser object
260
+ # with all directives and tags created.
261
+ # @yieldreturn [void]
262
+ # @return [void]
263
+ def self.after_parse(&block)
264
+ self.after_parse_callbacks << block
265
+ end
266
+
267
+ # @return [Array<Proc>] the {#after_parse} callback proc objects
268
+ def self.after_parse_callbacks
269
+ @after_parse_callbacks ||= []
270
+ end
271
+
243
272
  # Define a callback to check that @param tags are properly named
244
273
  after_parse do |parser|
245
274
  next unless parser.object
@@ -254,11 +283,11 @@ module YARD
254
283
  parser.tags.each do |tag|
255
284
  next if tag.is_a?(Tags::RefTagList) # we don't handle this yet
256
285
  next unless tag.tag_name == "param"
257
- if names.include?(tag.name)
258
- seen_names << tag.name
259
- elsif seen_names.include?(tag.name)
286
+ if seen_names.include?(tag.name)
260
287
  log.warn "@param tag has duplicate parameter name: " +
261
288
  "#{tag.name} #{infile_info}"
289
+ elsif names.include?(tag.name)
290
+ seen_names << tag.name
262
291
  else
263
292
  log.warn "@param tag has unknown parameter name: " +
264
293
  "#{tag.name} #{infile_info}"