class Bake::Documentation

Structured access to a set of comment lines.

def attributes

@returns [Enumerable] If no block given.
@parameter match [MatchData] The regular expression match with `name` and `value` keys.
@yields {|match| ...}

e.g. `@returns [String]`.
The attribute lines of the comment block. 
def attributes
	return to_enum(:attributes) unless block_given?
	
	@comments.each do |comment|
		if match = comment.match(ATTRIBUTE)
			yield match
		end
	end
end

def description

@returns [Enumerable] If no block given.
@parameter match [MatchData] The regular expression match for each line of documentation.
@yields {|match| ...}

The text-only lines of the comment block. 
def description
	return to_enum(:description) unless block_given?
	
	# We track empty lines and only yield a single empty line when there is another line of text:
	gap = false
	
	@comments.each do |comment|
		if match = comment.match(DESCRIPTION)
			if match[1]
				if gap
					yield ""
					gap = false
				end
				
				yield match[1]
			else
				gap = true
			end
		else
			break
		end
	end
end

def initialize(comments)

@parameter comments [Array(String)] An array of comment lines.

Initialize the documentation with an array of comments. 
def initialize(comments)
	@comments = comments
end

def parameters

@returns [Enumerable] If no block given.
@parameter match [MatchData] The regular expression match with `name`, `type` and `details` keys.
@yields {|match| ...}

e.g. `@parameter value [String] The value.`
The parameter lines of the comment block. 
def parameters
	return to_enum(:parameters) unless block_given?
	
	@comments.each do |comment|
		if match = comment.match(PARAMETER)
			yield match
		end
	end
end