104 lines
2.9 KiB
Ruby
104 lines
2.9 KiB
Ruby
require_relative '../code_objects'
|
|
|
|
module Puppetx::Yardoc::YARD::Handlers
|
|
class FutureParserFunctionHandler < YARD::Handlers::Ruby::Base
|
|
include Puppetx::Yardoc::YARD::CodeObjects
|
|
|
|
handles method_call(:create_function)
|
|
|
|
process do
|
|
name = process_parameters
|
|
|
|
obj = MethodObject.new(function_namespace, name)
|
|
|
|
register obj
|
|
|
|
obj.add_tag YARD::Tags::Tag.new(:api, 'public')
|
|
end
|
|
|
|
private
|
|
|
|
# Returns a {PuppetNamespaceObject} for holding functions. Creates this
|
|
# object if necessary.
|
|
#
|
|
# @return [PuppetNamespaceObject]
|
|
def function_namespace
|
|
# NOTE: This tricky. If there is ever a Ruby class or module with the
|
|
# name ::ParserFunctions, then there will be a clash. Hopefully the name
|
|
# is sufficiently uncommon.
|
|
obj = P(:root, 'FutureParserFunctions')
|
|
if obj.is_a? Proxy
|
|
namespace_obj = PuppetNamespaceObject.new(:root, 'FutureParserFunctions')
|
|
|
|
register namespace_obj
|
|
register_docstring(namespace_obj, '', nil)
|
|
namespace_obj.add_tag YARD::Tags::Tag.new(:api, 'public')
|
|
end
|
|
|
|
obj
|
|
end
|
|
|
|
# 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
|
|
# Passing `false` to prameters excludes the block param from the returned
|
|
# list.
|
|
name, _ = statement.parameters(false).compact
|
|
|
|
name = process_element(name)
|
|
|
|
name
|
|
end
|
|
|
|
# Sometimes the YARD parser returns Heredoc strings that start with `<-`
|
|
# instead of `<<-`.
|
|
HEREDOC_START = /^<?<-/
|
|
|
|
# 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 HEREDOC_START.match(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
|
|
end
|