Class: RDoc::MethodAttr

Inherits:
CodeObject show all
Includes:
Comparable
Defined in:
lib/rdoc/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::TO_HTML_CHARACTERS

Class Attribute Summary collapse

Instance Attribute Summary collapse

Attributes inherited from CodeObject

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

Instance Method Summary collapse

Methods inherited from CodeObject

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

Methods included from Generator::Markup

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

Methods included from Text

encode_fallback, #expand_tabs, #flush_left, #markup, #normalize_comment, #parse, #snippet, #strip_hashes, #strip_newlines, #strip_stars, #to_html, #wrap

Constructor Details

#initialize(text, name) ⇒ MethodAttr

Creates a new MethodAttr from token stream text and method or attribute name name.

Usually this is called by super from a subclass.



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/rdoc/method_attr.rb', line 77

def initialize text, name
  super()

  @text = text
  @name = name

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

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

Class Attribute Details

.add_line_numbers ⇒ Object

Allows controlling whether #markup_code adds line numbers to the source code.



74
75
76
 
# File 'lib/rdoc/generator/markup.rb', line 74

def add_line_numbers
  @add_line_numbers
end

Instance Attribute Details

#aliases ⇒ Object (readonly)

Array of other names for this method/attribute



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

def aliases
  @aliases
end

#arglists ⇒ Object (readonly)

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



63
64
65
 
# File 'lib/rdoc/method_attr.rb', line 63

def arglists
  @arglists
end

#block_params ⇒ Object

Parameters yielded by the called block



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

def block_params
  @block_params
end

#call_seq ⇒ Object

Different ways to call this method



58
59
60
 
# File 'lib/rdoc/method_attr.rb', line 58

def call_seq
  @call_seq
end

#is_alias_for ⇒ Object

The method/attribute we’re aliasing



36
37
38
 
# File 'lib/rdoc/method_attr.rb', line 36

def is_alias_for
  @is_alias_for
end

#name ⇒ Object

Name of this method/attribute.



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

def name
  @name
end

#param_seq ⇒ Object (readonly)

Pretty parameter list for this method



68
69
70
 
# File 'lib/rdoc/method_attr.rb', line 68

def param_seq
  @param_seq
end

#params ⇒ Object

Parameters for this method



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

def params
  @params
end

#singleton ⇒ Object

Is this a singleton method/attribute?



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

def singleton
  @singleton
end

#text ⇒ Object (readonly)

Source file token stream



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

def text
  @text
end

#visibility ⇒ Object

public, protected, private



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

def visibility
  @visibility
end

Instance Method Details

#<=>(other) ⇒ Object

Order by #singleton then #name



112
113
114
115
116
117
118
 
# File 'lib/rdoc/method_attr.rb', line 112

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

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

#==(other) ⇒ Object

:nodoc:



120
121
122
 
# File 'lib/rdoc/method_attr.rb', line 120

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) 


208
209
210
 
# File 'lib/rdoc/method_attr.rb', line 208

def add_alias(an_alias, context)
  raise NotImplementedError
end

#add_line_numbers(src) ⇒ Object

Prepend src with line numbers. Relies on the first line of a source code listing having:

# File xxxxx, line dddd

If it has this comment then line numbers are added to src and the , line dddd portion of the comment is removed.



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/rdoc/generator/markup.rb', line 86

def add_line_numbers(src)
  return unless src.sub!(/\A(.*)(, line (\d+))/, '\1')
  first = $3.to_i - 1
  last  = first + src.count("\n")
  size = last.to_s.length

  line = first
  src.gsub!(/^/) do
    res = if line == first then
            " " * (size + 1)
          else
            "<span class=\"line-num\">%2$*1$d</span> " % [size, line]
          end

    line += 1
    res
  end
end

#aref ⇒ Object

HTML fragment reference for this method



215
216
217
218
219
 
# File 'lib/rdoc/method_attr.rb', line 215

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) 


224
225
226
 
# File 'lib/rdoc/method_attr.rb', line 224

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) 


131
132
133
134
135
 
# File 'lib/rdoc/method_attr.rb', line 131

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:



177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/rdoc/method_attr.rb', line 177

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:



165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/rdoc/method_attr.rb', line 165

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



299
300
301
 
# File 'lib/rdoc/method_attr.rb', line 299

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

#html_name ⇒ Object

HTML id-friendly method/attribute name



290
291
292
293
294
 
# File 'lib/rdoc/method_attr.rb', line 290

def html_name
  require 'cgi'

  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



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

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

#initialize_visibility ⇒ Object

:nodoc:



104
105
106
107
 
# File 'lib/rdoc/method_attr.rb', line 104

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

#inspect ⇒ Object

:nodoc:



303
304
305
306
307
308
309
310
311
312
313
 
# File 'lib/rdoc/method_attr.rb', line 303

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 add_line_numbers is true.



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/rdoc/generator/markup.rb', line 110

def markup_code
  return '' unless @token_stream

  src = RDoc::TokenStream.to_html @token_stream

  # dedent the source
  indent = src.length
  lines = src.lines.to_a
  lines.shift if src =~ /\A.*#\ *File/i # remove '# File' comment
  lines.each do |line|
    if line =~ /^ *(?=\S)/
      n = $&.length
      indent = n if n < indent
      break if n == 0
    end
  end
  src.gsub!(/^#{' ' * indent}/, '') if indent > 0

  add_line_numbers(src) if RDoc::MethodAttr.add_line_numbers

  src
end

#name_prefix ⇒ Object

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



318
319
320
 
# File 'lib/rdoc/method_attr.rb', line 318

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

#output_name(context) ⇒ Object

Name for output to HTML. For class methods the full name with a “.” is used like SomeClass.method_name. For instance methods the class name is used if context does not match the parent.

This is to help prevent people from using

to call class methods.



329
330
331
332
333
 
# File 'lib/rdoc/method_attr.rb', line 329

def output_name context
  return "#{name_prefix}#{@name}" if context == parent

  "#{parent_name}#{@singleton ? '.' : '#'}#{@name}"
end

#parent_name ⇒ Object

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



359
360
361
 
# File 'lib/rdoc/method_attr.rb', line 359

def parent_name
  @parent_name || super
end

#path ⇒ Object

Path to this method for use with HTML generator output.



352
353
354
 
# File 'lib/rdoc/method_attr.rb', line 352

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

#pretty_name ⇒ Object

Method/attribute name with class/instance indicator



338
339
340
 
# File 'lib/rdoc/method_attr.rb', line 338

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

#pretty_print(q) ⇒ Object

:nodoc:



363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
 
# File 'lib/rdoc/method_attr.rb', line 363

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

    if text then
      q.breakable
      q.text "text:"
      q.breakable
      q.pp @text
    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.



397
398
399
400
401
402
403
404
405
406
407
 
# File 'lib/rdoc/method_attr.rb', line 397

def search_record
  [
    @name,
    full_name,
    @name,
    @parent.full_name,
    path,
    params,
    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.



151
152
153
154
 
# File 'lib/rdoc/method_attr.rb', line 151

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.



159
160
161
162
163
 
# File 'lib/rdoc/method_attr.rb', line 159

def store= store
  super

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

#to_s ⇒ Object

:nodoc:



409
410
411
412
413
414
415
 
# File 'lib/rdoc/method_attr.rb', line 409

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)



345
346
347
 
# File 'lib/rdoc/method_attr.rb', line 345

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