Class: YARD::Tags::MethodDirective

Inherits:
Directive
  • Object
show all
Defined in:
lib/yard/tags/directives.rb

Overview

Note:

For backwards compatibility support, you do not need to indent the method's docstring text. If a @!method directive is seen with no indented block, the entire docstring is used as the new method's docstring text.

Defines a method object with a given method signature, using indented block data as the method's docstring. The signature is similar to the @overload tag. The comment containing this directive does not need to be attached to any source, but if it is, that source code will be used as the method's source.

To define an attribute method, see @!attribute

Examples:

Defining a simple method

# @!method quit(username, message = "Quit")
#   Sends a quit message to the server for a +username+.
#   @param [String] username the username to quit
#   @param [String] message the quit message
quit_message_method

Attaching multiple methods to the same source

# @!method method1
# @!method method2
create_methods :method1, :method2

See Also:

Since:

Direct Known Subclasses

AttributeDirective

Constant Summary

SCOPE_MATCH =

Since:

  • 0.7.0

/\A\s*self\s*\.\s*/

Instance Attribute Summary (collapse)

Parser callbacks (collapse)

Constructor Details

This class inherits a constructor from YARD::Tags::Directive

Instance Attribute Details

- (String?) expanded_text Originally defined in class Directive

Set this field to replace the directive definition inside of a docstring with arbitrary text. For instance, the MacroDirective uses this field to expand its macro data in place of the call to a @!macro.

Returns:

  • (String)

    the text to expand in the original docstring in place of this directive definition.

  • (nil)

    if no expansion should take place for this directive

Since:

  • 0.8.0

- (Handlers::Base?) handler (readonly) Originally defined in class Directive

Returns the handler object the docstring parser might be attached to. May be nil. Only available when parsing through Parser::SourceParser.

Returns:

Since:

  • 0.8.0

- (CodeObjects::Base?) object (readonly) Originally defined in class Directive

Returns the object the parent docstring is attached to. May be nil.

Returns:

  • (CodeObjects::Base, nil)

    the object the parent docstring is attached to. May be nil.

Since:

  • 0.8.0

- (DocstringParser) parser (protected) Originally defined in class Directive

Returns the parser that is parsing all tag information out of the docstring

Returns:

  • (DocstringParser)

    the parser that is parsing all tag information out of the docstring

Since:

  • 0.8.0

- (Tag) tag Originally defined in class Directive

Returns the meta-data tag containing data input to the directive

Returns:

  • (Tag)

    the meta-data tag containing data input to the directive

Since:

  • 0.8.0

Instance Method Details

- (Object) after_parse

Since:

  • 0.7.0



356
357
358
359
360
# File 'lib/yard/tags/directives.rb', line 356

def after_parse
  return unless handler
  use_indented_text
  create_object
end

- (Object) call

Since:

  • 0.7.0



354
# File 'lib/yard/tags/directives.rb', line 354

def call; end

- (Object) create_object (protected)

Since:

  • 0.7.0



396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
# File 'lib/yard/tags/directives.rb', line 396

def create_object
  name = method_name
  scope = parser.state.scope || handler.scope
  visibility = parser.state.visibility || handler.visibility
  ns = CodeObjects::NamespaceObject === object ? object : handler.namespace
  obj = CodeObjects::MethodObject.new(ns, name, scope)
  handler.register_file_info(obj)
  handler.register_source(obj)
  handler.register_visibility(obj, visibility)
  handler.register_group(obj)
  obj.signature = method_signature
  obj.parameters = OverloadTag.new(:overload, method_signature).parameters
  obj.docstring = Docstring.new!(parser.text, parser.tags, obj,
    parser.raw_text, parser.reference)
  handler.register_module_function(obj)
  obj
end

- (Object) method_name (protected)

Since:

  • 0.7.0



364
365
366
367
368
369
370
371
# File 'lib/yard/tags/directives.rb', line 364

def method_name
  sig = sanitized_tag_signature
  if sig && sig =~ /^#{CodeObjects::METHODNAMEMATCH}(\s|\(|$)/
    sig[/\A\s*([^\(; \t]+)/, 1]
  else
    handler.call_params.first
  end
end

- (Object) method_signature (protected)

Since:

  • 0.7.0



373
374
375
# File 'lib/yard/tags/directives.rb', line 373

def method_signature
  "def #{sanitized_tag_signature || method_name}"
end

- (Object) sanitized_tag_signature (protected)

Since:

  • 0.7.0



377
378
379
380
381
382
383
384
# File 'lib/yard/tags/directives.rb', line 377

def sanitized_tag_signature
  if tag.name && tag.name =~ SCOPE_MATCH
    parser.state.scope = :class
    $'
  else
    tag.name
  end
end

- (Object) use_indented_text (protected)

Since:

  • 0.7.0



386
387
388
389
390
391
392
393
394
# File 'lib/yard/tags/directives.rb', line 386

def use_indented_text
  return if tag.text.empty?
  handler = parser.handler
  object = parser.object
  self.parser = parser.class.new(parser.library)
  parser.state.inside_directive = true
  parser.parse(tag.text, object, handler)
  parser.state.inside_directive = false
end