Class: SupportTableData::Documentation::SourceFile

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

Constant Summary collapse

BEGIN_YARD_COMMENT = 
"# Begin YARD docs for support_table_data"
END_YARD_COMMENT = 
"# End YARD docs for support_table_data"
YARD_COMMENT_REGEX = 
/^(?<indent>[ \t]*)#{BEGIN_YARD_COMMENT}.*?^[ \t]*#{END_YARD_COMMENT}$/m
CLASS_DEF_REGEX = 
/^[ \t]*class [a-zA-Z_0-9:]+.*?$/
UPDATE_COMMAND_COMMENT = 
"# To update these docs, run `bundle exec rake support_table_data:yard_docs`"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(klass, path) ⇒ SourceFile

Initialize a new source file representation.

Parameters:

  • klass (Class) —

    The model class

  • path (Pathname) —

    The path to the source file



18
19
20
21
22
 
# File 'lib/support_table_data/documentation/source_file.rb', line 18

def initialize(klass, path)
  @klass = klass
  @path = path
  @source = nil
end

Instance Attribute Details

#klass ⇒ Object (readonly)

Returns the value of attribute klass.



6
7
8
 
# File 'lib/support_table_data/documentation/source_file.rb', line 6

def klass
  @klass
end

#path ⇒ Object (readonly)

Returns the value of attribute path.



6
7
8
 
# File 'lib/support_table_data/documentation/source_file.rb', line 6

def path
  @path
end

Instance Method Details

#has_yard_docs? ⇒ Boolean

Check if the source file has any YARD documentation added by support_table_data.

Returns:

  • (Boolean) 


104
105
106
 
# File 'lib/support_table_data/documentation/source_file.rb', line 104

def has_yard_docs?
  source.match?(YARD_COMMENT_REGEX)
end

#source ⇒ String

Return the source code of the file.

Returns:

  • (String) 


27
28
29
 
# File 'lib/support_table_data/documentation/source_file.rb', line 27

def source
  @source ||= @path.read
end

#source_with_yard_docs ⇒ String

Return the source code with the generated YARD documentation added. The YARD docs are identified by a begin and end comment block. By default the generated docs are added to the end of the file by reopening the class definition. You can move the comment block inside the original class if desired.

Returns:

  • (String) 


45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/support_table_data/documentation/source_file.rb', line 45

def source_with_yard_docs
  yard_docs = YardDoc.new(klass).named_instance_yard_docs
  if yard_docs.nil?
    return has_yard_docs? ? source_without_yard_docs : source
  end

  existing_yard_docs = source.match(YARD_COMMENT_REGEX)
  if existing_yard_docs
    indent = existing_yard_docs[:indent]
    has_class_def = existing_yard_docs.to_s.match?(CLASS_DEF_REGEX)
    yard_docs = yard_docs.lines.map { |line| line.blank? ? "\n" : "#{indent}#{"  " if has_class_def}#{line}" }.join

    updated_source = source[0, existing_yard_docs.begin(0)]
    updated_source << "#{indent}#{BEGIN_YARD_COMMENT}\n"
    updated_source << "#{indent}#{UPDATE_COMMAND_COMMENT}\n"
    updated_source << "#{indent}# rubocop:disable all\n"
    updated_source << "#{indent}class #{klass.name}\n" if has_class_def
    updated_source << yard_docs
    updated_source << "\n#{indent}end" if has_class_def
    updated_source << "\n#{indent}# rubocop:enable all"
    updated_source << "\n#{indent}#{END_YARD_COMMENT}"
    # Strip out any duplicate generated blocks (i.e. left over from a bad merge)
    # so that the file is left with exactly one block. Otherwise the tail of the
    # file is preserved verbatim so that a file whose docs are already up to date
    # compares byte for byte with its own source.
    tail = source[existing_yard_docs.end(0)..]
    deduped_tail = tail.gsub(YARD_COMMENT_REGEX, "")
    if deduped_tail == tail
      updated_source << tail
      updated_source
    else
      updated_source << deduped_tail
      "#{updated_source.rstrip}#{trailing_newline}"
    end
  else
    yard_comments = <<~SOURCE.chomp("\n")
      #{BEGIN_YARD_COMMENT}
      #{UPDATE_COMMAND_COMMENT}
      # rubocop:disable all
      class #{klass.name}
      #{yard_docs.lines.map { |line| line.blank? ? "\n" : "  #{line}" }.join}
      end
      # rubocop:enable all
      #{END_YARD_COMMENT}
    SOURCE
    "#{source.rstrip}\n\n#{yard_comments}#{trailing_newline}"
  end
end

#source_without_yard_docs ⇒ String

Return the source code without any generated YARD documentation.

Returns:

  • (String) 


34
35
36
 
# File 'lib/support_table_data/documentation/source_file.rb', line 34

def source_without_yard_docs
  "#{source.gsub(YARD_COMMENT_REGEX, "").rstrip}#{trailing_newline}"
end

#yard_docs_up_to_date? ⇒ Boolean

Check if the YARD documentation in the source file is up to date.

Returns:

  • (Boolean) 


97
98
99
 
# File 'lib/support_table_data/documentation/source_file.rb', line 97

def yard_docs_up_to_date?
  source == source_with_yard_docs
end