Class: RDoc::MethodAttr

Inherits:
CodeObject show all
Includes:
Comparable
Defined in:
lib/rdoc/code_object/method_attr.rb,
lib/rdoc/generator/markup.rb

Overview

Abstract class representing either a method or an attribute.

Direct Known Subclasses

AnyMethod, Attr

Constant Summary

Constants included from Text

Text::MARKUP_FORMAT, Text::SPACE_SEPARATED_LETTER_CLASS

Instance Attribute Summary collapse

Attributes inherited from CodeObject

#comment, #document_children, #document_self, #done_documenting, #file, #force_documentation, #line, #metadata, #mixin_from, #parent, #received_nodoc, #section, #store

Attributes included from Text

#language

Instance Method Summary collapse

Methods inherited from CodeObject

#display?, #file_name, #full_name=, #ignore, #ignored?, #options, #record_location, #start_doc, #stop_doc, #suppress, #suppressed?

Methods included from Generator::Markup

#aref_to, #as_href, #canonical_url, #cvs_url, #description, #formatter

Methods included from Text

decode_legacy_label, expand_tabs, #flush_left, #markup, #normalize_comment, #parse, #snippet, #strip_hashes, #strip_newlines, #strip_stars, to_anchor, #wrap

Constructor Details

#initialize(name, singleton: false) ⇒ MethodAttr

Creates a new MethodAttr with method or attribute name name.

Usually this is called by super from a subclass.



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/rdoc/code_object/method_attr.rb', line 73

def initialize(name, singleton: false)
  super()

  @name = name

  @aliases      = []
  @is_alias_for = nil
  @parent_name  = nil
  @singleton    = singleton
  @visibility   = :public
  @see = false

  @arglists     = nil
  @block_params = nil
  @call_seq     = nil
  @params       = nil
  @type_signature_lines = nil
end

Instance Attribute Details

#aliases ⇒ Object (readonly)

Array of other names for this method/attribute



27
28
29
 
# File 'lib/rdoc/code_object/method_attr.rb', line 27

def aliases
  @aliases
end

#arglists ⇒ Object (readonly)

The call_seq or the param_seq with method name, if there is no call_seq.



65
66
67
 
# File 'lib/rdoc/code_object/method_attr.rb', line 65

def arglists
  @arglists
end

#block_params ⇒ Object

Parameters yielded by the called block



44
45
46
 
# File 'lib/rdoc/code_object/method_attr.rb', line 44

def block_params
  @block_params
end

#call_seq ⇒ Object

Different ways to call this method



54
55
56
 
# File 'lib/rdoc/code_object/method_attr.rb', line 54

def call_seq
  @call_seq
end

#is_alias_for ⇒ Object

The method/attribute we’re aliasing



32
33
34
 
# File 'lib/rdoc/code_object/method_attr.rb', line 32

def is_alias_for
  @is_alias_for
end

#name ⇒ Object

Name of this method/attribute.



12
13
14
 
# File 'lib/rdoc/code_object/method_attr.rb', line 12

def name
  @name
end

#params ⇒ Object

Parameters for this method



49
50
51
 
# File 'lib/rdoc/code_object/method_attr.rb', line 49

def params
  @params
end

#singleton ⇒ Object

Is this a singleton method/attribute?



22
23
24
 
# File 'lib/rdoc/code_object/method_attr.rb', line 22

def singleton
  @singleton
end

#type_signature_lines ⇒ Object

RBS type signature lines from inline annotations or loaded .rbs files. Each entry is one overload or type expression.



60
61
62
 
# File 'lib/rdoc/code_object/method_attr.rb', line 60

def type_signature_lines
  @type_signature_lines
end

#visibility ⇒ Object

public, protected, private



17
18
19
 
# File 'lib/rdoc/code_object/method_attr.rb', line 17

def visibility
  @visibility
end

Instance Method Details

#<=>(other) ⇒ Object

Order by #singleton then #name



107
108
109
110
111
112
113
 
# File 'lib/rdoc/code_object/method_attr.rb', line 107

def <=>(other)
  return unless other.respond_to?(:singleton) &&
                other.respond_to?(:name)

  [@singleton      ? 0 : 1, name_ord_range,       name] <=>
  [other.singleton ? 0 : 1, other.name_ord_range, other.name]
end

#==(other) ⇒ Object

:nodoc:



115
116
117
 
# File 'lib/rdoc/code_object/method_attr.rb', line 115

def ==(other) # :nodoc:
  equal?(other) or self.class == other.class and full_name == other.full_name
end

#add_alias(an_alias, context) ⇒ Object

Abstract method. Contexts in their building phase call this to register a new alias for this known method/attribute.

  • creates a new AnyMethod/Attribute named an_alias.new_name;

  • adds self as an alias for the new method or attribute

  • adds the method or attribute to #aliases

  • adds the method or attribute to context.

Raises:

  • (NotImplementedError) 


