Module: Puppet::Interface::FullDocs

Extended by:
DocGen
Includes:
TinyDocs
Included in:
Puppet::Interface, Action
Defined in:
lib/puppet/interface/documentation.rb

Overview

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

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Methods included from DocGen

attr_doc, strip_whitespace

Methods included from TinyDocs

#build_synopsis, #description, #summary

Instance Attribute Details

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Sets the copyright owner

Parameters:

  • value (String, Array<String>) —

    The copyright owner or owners.

Returns:

  • (String) —

    Comma-separated list of copyright owners



275
276
277
 
# File 'lib/puppet/interface/documentation.rb', line 275

def copyright_owner
  @copyright_owner
end

- (String) copyright_years  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Sets the copyright year

Parameters:

  • value (Integer, Range<Integer>, Array<Integer, Range>) —

    The copyright year or years.

Returns:

  • (String) 


291
292
293
 
# File 'lib/puppet/interface/documentation.rb', line 291

def copyright_years
  @copyright_years
end

Instance Method Details

- (Object) author=(value)  private Also known as: authors=

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



234
235
236
237
238
239
240
241
 
# File 'lib/puppet/interface/documentation.rb', line 234

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

- (String) authors  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a list of authors. See author.

Returns:

  • (String) —

    The list of authors, separated by newlines.



229
230
231
 
# File 'lib/puppet/interface/documentation.rb', line 229

def authors
  @authors
end

- (String) copyright(owner = nil, years = nil)  DSL

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.

Parameters:

  • owner (String, Array<String>) (defaults to: nil) —

    The copyright owner or an array of owners

  • years (Integer, Range<Integer>, Array<Integer,Range<Integer>>) (defaults to: nil) —

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

Returns:

  • (String) —

    A string describing the copyright on this object.

DSL:

  • Faces



256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/puppet/interface/documentation.rb', line 256

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

- (Object) munge_copyright_year(input)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
 
# File 'lib/puppet/interface/documentation.rb', line 307

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