Module: YardStruct::SharedMethods

Includes:
YARD::CodeObjects
Included in:
ModernStructHandler, StructHandler
Defined in:
lib/yard-struct/shared_methods.rb

Instance Method Summary collapse

Instance Method Details

#create_attributes(klass, members) ⇒ Object

Creates the given member methods and attaches them to the given ClassObject.

Parameters:

  • klass (ClassObject) —

    the class to generate attributes for

  • members (Array<String>) —

    a list of member names



112
113
114
115
116
117
118
119
120
121
 
# File 'lib/yard-struct/shared_methods.rb', line 112

def create_attributes(klass, members)
  # For each parameter, add reader and writers
  members.each do |member|
    # Ripped off from YARD's attribute handling source
    klass.attributes[:instance][member] = SymbolHash[:read => nil, :write => nil]
    
    create_writer klass, member
    create_reader klass, member
  end
end

#create_class(classname, superclass) ⇒ ClassObject

Creates and registers a class object with the given name and superclass name. Returns it for further use.

Parameters:

  • classname (String) —

    the name of the class

  • superclass (String) —

    the name of the superclass

Returns:

  • (ClassObject) —

    the class object for further processing/method attaching



66
67
68
69
70
71
 
# File 'lib/yard-struct/shared_methods.rb', line 66

def create_class(classname, superclass)
  register ClassObject.new(namespace, classname) do |o|
    o.superclass = superclass if superclass
    o.superclass.type = :class if o.superclass.is_a?(Proxy)
  end
end

#create_reader(klass, member) ⇒ Object

Creates the getter (reader) method and attaches it to the class as an attribute. Also sets up the docstring to prettify the documentation output.

Parameters:

  • klass (ClassObject) —

    the class to attach the method to

  • member (String) —

    the name of the member we’re generating a method for



97
98
99
100
101
102
103
104
105
 
# File 'lib/yard-struct/shared_methods.rb', line 97

def create_reader(klass, member)
  # Do the getter
  new_meth = register MethodObject.new(klass, member, :instance) do |o|
    o.signature ||= "def #{member}"
    o.source ||= "#{o.signature}\n  @#{member}\nend"
  end
  new_meth.docstring.replace getter_docstring(klass, member)
  klass.attributes[:instance][member][:read] = new_meth
end

#create_writer(klass, member) ⇒ Object

Creates the setter (writer) method and attaches it to the class as an attribute. Also sets up the docstring to prettify the documentation output.

Parameters:

  • klass (ClassObject) —

    the class to attach the method to

  • member (String) —

    the name of the member we’re generating a method for



79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/yard-struct/shared_methods.rb', line 79

def create_writer(klass, member)
  # We want to convert these members into attributes just like
  # as if they were declared using attr_accessor.
  new_meth = register MethodObject.new(klass, "#{member}=", :instance) do |o|
    o.parameters = [['value', nil]]
    o.signature ||= "def #{member}=(value)"
    o.source ||= "#{o.signature}\n  @#{member} = value\nend"
  end
  new_meth.docstring.replace setter_docstring(klass, member)
  klass.attributes[:instance][member][:write] = new_meth
end

#getter_docstring(klass, member) ⇒ String

Creates the auto-generated docstring for the getter method of a struct’s member. This is used so the generated documentation will look just like that of an attribute defined using attr_accessor.

Parameters:

  • klass (ClassObject) —

    the class whose members we’re working with

  • member (String) —

    the name of the member we’re generating documentation for

Returns:

  • (String) —

    a docstring to be attached to the getter method for this member



37
38
39
40
41
 
# File 'lib/yard-struct/shared_methods.rb', line 37

def getter_docstring(klass, member)
  member_tag = member_tag_for_member(klass, member)
  getter_doc_text = member_tag ? member_tag.text : "Returns the value of attribute #{member}"
  getter_doc_text += "\n@return #{return_type_for_member(klass, member)} the current value of #{member}"
end

#member_tag_for_member(klass, member) ⇒ YARD::Tags::Tag?

Extracts the user’s defined @member tag for a given class and its member. Returns nil if the user did not define a @member tag for this struct entry.

Parameters:

  • klass (ClassObject) —

    the class whose tags we’re searching

  • member (String) —

    the name of the struct member we need

Returns:

  • (YARD::Tags::Tag, nil) —

    the tag matching the request, or nil if not found



12
13
14
 
# File 'lib/yard-struct/shared_methods.rb', line 12

def member_tag_for_member(klass, member)
  klass.tags(:member).find {|tag| tag.name == member}
end

#return_type_for_member(klass, member) ⇒ String

Gets the return type for the member in a nicely formatted string. Used to be injected into auto-generated docstrings.

Parameters:

  • klass (ClassObject) —

    the class whose tags we’re searching

  • member (String) —

    the name of the struct member whose return type we need

Returns:

  • (String) —

    the user-declared type of the struct member, or [Object] if the user did not define a type for this member.



24
25
26
27
 
# File 'lib/yard-struct/shared_methods.rb', line 24

def return_type_for_member(klass, member)
  member_tag = member_tag_for_member(klass, member)
  return_type = member_tag ? "[#{member_tag.types.join(', ')}]" : "[Object]"
end

#setter_docstring(klass, member) ⇒ String

Creates the auto-generated docstring for the setter method of a struct’s member. This is used so the generated documentation will look just like that of an attribute defined using attr_accessor.

Parameters:

  • klass (ClassObject) —

    the class whose members we’re working with

  • member (String) —

    the name of the member we’re generating documentation for

Returns:

  • (String) —

    a docstring to be attached to the setter method for this member



51
52
53
54
55
56
57
 
# File 'lib/yard-struct/shared_methods.rb', line 51

def setter_docstring(klass, member)
  member_tag = member_tag_for_member(klass, member)
  return_type = return_type_for_member(klass, member)
  setter_doc_text = member_tag ? member_tag.text : "Sets the attribute #{member}"
  setter_doc_text += "\n@param #{return_type} value the value to set the attribute #{member} to."
  setter_doc_text += "\n@return #{return_type} the newly set value"
end