Module: YARD::Markdown::TagFormattingHelper

Defined in:
lib/yard/markdown/tag_formatting_helper.rb

Overview

Formats YARD tags into Markdown list items and fenced examples.

Instance Method Summary collapse

Instance Method Details

#format_hash_tag_type(name, value) ⇒ String?

Formats a hash-style tag type entry.

Parameters:

  • name (String) —

    Type name to format.

  • value (Object) —

    Associated type detail.

Returns:

  • (String, nil) —

    Formatted type entry, or nil when blank.



66
67
68
69
70
71
72
 
# File 'lib/yard/markdown/tag_formatting_helper.rb', line 66

def format_hash_tag_type(name, value)
  key = name.rstrip
  return nil if key.empty?
  return key if value.nil? || value == true || (value.respond_to?(:empty?) && value.empty?)

  "#{key}: #{value}"
end

#format_tag(tag) ⇒ String

Formats a non-example YARD tag as a Markdown list item body.

Parameters:

  • tag (YARD::Tags::Tag) —

    Non-example tag being converted into list item text.

Returns:

  • (String) —

    Markdown representation of the tag.



36
37
38
39
40
41
42
43
44
45
 
# File 'lib/yard/markdown/tag_formatting_helper.rb', line 36

def format_tag(tag)
  parts = ["**@#{tag.tag_name}**"]
  parts << "`#{tag.name}`" unless tag.name.to_s.lstrip.empty?

  cleaned_types = normalized_tag_types(tag.types)
  parts << "[#{cleaned_types.join(', ')}]" unless cleaned_types.empty?
  parts << tag.text.strip unless tag.text.to_s.lstrip.empty?

  parts.join(' ')
end

#normalized_tag_types(types) ⇒ Array<String>

Normalizes tag type declarations into printable strings.

Parameters:

  • types (Array<Object>, Hash, nil) —

    Raw tag types from YARD.

Returns:

  • (Array<String>) —

    Cleaned type strings.



51
52
53
54
55
56
57
58
59
 
# File 'lib/yard/markdown/tag_formatting_helper.rb', line 51

def normalized_tag_types(types)
  values = if types.instance_of?(Hash)
             types.map { |name, value| format_hash_tag_type(name, value) }
           else
             Array(types)
           end

  values.map(&:to_s).map(&:strip).reject(&:empty?)
end

#render_tags(object) ⇒ String

Renders all tags for an object as Markdown.

Parameters:

  • object (YARD::CodeObjects::Base) —

    Object whose tags are being rendered.

Returns:

  • (String) —

    Markdown representation of the object’s tags.



11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/yard/markdown/tag_formatting_helper.rb', line 11

def render_tags(object)
  lines = []
  regular_tags = object.tags.reject { |tag| tag.tag_name == 'example' }
  example_tags = object.tags.select { |tag| tag.tag_name == 'example' }

  regular_tags.each do |tag|
    lines << "- #{format_tag(tag)}"
  end

  example_tags.each do |tag|
    lines << nil unless lines.empty?
    title = tag.name.to_s.rstrip.empty? ? '**@example**' : "**@example #{tag.name}**"
    lines << title
    lines << '```ruby'
    lines << tag.text.to_s.rstrip
    lines << '```'
  end

  lines.join("\n")
end