# 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=
copyright(owner = nil, years = nil) click to toggle source

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