Class: SleepingKingStudios::Docs::Data::MethodObject

Inherits:
Base
  • Object
show all
Defined in:
lib/sleeping_king_studios/docs/data/method_object.rb

Overview

Object representing a Ruby method.

Each method has a name and a signature, and can define the following elements:

  • Parameters.

  • A return type.

  • Raised exceptions.

  • A yielded block.

In addition, a method may have a short description, a full description, and metadata.

Instance Method Summary collapse

Methods inherited from Base

#initialize

Constructor Details

This class inherits a constructor from SleepingKingStudios::Docs::Data::Base

Instance Method Details

#alias? ⇒ true, false

Returns true if the method object is an alias of another method; otherwise false.

Returns:

  • (true, false) —

    true if the method object is an alias of another method; otherwise false.



45
46
47
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 45

def alias?
  native.is_alias?
end

#aliases ⇒ Array<String>

Returns the names of the method aliases, if any.

Returns:

  • (Array<String>) —

    the names of the method aliases, if any.



50
51
52
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 50

def aliases
  native.aliases.map { |obj| obj.name.to_s }.sort
end

#as_json ⇒ Hash{String => Object}

Generates a JSON-compatible representation of the method.

Returns a Hash with the following keys:

  • ‘name’: The full, qualified name of the method.

  • ‘slug’: The name of the method in url-safe format.

  • ‘signature’: A String representation of the method and its parameters.

  • ‘short_description’: A short description of the method.

Additionally, the returned Hash will conditionally include the following keys, if the method defines at least one of the corresponding code objects.

  • ‘description’: The full description of the method, minus the first clause.

  • ‘metadata’: Additional metadata tags from the documentation.

  • ‘params’: The method’s parameters, as documented.

  • ‘options’: The method’s option parameters, if any.

  • ‘raises’: The exceptions raised by the method.

  • ‘returns’: The method’s return types and description.

  • ‘yields’: The block yielded by the method.

  • ‘yieldparams’: The yielded blocks’ parameters.

  • ‘yieldreturn’: The value returned by the block.

Finally, the method may have one or more overloads, which replace or supplement the method with alternative signatures or documentation.

  • ‘overloads’: The method overloads, if any. Each overload has the same keys as a full method object.

Returns:

  • (Hash{String => Object}) —

    the representation of the method.



85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 85

def as_json
  JSON_PROPERTIES
    .reduce(required_json) do |memo, property_name|
      value = send(property_name)

      next memo if empty?(value)

      memo.update(property_name.to_s => value)
    end
    .then { |json| merge_pure_overload(json) }
end

#class_method? ⇒ Boolean

Returns true if the method is a class method; otherwise false.

Returns:

  • (Boolean) —

    true if the method is a class method; otherwise false.



98
99
100
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 98

def class_method?
  !instance_method?
end

#constructor? ⇒ Boolean Also known as: constructor

Returns true if the method is a constructor; otherwise false.

Returns:

  • (Boolean) —

    true if the method is a constructor; otherwise false.



103
104
105
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 103

def constructor?
  native.constructor?
end

#data_path ⇒ String

The path to the data file.

Returns:

  • (String) —

    the file path.



111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 111

def data_path
  return @data_path if @data_path

  *scope_names, method_name =
    name.split(NAME_SEPARATOR).reject(&:empty?)

  scope_names = scope_names.map { |str| slugify(str) }
  scope_names << "#{instance_method? ? 'i' : 'c'}-#{slugify(method_name)}"

  @data_path = scope_names.join('/')
end

#description ⇒ String

The full description of the method, minus the first clause.

The remainder of the method description, if any, after subtracting the short description (separated by the first paragraph break).

Returns:

  • (String) —

    the remaining description.

See Also:



131
132
133
134
135
136
137
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 131

def description
  return @description if @description

  @short_description, @description = split_docstring

  @description
end

#instance_method? ⇒ Boolean

Returns true if the method is an instance method; otherwise false.

Returns:

  • (Boolean) —

    true if the method is an instance method; otherwise false.



141
142
143
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 141

def instance_method?
  native.path[-(1 + native.name.length)] == '#'
end

#metadata ⇒ Object

Additional metadata tags from the documentation.

See Also:



148
149
150
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 148

def metadata
  @metadata ||= format_metadata
end

#name ⇒ String

The full, qualified name of the method.

Returns:

  • (String) —

    the qualified name.



155
156
157
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 155

def name
  @name ||= native.path
end

#options ⇒ Array<Hash>

The documented options of the method.

Each option is a Hash with the following keys:

  • ‘name’: The name of the parameter.

  • ‘type’: The JSON representation of the parsed Type object.

  • ‘description’: The description of the parameter.

Returns:

  • (Array<Hash>) —

    the method options.



168
169
170
171
172
173
174
175
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 168

def options
  @options ||=
    native
    .tags
    .select { |tag| tag.tag_name == 'option' }
    .group_by(&:name)
    .map { |name, tags| format_options(name, tags) }
end

#overloaded? ⇒ true, false

Checks if the method has been completely overloaded.

A completely overloaded method has no description and no tags other than exactly one @overload tag. This case is common when documenting a method with a different signature.

Returns:

  • (true, false) —

    true if the method is completely overloaded; otherwise false.



185
186
187
188
189
190
191
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 185

