module Puppet::Interface::FullDocs

This module can be mixed in to provide a full set of documentation attributes. It is intended to be used for {Puppet::Interface}. @api public

Attributes

copyright_owner[RW]

Sets the copyright owner @param value [String, Array<String>] The copyright owner or

owners.

@return [String] Comma-separated list of copyright owners @api private

copyright_years[RW]

Sets the copyright year @param value [Integer, Range<Integer>, Array<Integer, Range>] The

copyright year or years.

@return [String] @api private

Public Instance Methods

author(value = nil) click to toggle source

@overload author(value)

Adds an author to the documentation for this object. To set
multiple authors, call this once for each author.
@param value [String] the name of the author
@api public
@dsl Faces

@overload author

Returns a list of authors
@return [String, nil] The names of all authors separated by
  newlines, or `nil` if no authors have been set.
@api private

# File lib/puppet/interface/documentation.rb, line 211
def author(value = nil)
  unless value.nil? then
    unless value.is_a? String
      raise ArgumentError, 'author must be a string; use multiple statements for multiple authors'
    end

    if value =~ /\n/ then
      raise ArgumentError, 'author should be a single line; use multiple statements for multiple authors'
    end
    @authors.push(Puppet::Interface::DocGen.strip_whitespace(value))
  end
  @authors.empty? ? nil : @authors.join("\n")
end

author=(value) click to toggle source

@api private

# File lib/puppet/interface/documentation.rb, line 233
def author=(value)
  # I think it's a bug that this ends up being the exposed
  # version of `author` on ActionBuilder
  if Array(value).any? {|x| x =~ /\n/ } then
    raise ArgumentError, 'author should be a single line; use multiple statements'
  end
  @authors = Array(value).map{|x| Puppet::Interface::DocGen.strip_whitespace(x) }
end

Also aliased as: authors=

authors() click to toggle source

Returns a list of authors. See {author}. @return [String] The list of authors, separated by newlines. @api private

# File lib/puppet/interface/documentation.rb, line 228
def authors
  @authors
end

authors=(value)

Alias for: author=

Sets the copyright owner and year. This returns the copyright string, so it can be called with no arguments retrieve that string without side effects. @param owner [String, Array<String>] The copyright owner or an

array of owners

@param years [Integer, Range<Integer>, Array<Integer,Range<Integer>>]

The copyright year or years. Years can be specified with integers,
a range of integers, or an array of integers and ranges of
integers.

@return [String] A string describing the copyright on this object. @api public @dsl Faces

# File lib/puppet/interface/documentation.rb, line 255
def copyright(owner = nil, years = nil)
  if years.nil? and not owner.nil? then
    raise ArgumentError, 'copyright takes the owners names, then the years covered'
  end
  self.copyright_owner = owner unless owner.nil?
  self.copyright_years = years unless years.nil?

  if self.copyright_years or self.copyright_owner then
    "Copyright #{self.copyright_years} by #{self.copyright_owner}"
  else
    "Unknown copyright owner and years."
  end
end

copyright_owner=(value) click to toggle source

# File lib/puppet/interface/documentation.rb, line 275
def copyright_owner=(value)
  case value
  when String then @copyright_owner = value
  when Array  then @copyright_owner = value.join(", ")
  else
    raise ArgumentError, "copyright owner must be a string or an array of strings"
  end
  @copyright_owner
end

copyright_years=(value) click to toggle source

# File lib/puppet/interface/documentation.rb, line 291
def copyright_years=(value)
  years = munge_copyright_year value
  years = (years.is_a?(Array) ? years : [years]).
    sort_by do |x| x.is_a?(Range) ? x.first : x end

  @copyright_years = years.map do |year|
    if year.is_a? Range then
      "#{year.first}-#{year.last}"
    else
      year
    end
  end.join(", ")
end

munge_copyright_year(input) click to toggle source

@api private

# File lib/puppet/interface/documentation.rb, line 306
def munge_copyright_year(input)
  case input
  when Range then input
  when Integer then
    if input < 1970 then
      fault = "before 1970"
    elsif input > (future = Time.now.year + 2) then
      fault = "after #{future}"
    end
    if fault then
      raise ArgumentError, "copyright with a year #{fault} is very strange; did you accidentally add or subtract two years?"
    end

    input

  when String then
    input.strip.split(/,/).map do |part|
      part = part.strip
      if part =~ /^\d+$/ then
        part.to_i
      elsif found = part.split(/-/) then
        unless found.length == 2 and found.all? {|x| x.strip =~ /^\d+$/ }
          raise ArgumentError, "#{part.inspect} is not a good copyright year or range"
        end
        Range.new(found[0].to_i, found[1].to_i)
      else
        raise ArgumentError, "#{part.inspect} is not a good copyright year or range"
      end
    end

  when Array then
    result = []
    input.each do |item|
      item = munge_copyright_year item
      if item.is_a? Array
        result.concat item
      else
        result << item
      end
    end
    result

  else
    raise ArgumentError, "#{input.inspect} is not a good copyright year, set, or range"
  end
end

short_description(value = nil) click to toggle source

@overload #short_description(value)

Sets a short description for this object.
@param value [String, nil] A short description (about a paragraph)
  of this component. If `value` is `nil` the short_description
  will be set to the shorter of the first paragraph or the first
  five lines of {description}.
@return [void]
@api public
@dsl Faces

@overload #short_description

Get the short description for this object
@return [String, nil] The short description of this object. If none is
  set it will be derived from {description}. Returns `nil` if
  {description} is `nil`.
@api private

# File lib/puppet/interface/documentation.rb, line 187
def short_description(value = nil)
  self.short_description = value unless value.nil?
  if @short_description.nil? then
    return nil if @description.nil?
    lines = @description.split("\n")
    first_paragraph_break = lines.index('') || 5
    grab  = [5, first_paragraph_break].min
    @short_description = lines[0, grab].join("\n")
    @short_description += ' [...]' if (grab < lines.length and first_paragraph_break >= 5)
  end
  @short_description
end