Class: YARD::Docstring
Overview
A documentation string, or “docstring” for short, encapsulates the comments and metadata, or “tags”, of an object. Meta-data is expressed in the form @tag VALUE, where VALUE can span over multiple lines as long as they are indented. The following @example tag shows how tags can be indented:
# @example My example
# a = "hello world"
# a.reverse
# @version 1.0
Tags can be nested in a documentation string, though the Tags::Tag itself is responsible for parsing the inner tags.
Constant Summary collapse
- META_MATCH =
Matches a tag at the start of a comment line
/^@([a-z_0-9]+)(?:\s+(.*))?$/i
Instance Attribute Summary collapse
-
#all ⇒ String
readonly
The raw documentation (including raw tag text).
-
#hash_flag ⇒ Boolean
Whether the docstring was started with “##”.
-
#line_range ⇒ Range
Line range in the #object‘s file where the docstring was parsed from.
-
#object ⇒ CodeObjects::Base
The object that owns the docstring.
-
#ref_tags ⇒ Array<Tags::RefTag>
readonly
The list of reference tags.
Creating a Docstring Object collapse
-
#+(other) ⇒ Docstring
Adds another Docstring, copying over tags.
-
#initialize(content = '', object = nil) ⇒ Docstring
constructor
Creates a new docstring with the raw contents attached to an optional object.
-
#replace(content) ⇒ Object
(also: #all=)
Replaces the docstring with new raw content.
Creating and Accessing Meta-data collapse
-
#add_tag(*tags) ⇒ Object
Adds a tag or reftag object to the tag list.
-
#blank?(only_visible_tags = true) ⇒ Boolean
Returns true if the docstring has no content that is visible to a template.
-
#has_tag?(name) ⇒ Boolean
Returns true if at least one tag by the name
name
was declared. -
#tag(name) ⇒ Tags::Tag
Convenience method to return the first tag object in the list of tag objects of that name.
-
#tags(name = nil) ⇒ Array<Tags::Tag>
Returns a list of tags specified by
name
or all tags ifname
is not specified.
Instance Method Summary collapse
-
#line ⇒ Fixnum
The first line of the #line_range.
-
#summary ⇒ String
Gets the first line of a docstring to the period or the first paragraph.
Methods inherited from String
Constructor Details
#initialize(content = '', object = nil) ⇒ Docstring
Creates a new docstring with the raw contents attached to an optional object.
47 48 49 50 51 52 53 |
# File 'lib/yard/docstring.rb', line 47 def initialize(content = '', object = nil) @object = object @summary = nil @hash_flag = false self.all = content end |
Instance Attribute Details
#all ⇒ String (readonly)
Returns the raw documentation (including raw tag text).
26 27 28 |
# File 'lib/yard/docstring.rb', line 26 def all @all end |
#hash_flag ⇒ Boolean
Returns whether the docstring was started with “##”.
29 30 31 |
# File 'lib/yard/docstring.rb', line 29 def hash_flag @hash_flag end |
#line_range ⇒ Range
Returns line range in the #object‘s file where the docstring was parsed from.
23 24 25 |
# File 'lib/yard/docstring.rb', line 23 def line_range @line_range end |
#object ⇒ CodeObjects::Base
Returns the object that owns the docstring.
20 21 22 |
# File 'lib/yard/docstring.rb', line 20 def object @object end |
#ref_tags ⇒ Array<Tags::RefTag> (readonly)
Returns the list of reference tags.
17 18 19 |
# File 'lib/yard/docstring.rb', line 17 def @ref_tags end |
Instance Method Details
#+(other) ⇒ Docstring
Adds another YARD::Docstring, copying over tags.
60 61 62 63 64 65 66 67 |
# File 'lib/yard/docstring.rb', line 60 def +(other) case other when Docstring Docstring.new([all, other.all].join("\n"), object) else super end end |
#add_tag(*tags) ⇒ Object
Adds a tag or reftag object to the tag list
114 115 116 117 118 119 120 121 122 123 124 125 126 |
# File 'lib/yard/docstring.rb', line 114 def add_tag(*) .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 |
#blank?(only_visible_tags = true) ⇒ Boolean
Returns true if the docstring has no content that is visible to a template.
164 165 166 167 168 169 170 |
# File 'lib/yard/docstring.rb', line 164 def blank?( = true) if empty? && !.any? {|tag| Tags::Library..include?(tag.tag_name.to_sym) } else empty? && @tags.empty? && @ref_tags.empty? end end |
#has_tag?(name) ⇒ Boolean
Returns true if at least one tag by the name name
was declared
155 156 157 |
# File 'lib/yard/docstring.rb', line 155 def has_tag?(name) .any? {|tag| tag.tag_name.to_s == name.to_s } end |
#line ⇒ Fixnum
Returns the first line of the #line_range.
81 82 83 |
# File 'lib/yard/docstring.rb', line 81 def line line_range.first end |
#replace(content) ⇒ Object Also known as: all=
Replaces the docstring with new raw content. Called by #all=.
71 72 73 74 75 |
# File 'lib/yard/docstring.rb', line 71 def replace(content) @tags, @ref_tags = [], [] @all = content super parse_comments(content) end |
#summary ⇒ String
Gets the first line of a docstring to the period or the first paragraph.
87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 |
# File 'lib/yard/docstring.rb', line 87 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 |
#tag(name) ⇒ Tags::Tag
Convenience method to return the first tag object in the list of tag objects of that name
137 138 139 |
# File 'lib/yard/docstring.rb', line 137 def tag(name) .find {|tag| tag.tag_name.to_s == name.to_s } end |