yard 0.9.37 → 0.9.41

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.
Files changed (71) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +52 -1
  3. data/README.md +27 -30
  4. data/docs/GettingStarted.md +41 -15
  5. data/docs/Tags.md +5 -5
  6. data/docs/Templates.md +5 -4
  7. data/docs/WhatsNew.md +59 -7
  8. data/docs/templates/default/yard_tags/html/setup.rb +1 -1
  9. data/lib/yard/autoload.rb +17 -0
  10. data/lib/yard/cli/diff.rb +7 -2
  11. data/lib/yard/code_objects/base.rb +1 -1
  12. data/lib/yard/code_objects/extra_file_object.rb +1 -0
  13. data/lib/yard/code_objects/proxy.rb +1 -1
  14. data/lib/yard/handlers/base.rb +23 -1
  15. data/lib/yard/handlers/processor.rb +1 -0
  16. data/lib/yard/handlers/rbs/attribute_handler.rb +43 -0
  17. data/lib/yard/handlers/rbs/base.rb +38 -0
  18. data/lib/yard/handlers/rbs/constant_handler.rb +18 -0
  19. data/lib/yard/handlers/rbs/method_handler.rb +327 -0
  20. data/lib/yard/handlers/rbs/mixin_handler.rb +20 -0
  21. data/lib/yard/handlers/rbs/namespace_handler.rb +26 -0
  22. data/lib/yard/handlers/ruby/attribute_handler.rb +7 -4
  23. data/lib/yard/handlers/ruby/constant_handler.rb +24 -6
  24. data/lib/yard/handlers/ruby/legacy/visibility_handler.rb +2 -1
  25. data/lib/yard/handlers/ruby/visibility_handler.rb +1 -0
  26. data/lib/yard/i18n/locale.rb +1 -1
  27. data/lib/yard/i18n/pot_generator.rb +1 -1
  28. data/lib/yard/parser/rbs/rbs_parser.rb +325 -0
  29. data/lib/yard/parser/rbs/statement.rb +75 -0
  30. data/lib/yard/parser/ruby/ast_node.rb +5 -4
  31. data/lib/yard/parser/ruby/legacy/irb/slex.rb +19 -1
  32. data/lib/yard/parser/ruby/legacy/ruby_lex.rb +1 -1
  33. data/lib/yard/parser/ruby/ruby_parser.rb +109 -24
  34. data/lib/yard/parser/source_parser.rb +3 -2
  35. data/lib/yard/registry_resolver.rb +7 -0
  36. data/lib/yard/rubygems/specification.rb +1 -1
  37. data/lib/yard/server/library_version.rb +1 -1
  38. data/lib/yard/server/templates/default/fulldoc/html/js/autocomplete.js +208 -12
  39. data/lib/yard/server/templates/default/layout/html/breadcrumb.erb +1 -17
  40. data/lib/yard/server/templates/default/method_details/html/permalink.erb +4 -2
  41. data/lib/yard/server/templates/doc_server/library_list/html/headers.erb +3 -3
  42. data/lib/yard/server/templates/doc_server/library_list/html/library_list.erb +2 -3
  43. data/lib/yard/server/templates/doc_server/processing/html/processing.erb +22 -16
  44. data/lib/yard/tags/directives.rb +7 -0
  45. data/lib/yard/tags/library.rb +3 -3
  46. data/lib/yard/tags/overload_tag.rb +2 -1
  47. data/lib/yard/tags/tag.rb +1 -1
  48. data/lib/yard/tags/types_explainer.rb +5 -4
  49. data/lib/yard/templates/helpers/base_helper.rb +1 -1
  50. data/lib/yard/templates/helpers/html_helper.rb +21 -6
  51. data/lib/yard/templates/helpers/html_syntax_highlight_helper.rb +6 -1
  52. data/lib/yard/templates/helpers/markup/hybrid_markdown.rb +2147 -0
  53. data/lib/yard/templates/helpers/markup/rdoc_markup.rb +2 -0
  54. data/lib/yard/templates/helpers/markup_helper.rb +4 -2
  55. data/lib/yard/version.rb +1 -1
  56. data/po/ja.po +82 -82
  57. data/templates/default/fulldoc/html/css/style.css +33 -15
  58. data/templates/default/fulldoc/html/full_list.erb +4 -4
  59. data/templates/default/fulldoc/html/js/app.js +567 -271
  60. data/templates/default/fulldoc/html/js/full_list.js +341 -211
  61. data/templates/default/layout/html/headers.erb +1 -1
  62. data/templates/default/layout/html/layout.erb +2 -1
  63. data/templates/default/method/html/header.erb +3 -3
  64. data/templates/default/module/html/defines.erb +3 -3
  65. data/templates/default/module/html/inherited_methods.erb +1 -0
  66. data/templates/default/module/html/method_summary.erb +8 -0
  67. data/templates/default/module/setup.rb +20 -0
  68. data/templates/default/onefile/html/layout.erb +3 -4
  69. data/templates/guide/fulldoc/html/js/app.js +57 -26
  70. data/templates/guide/layout/html/layout.erb +9 -11
  71. metadata +18 -8