203
204
205
 
# File 'lib/rdoc/code_object/method_attr.rb', line 203

def add_alias(an_alias, context)
  raise NotImplementedError
end

#add_line_numbers(src) ⇒ Object

Prepend src with line numbers.



108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/rdoc/generator/markup.rb', line 108

def add_line_numbers(src)
  return if src.empty? || !line
  start_line = line
  end_line  = start_line + src.count("\n")
  number_digits = end_line.to_s.length

  current_line = start_line
  src.gsub!(/^/) do
    res = "<span class=\"line-num\">#{current_line.to_s.rjust(number_digits)}</span> "

    current_line += 1
    res
  end
end

#add_location_comment(src) ⇒ Object

Prepend src with a comment that declares its location in the source.



126
127
128
129
130
131
132
133
 
# File 'lib/rdoc/generator/markup.rb', line 126

def add_location_comment(src)
  path = CGI.escapeHTML(file.relative_name)
  if options.line_numbers && !src.empty?
    src.prepend("<span class=\"ruby-comment\"># File #{path}</span>\n")
  else
    src.prepend("<span class=\"ruby-comment\"># File #{path}, line #{line}</span>\n")
  end
end

#aref ⇒ Object

HTML fragment reference for this method



210
211
212
213
214
 
# File 'lib/rdoc/code_object/method_attr.rb', line 210

def aref
  type = singleton ? 'c' : 'i'
  # % characters are not allowed in html names => dash instead
  "#{aref_prefix}-#{type}-#{html_name}"
end

#aref_prefix ⇒ Object

Prefix for aref, defined by subclasses.

Raises:

  • (NotImplementedError) 


219
220
221
 
# File 'lib/rdoc/code_object/method_attr.rb', line 219

def aref_prefix
  raise NotImplementedError
end

#documented? ⇒ Boolean

A method/attribute is documented if any of the following is true:

  • it was marked with :nodoc:;

  • it has a comment;

  • it is an alias for a documented method;

  • it has a #see method that is documented.

Returns:

  • (Boolean) 


126
127
128
129
130
 
# File 'lib/rdoc/code_object/method_attr.rb', line 126

def documented?
  super or
    (is_alias_for and is_alias_for.documented?) or
    (see and see.documented?)
end

#find_method_or_attribute(name) ⇒ Object

:nodoc:



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/rdoc/code_object/method_attr.rb', line 172

def find_method_or_attribute(name) # :nodoc:
  return nil unless parent.respond_to? :ancestors

  searched = parent.ancestors
  kernel = @store.modules_hash['Kernel']

  searched << kernel if kernel &&
    parent != kernel && !searched.include?(kernel)

  searched.each do |ancestor|
    next if String === ancestor
    next if parent == ancestor

    other = ancestor.find_method_named('#' + name) ||
            ancestor.find_attribute_named(name)

    return other if other
  end

  nil
end

#find_see ⇒ Object

:nodoc:



160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/rdoc/code_object/method_attr.rb', line 160

def find_see # :nodoc:
  return nil if singleton || is_alias_for

  # look for the method
  other = find_method_or_attribute name
  return other if other

  # if it is a setter, look for a getter
  return nil unless name =~ /[a-z_]=$/i   # avoid == or ===
  return find_method_or_attribute name[0..-2]
end

#full_name ⇒ Object

Full method/attribute name including namespace



295
296
297
 
# File 'lib/rdoc/code_object/method_attr.rb', line 295

def full_name
  @full_name ||= "#{parent_name}#{pretty_name}"
end

#html_name ⇒ Object

HTML id-friendly method/attribute name



285
286
287
288
289
290
 
# File 'lib/rdoc/code_object/method_attr.rb', line 285

def html_name
  require 'cgi/escape'
  require 'cgi/util' unless defined?(CGI::EscapeExt)

  CGI.escape(@name.gsub('-', '-2D')).gsub('%', '-').sub(/^-/, '')
end

#initialize_copy(other) ⇒ Object

Resets cached data for the object so it can be rebuilt by accessor methods



95
96
97
 
# File 'lib/rdoc/code_object/method_attr.rb', line 95

def initialize_copy(other) # :nodoc:
  @full_name = nil
end

#initialize_visibility ⇒ Object

:nodoc:



99
100
101
102
 
# File 'lib/rdoc/code_object/method_attr.rb', line 99

def initialize_visibility # :nodoc:
  super
  @see = nil
end

#inspect ⇒ Object

:nodoc:



299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/rdoc/code_object/method_attr.rb', line 299

def inspect # :nodoc:
  alias_for = @is_alias_for ? " (alias for #{@is_alias_for.name})" : nil
  visibility = self.visibility
  visibility = "forced #{visibility}" if force_documentation
  "#<%s:0x%x %s (%s)%s>" % [
    self.class, object_id,
    full_name,
    visibility,
    alias_for,
  ]
end

#markup_code ⇒ Object

