Class: YARD::Docstring

Inherits:

String

• Object
• String
• YARD::Docstring

show all

Defined in:

lib/yard/docstring.rb

Overview

  # @example My example
  #   a = "hello world"
  #   a.reverse
  # @version 1.0

Constant Summary

META_MATCH = Matches a tag at the start of a comment line.

/^@([a-z_]+)(?:\s+(.*))?$/i

Instance Attribute Summary

• - (String) all The raw documentation (including raw tag text).
• - (Range) line_range Line range in the #object’s file where the docstring was parsed from.
• - (CodeObjects::Base) object The object that owns the docstring.
• - (Array<Tags::RefTag>) ref_tags readonly The list of reference tags.

Instance Method Summary

• - (Object) add_tag(*tags) Adds a tag or reftag object to the tag list.
• - (Boolean) blank? Returns true if the docstring has no content.
• - (Boolean) has_tag?(name) Returns true if at least one tag by the name name was declared.
• - (Docstring) initialize(content = '', object = nil) constructor Creates a new docstring with the raw contents attached to an optional object.
• - (Fixnum) line The first line of the #line_range.
• - (Object) replace(content) (also: #all=) Replaces the docstring with new raw content.
• - (String) summary Gets the first line of a docstring to the period or the first paragraph.
• - (Tags::Tag) tag(name) Convenience method to return the first tag object in the list of tag objects of that name.
• - (Array<Tags::Tag>) tags(name = nil) Returns a list of tags specified by name or all tags if name is not specified.

Methods inherited from String

#camelcase, #shell_split, #underscore

  Docstring.new("hello world\n@return Object return", someobj)

41
42
43
44
45

# File 'lib/yard/docstring.rb', line 41

def initialize(content = '', object = nil)
  @object = object
  
  self.all = content
end

26
27
28

# File 'lib/yard/docstring.rb', line 26

def all
  @all
end

23
24
25

# File 'lib/yard/docstring.rb', line 23

def line_range
  @line_range
end

20
21
22

# File 'lib/yard/docstring.rb', line 20

def object
  @object
end

17
18
19

# File 'lib/yard/docstring.rb', line 17

def ref_tags
  @ref_tags
end

88
89
90
91
92
93
94
95
96
97
98
99
100

# File 'lib/yard/docstring.rb', line 88

def add_tag(*tags)
  tags.each_with_index do |tag, i|
    case tag
    when Tags::Tag
      tag.object = object
      @tags << tag
    when Tags::RefTag
      @ref_tags << tag
    else
      raise ArgumentError, "expected Tag or RefTag, got #{tag.class} (at index #{i})"
    end
  end
end

137
138
139

# File 'lib/yard/docstring.rb', line 137

def blank?
  empty? && @tags.empty? && @ref_tags.empty?
end

130
131
132

# File 'lib/yard/docstring.rb', line 130

def has_tag?(name)
  tags.any? {|tag| tag.tag_name.to_s == name.to_s }
end

57
58
59

# File 'lib/yard/docstring.rb', line 57

def line
  line_range.first
end

49
50
51
52
53

# File 'lib/yard/docstring.rb', line 49

def replace(content)
  @tags, @ref_tags = [], []
  @all = content
  super parse_comments(content)
end

63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

# File 'lib/yard/docstring.rb', line 63

def summary
  return @summary if @summary
  open_parens = ['{', '(', '[']
  close_parens = ['}', ')', ']']
  num_parens = 0
  idx = length.times do |index|
    case self[index, 1]
    when ".", "\r", "\n"
      next_char = self[index + 1, 1].to_s
      if num_parens == 0 && next_char =~ /^\s*$/
        break index - 1
      end
    when "{", "(", "["
      num_parens += 1
    when "}", ")", "]"
      num_parens -= 1
    end
  end
  @summary = self[0..idx]
  @summary += '.' unless @summary.empty?
  @summary
end

  doc = Docstring.new("@return zero when nil")
  doc.tag(:return).text  # => "zero when nil"

111
112
113

# File 'lib/yard/docstring.rb', line 111

def tag(name)
  tags.find {|tag| tag.tag_name.to_s == name.to_s }
end

119
120
121
122
123

# File 'lib/yard/docstring.rb', line 119

def tags(name = nil)
  list = @tags + convert_ref_tags
  return list unless name
  list.select {|tag| tag.tag_name.to_s == name.to_s }
end