Class: SupportTableData::Documentation::YardDoc

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

Constant Summary collapse

MACRO_FINDER = 
"support_table_data_finder"
MACRO_PREDICATE = 
"support_table_data_predicate"
MACRO_ATTRIBUTE = 
"support_table_data_attribute"

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



11
12
13
 
# File 'lib/support_table_data/documentation/yard_doc.rb', line 11

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



74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/support_table_data/documentation/yard_doc.rb', line 74

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



44
45
46
47
48
49
50
51
52
53
 
# File 'lib/support_table_data/documentation/yard_doc.rb', line 44

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 @!method/@!macro

    pair per generated method

  • ‘: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`).



26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/support_table_data/documentation/yard_doc.rb', line 26

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



59
60
61
62
63
64
65
66
67
 
# File 'lib/support_table_data/documentation/yard_doc.rb', line 59

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