Class: SupportTableData::Documentation::YardDoc

Inherits:
Object
  • Object
show all
Defined in:
lib/support_table_data/documentation/yard_doc.rb

Instance Method Summary collapse

Constructor Details

#initialize(klass) ⇒ YardDoc

Returns a new instance of YardDoc.

Parameters:

  • klass (Class) —

    The model class to generate documentation for



7
8
9
 
# File 'lib/support_table_data/documentation/yard_doc.rb', line 7

def initialize(klass)
  @klass = klass
end

Instance Method Details

#attribute_helper_yard_doc(name, attribute_name) ⇒ String

Generate YARD documentation comment for the attribute method helper for the named instance.

Parameters:

  • name (String) —

    The name of the instance method.

  • attribute_name (String) —

    The attribute being read.

Returns:

  • (String) —

    The YARD comment text



70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/support_table_data/documentation/yard_doc.rb', line 70

def attribute_helper_yard_doc(name, attribute_name)
  return_type = attribute_yard_return_type(name, attribute_name)
  <<~YARD.chomp("\n")
    # Get the #{attribute_name} attribute from the data file
    # for the named instance +#{name}+.
    #
    # @!method self.#{name}_#{attribute_name}
    # @return [#{return_type}]
    # @!visibility public
  YARD
end

#instance_helper_yard_doc(name) ⇒ String

Generate YARD documentation comment for named instance singleton method.

Parameters:

  • name (String) —

    The name of the instance method.

Returns:

  • (String) —

    The YARD comment text



40
41
42
43
44
45
46
47
48
49
 
# File 'lib/support_table_data/documentation/yard_doc.rb', line 40

def instance_helper_yard_doc(name)
  <<~YARD.chomp("\n")
    # Find the named instance +#{name}+ from the database.
    #
    # @!method self.#{name}
    # @return [#{klass.name}]
    # @raise [ActiveRecord::RecordNotFound] if the record does not exist
    # @!visibility public
  YARD
end

#named_instance_yard_docs ⇒ String?

Generate YARD documentation for the model's helper methods. The format is controlled by the model's support_table_yard_docs setting:

  • :full - verbose comment block per method (default)
  • :compact - shared @!macro definitions plus a short comment block per method that expands them
  • :none - generate no docs at all

Returns:

  • (String, nil) —

    The YARD documentation, or nil if no docs should be emitted (either because the model has no named instances or because support_table_yard_docs is :none).



22
23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/support_table_data/documentation/yard_doc.rb', line 22

def named_instance_yard_docs
  return nil if klass.support_table_yard_docs == :none

  instance_names = klass.instance_names
  return nil if instance_names.empty?

  case klass.support_table_yard_docs
  when :compact
    generate_compact_yard_docs(instance_names)
  else
    generate_verbose_yard_docs(instance_names)
  end
end

#predicate_helper_yard_doc(name) ⇒ String

Generate YARD documentation comment for the predicate method for the named instance.

Parameters:

  • name (String) —

    The name of the instance method.

Returns:

  • (String) —

    The YARD comment text



55
56
57
58
59
60
61
62
63
 
# File 'lib/support_table_data/documentation/yard_doc.rb', line 55

def predicate_helper_yard_doc(name)
  <<~YARD.chomp("\n")
    # Check if this record is the named instance +#{name}+.
    #
    # @!method #{name}?
    # @return [Boolean]
    # @!visibility public
  YARD
end