data/lib/yard/server/templates/doc_server/processing/html/processing.erb CHANGED
@@ -2,29 +2,35 @@
2
2
  <html>
3
3
  <head>
4
4
  <meta charset="utf-8">
5
- <link rel="stylesheet" href="<%= abs_url('css', 'style.css') %>?<%= mtime('css/style.css') %>" type="text/css" media="screen" charset="utf-8" />
6
- <link rel="stylesheet" href="<%= abs_url('css', 'custom.css') %>?<%= mtime('css/custom.css') %>" type="text/css" media="screen" charset="utf-8" />
7
- <script type="text/javascript" charset="utf-8" src="<%= abs_url('js', 'jquery.js') %>?<%= mtime('js/jquery.js') %>"></script>
5
+ <link rel="stylesheet" href="<%= abs_url('css', 'style.css') %>?<%= mtime('css/style.css') %>" type="text/css" media="screen" charset="utf-8">
6
+ <link rel="stylesheet" href="<%= abs_url('css', 'custom.css') %>?<%= mtime('css/custom.css') %>" type="text/css" media="screen" charset="utf-8">
8
7
  <script type="text/javascript" charset="utf-8">
9
8
  function checkPage(process) {
10
- $.ajax({cache: false, url: "<%= router.request.path %>" + (process ? "?process=true" : ""),
11
- statusCode: { 200: function() { window.location.reload(true); } } });
12
- setTimeout('checkPage()', 2000);
9
+ fetch("<%= router.request.path %>" + (process ? "?process=true" : ""), { cache: "no-store" })
10
+ .then(function(response) {
11
+ if (response.status === 200) window.location.reload();
12
+ });
13
+ setTimeout(checkPage, 2000);
13
14
  }
14
15
  function setFade() {
15
16
  centerMessage();
16
- $(window).resize(function() { centerMessage(); });
17
- $('#fade').fadeIn();
18
- $('#processing').fadeIn();
17
+ window.addEventListener("resize", centerMessage);
18
+ document.getElementById('fade').style.display = 'block';
19
+ document.getElementById('processing').style.display = 'block';
19
20
  }
20
21
  function centerMessage() {
21
- $('#fade').css('width', $(window).width() + 'px');
22
- $('#fade').css('height', $(window).height() - parseInt($('#fade').css('top')) + 'px');
23
- $('#processing').css('left', ($(window).width() / 2 - $('#processing').width() / 2) + 'px');
24
- $('#processing').css('top', ($(window).height() / 2 - $('#processing').height() / 2) + 'px');
22
+ var fade = document.getElementById('fade');
23
+ var processing = document.getElementById('processing');
24
+ var fadeTop = parseInt(window.getComputedStyle(fade).top, 10) || 0;
25
+ fade.style.width = window.innerWidth + 'px';
26
+ fade.style.height = (window.innerHeight - fadeTop) + 'px';
27
+ processing.style.left = (window.innerWidth / 2 - processing.offsetWidth / 2) + 'px';
28
+ processing.style.top = (window.innerHeight / 2 - processing.offsetHeight / 2) + 'px';
25
29
  }