Turns the method’s token stream into HTML.

Prepends line numbers if options.line_numbers is true.



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/rdoc/generator/markup.rb', line 140

def markup_code
  return '' if !@token_stream

  src = RDoc::TokenStream.to_html @token_stream

  # dedent the source
  common_indent = src.length
  src.scan(/^ *(?=\S)/) do |whitespace|
    common_indent = whitespace.length if whitespace.length < common_indent
    break if common_indent == 0
  end
  src.gsub!(/^#{' ' * common_indent}/, '') if common_indent > 0

  if source_language == 'ruby'
    add_line_numbers(src) if options.line_numbers
    add_location_comment(src)
  end

  src
end

#name_ord_range ⇒ Object

:nodoc:



405
406
407
408
409
410
411
412
413
414
415
416
 
# File 'lib/rdoc/code_object/method_attr.rb', line 405

def name_ord_range # :nodoc:
  case name.ord
  when 0..64 # anything below "A"
    1
  when 91..96 # the symbols between "Z" and "a"
    2
  when 123..126 # 7-bit symbols above "z": "{", "|", "}", "~"
    3
  else # everythig else can be sorted as normal
    4
  end
end

#name_prefix ⇒ Object

‘::’ for a class method/attribute, ‘#’ for an instance method.



314
315
316
 
# File 'lib/rdoc/code_object/method_attr.rb', line 314

def name_prefix
  @singleton ? '::' : '#'
end

#parent_name ⇒ Object

Name of our parent with special handling for un-marshaled methods



342
343
344
 
# File 'lib/rdoc/code_object/method_attr.rb', line 342

def parent_name
  @parent_name || super
end

#path ⇒ Object

Path to this method for use with HTML generator output.



335
336
337
 
# File 'lib/rdoc/code_object/method_attr.rb', line 335

def path
  "#{@parent.path}##{aref}"
end

#pretty_name ⇒ Object

Method/attribute name with class/instance indicator



321
322
323
 
# File 'lib/rdoc/code_object/method_attr.rb', line 321

def pretty_name
  "#{name_prefix}#{@name}"
end

#pretty_print(q) ⇒ Object

:nodoc:



346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
 
# File 'lib/rdoc/code_object/method_attr.rb', line 346

def pretty_print(q) # :nodoc:
  alias_for =
    if @is_alias_for.respond_to? :name then
      "alias for #{@is_alias_for.name}"
    elsif Array === @is_alias_for then
      "alias for #{@is_alias_for.last}"
    end

  q.group 2, "[#{self.class.name} #{full_name} #{visibility}", "]" do
    if alias_for then
      q.breakable
      q.text alias_for
    end

    unless comment.empty? then
      q.breakable
      q.text "comment:"
      q.breakable
      q.pp @comment
    end
  end
end

#search_record ⇒ Object

Used by RDoc::Generator::JsonIndex to create a record for the search engine.

TODO: Remove this method after dropping the darkfish theme and JsonIndex generator. Use #search_snippet instead for getting documentation snippets.



376
377
378
379
380
381
382
383
384
385
386
 
# File 'lib/rdoc/code_object/method_attr.rb', line 376

def search_record
  [
    @name,
    full_name,
    @name,
    @parent.full_name,
    path,
    params,
    search_snippet,
  ]
end

#search_snippet ⇒ Object

Returns an HTML snippet of the comment for search results.



391
392
393
394
395
 
# File 'lib/rdoc/code_object/method_attr.rb', line 391

def search_snippet
  return '' if @comment.empty?

  snippet(@comment)
end

#see ⇒ Object

A method/attribute to look at, in particular if this method/attribute has no documentation.

It can be a method/attribute of the superclass or of an included module, including the Kernel module, which is always appended to the included modules.

Returns nil if there is no such method/attribute. The #is_alias_for method/attribute, if any, is not included.

Templates may generate a “see also …” if this method/attribute has documentation, and “see …” if it does not.



146
147
148
149
 
# File 'lib/rdoc/code_object/method_attr.rb', line 146

def see
  @see = find_see if @see == false
  @see
end

#store=(store) ⇒ Object

Sets the store for this class or module and its contained code objects.



154
155
156
157
158
 
# File 'lib/rdoc/code_object/method_attr.rb', line 154

def store=(store)
  super

  @file = @store.add_file @file.full_name if @file
end

#to_s ⇒ Object

:nodoc:



397
398
399
400
401
402
403
 
# File 'lib/rdoc/code_object/method_attr.rb', line 397

def to_s # :nodoc:
  if @is_alias_for
    "#{self.class.name}: #{full_name} -> #{is_alias_for}"
  else
    "#{self.class.name}: #{full_name}"
  end
end

#type ⇒ Object

Type of method/attribute (class or instance)



328
329
330
 
# File 'lib/rdoc/code_object/method_attr.rb', line 328

def type
  singleton ? 'class' : 'instance'
end