def overloaded?
  return false unless native.docstring.empty?

  return false unless native.tags.all? { |tag| tag.tag_name == 'overload' }

  native.tags.size == 1
end

#overloads ⇒ Object

The documented overloads for the method.

Each overload is a JSON representation of a method, and includes the same tags and properties (with the exception that an overload cannot itself have overloads).

See Also:



200
201
202
203
204
205
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 200

def overloads
  native
    .tags
    .select { |tag| tag.tag_name == 'overload' }
    .map { |tag| format_overload(tag) }
end

#params ⇒ Array<Hash>

The documented parameters of the method.

Each parameter is a Hash with the following keys:

  • ‘name’: The name of the parameter.

  • ‘type’: The JSON representation of the parsed Type object.

  • ‘description’: The description of the parameter.

Returns:

  • (Array<Hash>) —

    the method parameters.



216
217
218
219
220
221
222
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 216

def params
  @params ||=
    native
    .tags
    .select { |tag| tag.tag_name == 'param' }
    .map { |tag| format_param(tag) }
end

#parent_path ⇒ String

The path to the defining class or module’s data file.

Returns:

  • (String) —

    the file path.



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 227

def parent_path
  return @parent_path if @parent_path

  return @parent_path = '' if native.parent.root?

  parent_class  =
    if native.parent.is_a?(YARD::CodeObjects::ClassObject)
      SleepingKingStudios::Docs::Data::ClassObject
    else
      SleepingKingStudios::Docs::Data::ModuleObject
    end
  parent_object = parent_class.new(native: native.parent)

  @parent_path = parent_object.data_path
end

#raises ⇒ Array<Hash>

The documented raised exceptions of the method.

Each raised exception is a Hash with the following keys:

  • ‘type’: The type of exception raised.

  • ‘description’: The description of the exception, or details on when the exception is raised.

Returns:

  • (Array<Hash>) —

    the exceptions raised.by the method.



252
253
254
255
256
257
258
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 252

def raises
  @raises ||=
    native
    .tags
    .select { |tag| tag.tag_name == 'raise' }
    .map { |tag| format_return(tag) }
end

#returns ⇒ Array<Hash>

The return type or types of the method.

Each return type or types is a Hash with the following keys:

  • ‘type’: The JSON representation of the parsed Type object.

  • ‘description’: The description of the returned type, or details on when that type will be returned.

Returns:

  • (Array<Hash>) —

    the return types of the method.

See Also:



271
272
273
274
275
276
277
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 271

def returns
  @returns ||=
    native
    .tags
    .select { |tag| tag.tag_name == 'return' }
    .map { |tag| format_return(tag) }
end

#short_description ⇒ String

A short description of the method.

The first part of the method description, separated by the first paragraph break. Typically should fit on a single line of text.

Returns:

  • (String) —

    the short description.

See Also:



287
288
289
290
291
292
293
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 287

def short_description
  return @short_description if @short_description

  @short_description, @description = split_docstring

  @short_description
end

#signature ⇒ String

The name and parameters of the method.

Returns:

  • (String) —

    the method signature.



298
299
300
301
302
303
304
305
306
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 298

def signature
  return @signature if @signature

  unless native.signature.include?('(')
    return @signature = native.signature.sub(/\Adef /, '')
  end

  @signature = generate_signature
end

#slug ⇒ String

The name of the method in url-safe format.

Returns:

  • (String) —

    the method name.



311
312
313
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 311

def slug
  @slug ||= slugify(name.sub(/\A::/, '').split(/#|\./).last)
end

#yield_params ⇒ Array<Hash>

The parameters of the yielded to the block.

Each parameter is a Hash with the following keys:

  • ‘name’: The name of the parameter.

  • ‘type’: The JSON representation of the parsed Type object.

  • ‘description’: The description of the parameter.

Returns:

  • (Array<Hash>) —

    the yielded parameters.



324
325
326
327
328
329
330
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 324

def yield_params
  @yield_params ||=
    native
    .tags
    .select { |tag| tag.tag_name == 'yieldparam' }
    .map { |tag| format_yield_param(tag) }
end

#yield_returns ⇒ Array<Hash>

The return type or types of the yielded block.

Each return type or types is a Hash with the following keys:

  • ‘type’: The JSON representation of the parsed Type object.

  • ‘description’: The description of the returned type, or details on when that type will be returned.

Returns:

  • (Array<Hash>) —

    the return types of the yielded block.

See Also:



343
344
345
346
347
348
349
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 343

def yield_returns
  @yield_returns ||=
    native
    .tags
    .select { |tag| tag.tag_name == 'yieldreturn' }
    .map { |tag| format_return(tag) }
end

#yields ⇒ Array<Hash>

The yielded block or blocks of method.

Each yielded block is a Hash with the following keys:

  • ‘description’: The description of the yielded block or details on when the block will be yielded.

  • ‘parameters’: (Optional) The parameters yielded to the block.

Returns:

  • (Array<Hash>) —

    the yielded blocks.

See Also:

  • #yieldparams
  • #yieldreturns


363
364
365
366
367
368
 
# File 'lib/sleeping_king_studios/docs/data/method_object.rb', line 363

def yields
  native
    .tags
    .select { |tag| tag.tag_name == 'yield' }
    .map { |tag| format_yield(tag) }
end