26
- $(function() { checkPage(true); });
27
- $(setFade);
30
+ document.addEventListener("DOMContentLoaded", function() {
31
+ checkPage(true);
32
+ setFade();
33
+ });
28
34
  </script>
29
35
  <style type="text/css" media="screen">
30
36
  body { overflow: hidden; margin: 12px; display: block; }
@@ -46,7 +52,7 @@
46
52
  <strong><%= @library.name %></strong> <% if @library.version %>(<%= @library.version %>)<% end %> is being processed.
47
53
  You'll be redirected when the pages are built, it shouldn't take much longer.
48
54
  </p>
49
- <img src="<%= abs_url('images', 'processing.gif') %>?<%= mtime('images/processing.gif') %>" align="center" />
55
+ <img src="<%= abs_url('images', 'processing.gif') %>?<%= mtime('images/processing.gif') %>" align="center">
50
56
  </div>
51
57
  </body>
52
58
  </html>
data/lib/yard/tags/directives.rb CHANGED
@@ -543,6 +543,7 @@ module YARD
543
543
  # @since 0.8.0
544
544
  class ParseDirective < Directive
545
545
  def call
546
+ existing = YARD::Registry.all.lazy.map(&:path).to_set if handler
546
547
  lang = tag.types ? tag.types.first.to_sym :
547
548
  (handler ? handler.parser.parser_type : :ruby)
548
549
  if handler && lang == handler.parser.parser_type
@@ -555,6 +556,12 @@ module YARD
555
556
  src_parser.file = handler.parser.file if handler
556
557
  src_parser.parse(StringIO.new(tag.text))
557
558
  end
559
+ return unless handler
560
+ YARD::Registry.all.each do |obj|
561
+ next if existing.include? obj.path
562
+ obj.files.each { |entry| entry[1] = handler.statement.line if entry[0] == handler.parser.file.to_s }
563
+ obj.source = handler.statement.source
564
+ end
558
565
  end
559
566
  end
560
567
 
data/lib/yard/tags/library.rb CHANGED
@@ -507,7 +507,7 @@ module YARD
507
507
  #
508
508
  # @example
509
509
  # # Synchronizes system time using NTP.
510
- # # @see http://ntp.org/documentation.html NTP Documentation
510
+ # # @see https://ntp.org/documentation.html NTP Documentation
511
511
  # # @see NTPHelperMethods
512
512
  # class NTPUpdater; end
513
513
  define_tag "See Also", :see, :with_name
@@ -541,7 +541,7 @@ module YARD
541
541
  # @example
542
542
  # # @todo Add support for Jabberwocky service.
543
543
  # # There is an open source Jabberwocky library available
544
- # # at http://jbrwcky.org that can be easily integrated.
544
+ # # at https://jbrwcky.org that can be easily integrated.
545
545
  # class Wonderlander; end
546
546
  # @see tag:note
547
547
  define_tag "Todo Item", :todo
@@ -554,7 +554,7 @@ module YARD
554
554
  # of a specific object.
555
555
  #
556
556
  # @example
557
- # # The public REST API for http://jbrwcky.org
557
+ # # The public REST API for https://jbrwcky.org
558
558
  # # @version 2.0
559
559
  # class JabberwockyAPI; end
560
560
  define_tag "Version", :version
data/lib/yard/tags/overload_tag.rb CHANGED
@@ -60,7 +60,8 @@ module YARD
60
60
  args = YARD::Handlers::Ruby::Legacy::Base.new(nil, nil).send(:tokval_list, toks, :all)
