Class: RDoc::MethodAttr

Inherits:
CodeObject show all
Includes:
Comparable
Defined in:
lib/rdoc/method_attr.rb

Overview

Abstract class representing either a method or an attribute.

Direct Known Subclasses

AnyMethod, Attr

Constant Summary

Constants included from Text

Text::TO_HTML_CHARACTERS

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, #viewer

Instance Method Summary collapse

Methods inherited from CodeObject

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

Methods included from Text

encode_fallback, #expand_tabs, #flush_left, #markup, #normalize_comment, #parse, #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.



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

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

Instance Attribute Details

#aliases ⇒ Object (readonly)

Array of other names for this method/attribute



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

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/method_attr.rb', line 65

def arglists
  @arglists
end

#block_params ⇒ Object

Parameters yielded by the called block



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

def block_params
  @block_params
end

#call_seq ⇒ Object

Different ways to call this method



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

def call_seq
  @call_seq
end

#is_alias_for ⇒ Object

The method/attribute we're aliasing



38
39
40
 
# File 'lib/rdoc/method_attr.rb', line 38

def is_alias_for
  @is_alias_for
end

#name ⇒ Object

Name of this method/attribute.



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

def name
  @name
end

#param_seq ⇒ Object (readonly)

Pretty parameter list for this method



70
71
72
 
# File 'lib/rdoc/method_attr.rb', line 70

def param_seq
  @param_seq
end

#params ⇒ Object

Parameters for this method



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

def params
  @params
end

#singleton ⇒ Object

Is this a singleton method/attribute?



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

def singleton
  @singleton
end

#text ⇒ Object (readonly)

Source file token stream



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

def text
  @text
end

#visibility ⇒ Object

public, protected, private



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

def visibility
  @visibility
end

Instance Method Details

#<=>(other) ⇒ Object

Order by #singleton then #name



102
103
104
 
# File 'lib/rdoc/method_attr.rb', line 102

def <=>(other)
  [@singleton ? 0 : 1, name] <=> [other.singleton ? 0 : 1, other.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 newa named an_alias.new_name;

  • adds self as newa.is_alias_for;

  • adds newa to #aliases

  • adds newa to the methods/attributes of context.

Raises:

  • (NotImplementedError) 


181
182
183
 
# File 'lib/rdoc/method_attr.rb', line 181

def add_alias(an_alias, context)
  raise NotImplementedError
end

#aref ⇒ Object

HTML fragment reference for this method



188
189
190
191
192
 
# File 'lib/rdoc/method_attr.rb', line 188

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) 


197
198
199
 
# File 'lib/rdoc/method_attr.rb', line 197

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) 


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

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:



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/rdoc/method_attr.rb', line 150

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

  searched = parent.ancestors
  kernel = RDoc::TopLevel.all_modules_hash['Kernel']

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

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

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

    return other if other
  end

  nil
end

#find_see ⇒ Object

:nodoc:



138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/rdoc/method_attr.rb', line 138

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



270
271
272
 
# File 'lib/rdoc/method_attr.rb', line 270

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

#html_name ⇒ Object

HTML id-friendly method/attribute name



263
264
265
 
# File 'lib/rdoc/method_attr.rb', line 263

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

#inspect ⇒ Object

:nodoc:



334
335
336
337
338
339
340
341
342
343
344
 
# File 'lib/rdoc/method_attr.rb', line 334

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

#name_prefix ⇒ Object

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



277
278
279
 
# File 'lib/rdoc/method_attr.rb', line 277

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

#parent_name ⇒ Object

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



305
306
307
 
# File 'lib/rdoc/method_attr.rb', line 305

def parent_name
  @parent_name || super
end

#path ⇒ Object

Path to this method



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

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

#pretty_name ⇒ Object

Method/attribute name with class/instance indicator



284
285
286
 
# File 'lib/rdoc/method_attr.rb', line 284

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

#pretty_print(q) ⇒ Object

:nodoc:



309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/rdoc/method_attr.rb', line 309

def pretty_print q # :nodoc:
  alias_for = @is_alias_for ? "alias for #{@is_alias_for.name}" : nil

  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

#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.



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

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

#to_s ⇒ Object

:nodoc:



346
347
348
349
350
351
352
 
# File 'lib/rdoc/method_attr.rb', line 346

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)



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

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