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.



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

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.



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

def add_line_numbers
  @add_line_numbers
end

Instance Attribute Details

#aliases ⇒ Object (readonly)

Array of other names for this method/attribute



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

def aliases
  @aliases
end

#arglists ⇒ Object (readonly)

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



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

def arglists
  @arglists
end

#block_params ⇒ Object

Parameters yielded by the called block



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

def block_params
  @block_params
end

#call_seq ⇒ Object

Different ways to call this method



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

def call_seq
  @call_seq
end

#is_alias_for ⇒ Object

The method/attribute we’re aliasing



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

def is_alias_for
  @is_alias_for
end

#name ⇒ Object

Name of this method/attribute.



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

def name
  @name
end

#param_seq ⇒ Object (readonly)

Pretty parameter list for this method



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

def param_seq
  @param_seq
end

#params ⇒ Object

Parameters for this method



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

def params
  @params
end

#singleton ⇒ Object

Is this a singleton method/attribute?



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

def singleton
  @singleton
end

#text ⇒ Object (readonly)

Source file token stream



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

def text
  @text
end

#visibility ⇒ Object

public, protected, private



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

def visibility
  @visibility
end

Instance Method Details

#<=>(other) ⇒ Object

Order by #singleton then #name



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

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:



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

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) 


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

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.



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

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



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

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) 


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

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) 


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

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:



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

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:



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

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



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

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

#html_name ⇒ Object

HTML id-friendly method/attribute name



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

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



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

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

#initialize_visibility ⇒ Object

:nodoc:



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

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

#inspect ⇒ Object

:nodoc:



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

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.



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

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.



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

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.



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

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



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

def parent_name
  @parent_name || super
end

#path ⇒ Object

Path to this method for use with HTML generator output.



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

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

#pretty_name ⇒ Object

Method/attribute name with class/instance indicator



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

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

#pretty_print(q) ⇒ Object

:nodoc:



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
392
 
# File 'lib/rdoc/method_attr.rb', line 364

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.



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

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.



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

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.



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

def store= store
  super

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

#to_s ⇒ Object

:nodoc:



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

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)



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

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