81 lines
2.2 KiB
Ruby
81 lines
2.2 KiB
Ruby
class HereDocHelper
|
|
# NOTE: The following methods duplicate functionality from
|
|
# Puppet::Util::Reference and Puppet::Parser::Functions.functiondocs
|
|
#
|
|
# However, implementing this natively in YARD is a good test for the
|
|
# feasibility of extracting custom Ruby documentation. In the end, the
|
|
# existing approach taken by Puppet::Util::Reference may be the best due to
|
|
# the heavy use of metaprogramming in Types and Providers.
|
|
|
|
# Extracts the Puppet function name and options hash from the parsed
|
|
# definition.
|
|
#
|
|
# @return [(String, Hash{String => String})]
|
|
def process_parameters(statement)
|
|
# Passing `false` to prameters excludes the block param from the returned
|
|
# list.
|
|
name, opts = statement.parameters(false).compact
|
|
|
|
name = process_element(name)
|
|
|
|
# Don't try to process options if we don't have any
|
|
if !opts.nil?
|
|
opts = opts.map do |tuple|
|
|
# Jump down into the S-Expression that represents a hashrocket, `=>`,
|
|
# and the values on either side of it.
|
|
tuple.jump(:assoc).map{|e| process_element(e)}
|
|
end
|
|
|
|
options = Hash[opts]
|
|
else
|
|
options = {}
|
|
end
|
|
|
|
[name, options]
|
|
end
|
|
|
|
# Sometimes the YARD parser returns Heredoc strings that start with `<-`
|
|
# instead of `<<-`.
|
|
HEREDOC_START = /^<?<-/
|
|
|
|
def is_heredoc?(str)
|
|
HEREDOC_START.match(str)
|
|
end
|
|
|
|
# Turns an entry in the method parameter list into a string.
|
|
#
|
|
# @param ele [YARD::Parser::Ruby::AstNode]
|
|
# @return [String]
|
|
def process_element(ele)
|
|
ele = ele.jump(:ident, :string_content)
|
|
|
|
case ele.type
|
|
when :ident
|
|
ele.source
|
|
when :string_content
|
|
source = ele.source
|
|
if is_heredoc? source
|
|
process_heredoc(source)
|
|
else
|
|
source
|
|
end
|
|
end
|
|
end
|
|
|
|
# Cleans up and formats Heredoc contents parsed by YARD.
|
|
#
|
|
# @param source [String]
|
|
# @return [String]
|
|
def process_heredoc(source)
|
|
source = source.lines.to_a
|
|
|
|
# YARD adds a line of source context on either side of the Heredoc
|
|
# contents.
|
|
source.shift
|
|
source.pop
|
|
|
|
# This utility method normalizes indentation and trims whitespace.
|
|
Puppet::Util::Docs.scrub(source.join)
|
|
end
|
|
end
|