class Wrapture::Comment

A comment that can be inserted in generated source code.

Comments are primarily used to insert documentation about generated code for documentation generation tools such as Doxygen.

Attributes

text[R]

The raw text of the comment.

Public Class Methods

new(comment = '') click to toggle source

Creates a comment from a string. If the provided string is nil, then an empty string is used.

# File lib/wrapture/comment.rb, line 37
def initialize(comment = '')
  @text = comment.nil? ? '' : comment
end
validate_doc(doc) click to toggle source

Validates a doc string.

# File lib/wrapture/comment.rb, line 28
def self.validate_doc(doc)
  raise InvalidDoc, 'a doc must be a string' unless doc.is_a?(String)
end

Public Instance Methods

empty?() click to toggle source

True if this comment is empty, false otherwise.

# File lib/wrapture/comment.rb, line 42
def empty?
  @text.empty?
end
format(line_prefix: '// ', first_line: nil, last_line: nil, max_line_length: 80) { |first_line| ... } click to toggle source

Yields each line of the comment formatted as specified.

# File lib/wrapture/comment.rb, line 47
def format(line_prefix: '// ', first_line: nil, last_line: nil,
           max_line_length: 80)
  return if @text.empty?

  yield first_line if first_line

  paragraphs(max_line_length - line_prefix.length) do |line|
    yield "#{line_prefix}#{line}".rstrip
  end

  yield last_line if last_line
end
format_as_doxygen(max_line_length: 80, &block) click to toggle source

Calls the given block for each line of the comment formatted using Doxygen style.

# File lib/wrapture/comment.rb, line 62
def format_as_doxygen(max_line_length: 80, &block)
  format(line_prefix: ' * ', first_line: '/**',
         last_line: ' */', max_line_length: max_line_length) do |line|
    block.call(line)
  end
end

Private Instance Methods

paragraphs(line_length) { |running_line| ... } click to toggle source

Yields the comment converted into paragraph-style blocks.

Consecutive lines with text are concatenated together to the maximum line length, regardless of the original line length in the comment. One or more empty lines are written as a single empty line, separating paragraphs.

Yielded lines may have trailing spaces, which are not considered part of the maximum length. The caller must strip these off.

# File lib/wrapture/comment.rb, line 79
def paragraphs(line_length)
  running_line = String.new
  newline_mode = true
  @text.each_line do |line|
    if line.strip.empty?
      unless newline_mode
        yield running_line
        yield ''
        running_line.clear
        newline_mode = true
      end
    else
      newline_mode = false
    end

    line.scan(/\S+/) do |word|
      if running_line.length + word.length > line_length
        yield running_line
        running_line = String.new("#{word} ")
      else
        running_line << word << ' '
      end
    end
  end

  yield running_line
end