61
61
  args = args.map do |a|
62
62
  k, v = *a.split(/:|=/, 2)
63
- [k.strip.to_s + (a[k.size, 1] == ':' ? ':' : ''), (v ? v.strip : nil)]
63
+ v.strip! if v
64
+ [k.strip.to_s + (a[k.size, 1] == ':' ? ':' : ''), (v && v.empty? ? nil : v)]
64
65
  end if args
65
66
  @name = meth.to_sym
66
67
  @parameters = args
data/lib/yard/tags/tag.rb CHANGED
@@ -38,7 +38,7 @@ module YARD
38
38
  # +raise+, etc.
39
39
  #
40
40
  # @param [#to_s] tag_name the tag name to create the tag for
41
- # @param [String] text the descriptive text for this tag
41
+ # @param [String, nil] text the descriptive text for this tag, or nil if none provided
42
42
  # @param [Array<String>] types optional type list of formally declared types
43
43
  # for the tag
44
44
  # @param [String] name optional key name which the tag refers to
data/lib/yard/tags/types_explainer.rb CHANGED
@@ -32,7 +32,7 @@ module YARD
32
32
 
33
33
  def to_s(singular = true)
34
34
  if name[0, 1] == "#"
35
- singular ? "an object that responds to #{name}" : "objects that respond to #{name}"
35
+ (singular ? "an object that responds to " : "objects that respond to ") + list_join(name.split(/ *& */), with: "and")
36
36
  elsif name[0, 1] =~ /[A-Z]/
37
37
  singular ? "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} " + name : "#{name}#{name[-1, 1] =~ /[A-Z]/ ? "'" : ''}s"
38
38
  else
@@ -42,12 +42,12 @@ module YARD
42
42
 
43
43
  private
44
44
 
45
- def list_join(list)
45
+ def list_join(list, with: "or")
46
46
  index = 0
47
47
  list.inject(String.new) do |acc, el|
48
48
  acc << el.to_s
49
49
  acc << ", " if index < list.size - 2
50
- acc << " or " if index == list.size - 2
50
+ acc << " #{with} " if index == list.size - 2
51
51
  index += 1
52
52
  acc
53
53
  end
@@ -102,6 +102,7 @@ module YARD
102
102
  :fixed_collection_start => /\(/,
103
103
  :fixed_collection_end => /\)/,
104
104
  :type_name => /#{ISEP}#{METHODNAMEMATCH}|#{NAMESPACEMATCH}|\w+/,
105
+ :symbol => /:#{METHODNAMEMATCH}/,
105
106
  :type_next => /[,;]/,
106
107
  :whitespace => /\s+/,
107
108
  :hash_collection_start => /\{/,
@@ -130,7 +131,7 @@ module YARD
130
131
  next unless (match.nil? && @scanner.eos?) || (match && token = @scanner.scan(match))
131
132
  found = true
132
133
  case token_type
133
- when :type_name
134
+ when :type_name, :symbol
134
135
  raise SyntaxError, "expecting END, got name '#{token}'" if name
135
136
  name = token
136
137
  when :type_next
data/lib/yard/templates/helpers/base_helper.rb CHANGED
@@ -45,7 +45,7 @@ module YARD::Templates::Helpers
45
45
  # method depending on the arguments passed in.
46
46
  #
47
47
  # @example Linking a URL
48
- # linkify('http://example.com')
48
+ # linkify('https://example.com')
49
49
  # @example Including docstring contents of an object
50
50
  # linkify('include:YARD::Docstring')
51
51
  # @example Linking to an extra file
data/lib/yard/templates/helpers/html_helper.rb CHANGED
@@ -1,5 +1,9 @@
1
1
  # frozen_string_literal: true
2
- require 'cgi'
2
+ if RUBY_VERSION < '3.5'
3
+ require 'cgi/util'
4
+ else
5
+ require 'cgi/escape'
6
+ end
3
7
 
4
8
  module YARD
5
9
  module Templates::Helpers
@@ -89,10 +93,16 @@ module YARD
89
93
  :tables,
90
94
  :with_toc_data,
91
95
  :no_intraemphasis).to_html
96
+ when 'Commonmarker'
97
+ provider.to_html(text, :options => { }, :plugins => { :syntax_highlighter => nil })
92
98
  when 'CommonMarker'
93
- CommonMarker.render_html(text, %i[DEFAULT GITHUB_PRE_LANG], %i[autolink table])
99
+ provider.render_html(text, %i[DEFAULT GITHUB_PRE_LANG], %i[autolink table])
94
100
  else
95
- provider.new(text).to_html
101
+ if provider.respond_to?(:to_html)
102
+ provider.to_html(text)
103
+ else
104
+ provider.new(text).to_html
105
+ end
96
106
  end
97
107
  end
98
108
 
@@ -152,7 +162,7 @@ module YARD
152
162
  # @return [String] the output HTML
153
163
  # @since 0.6.0
154
164
  def html_markup_text(text)
155
- h(text).gsub(/\r?\n/, '<br/>')
165
+ h(text).gsub(/\r?\n/, '<br>')
156
166
  end
157
167
 
158
168
  # @return [String] the same text with no markup
@@ -224,7 +234,7 @@ module YARD
224
234
  # @return [String] HTML with linkified references
225
235
  def resolve_links(text)
226
236
  code_tags = 0
227
- text.gsub(%r{<(/)?(pre|code|tt)|(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W<]|.+</|$)}m) do |str|
237
+ text.gsub(%r{<(/)?(pre|code|tt)|(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=\W|.+</|$)}m) do |str|
228
238
  closed = $1
229
239
  tag = $2
230
240
  escape = $3
@@ -646,7 +656,12 @@ module YARD
646
656
  language ||= detect_lang_in_codeblock_attributes($1, $2)
647
657
  language ||= object.source_type
648
658
 
649
- if options.highlight
659
+ # Skip re-highlighting if the block is already highlighted (e.g. from a recursive
660
+ # htmlify call via {include:} or {yard:include_tags}). Passing pre-highlighted HTML
661
+ # through CGI.unescapeHTML would corrupt deliberately-escaped entities inside spans.
662
+ # Note: this heuristic suppresses highlighting for code blocks in :html markup that
663
+ # contain a literal <span> tag in the source being documented (an uncommon edge case).
664
+ if options.highlight && string !~ HtmlSyntaxHighlightHelper::ALREADY_HIGHLIGHTED_RE
650
665
  string = html_syntax_highlight(CGI.unescapeHTML(string), language)
651
666
  end
652
667
  classes = ['code', language].compact.join(' ')
data/lib/yard/templates/helpers/html_syntax_highlight_helper.rb CHANGED
@@ -6,6 +6,11 @@ module YARD
6
6
  module HtmlSyntaxHighlightHelper
7
7
  include ModuleHelper
8
8
 
9
+ # Matches source that has already been highlighted (i.e. contains a span tag).
10
+ # Used to avoid double-processing pre-highlighted HTML in the rescue clause of
11
+ # {#html_syntax_highlight_ruby_ripper} and in the {HtmlHelper#parse_codeblocks} guard.
12
+ ALREADY_HIGHLIGHTED_RE = /<span[\s>]/
13
+
9
14
  # Highlights Ruby source
10
15
  # @param [String] source the Ruby source code
11
16
  # @return [String] the highlighted Ruby source
@@ -39,7 +44,7 @@ module YARD
39
44
  end
40
45
  output
41
46
  rescue Parser::ParserSyntaxError
42
- source =~ /^<span\s+class=/ ? source : h(source)
47
+ source =~ ALREADY_HIGHLIGHTED_RE ? source : h(source)
43
48
  end
44
49
 
45
50
  def html_syntax_highlight_ruby_legacy(source)