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



263
264
265
 
# File 'lib/puppet/interface/documentation.rb', line 263

def copyright_owner
  @copyright_owner
end

#copyright_years ⇒ String

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) 


279
280
281
 
# File 'lib/puppet/interface/documentation.rb', line 279

def copyright_years
  @copyright_years
end

Instance Method Details

#author(value) ⇒ Object #author ⇒ String?

Overloads:

  • #author(value) ⇒ Object

    Adds an author to the documentation for this object. To set multiple authors, call this once for each author.

    Parameters:

    • value (String) —

      the name of the author

  • #author ⇒ String?

    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

    Returns:

    • (String, nil) —

      The names of all authors separated by newlines, or ‘nil` if no authors have been set.



200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/puppet/interface/documentation.rb', line 200

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) ⇒ Object 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. 



222
223
224
225
226
227
228
229
 
# File 'lib/puppet/interface/documentation.rb', line 222

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

#authors ⇒ String

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.



217
218
219
 
# File 'lib/puppet/interface/documentation.rb', line 217

def authors
  @authors
end

#copyright(owner = nil, years = nil) ⇒ String

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.



244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/puppet/interface/documentation.rb', line 244

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

#examples(text) ⇒ void #examples ⇒ String

Overloads:

  • #examples(text) ⇒ void

    This method returns an undefined value.

    Sets examples.

    Parameters:

    • text (String) —

      Example text

  • #examples ⇒ String

    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 documentation of examples

    Returns:

    • (String) —

      The examples



132
 
# File 'lib/puppet/interface/documentation.rb', line 132

attr_doc :examples

#license(text) ⇒ void #license ⇒ String

Overloads:

  • #license(text) ⇒ void

    This method returns an undefined value.

    Sets the license text

    Parameters:

    • text (String) —

      the license text

  • #license ⇒ String

    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 the license

    Returns:

    • (String) —

      The license



158
 
# File 'lib/puppet/interface/documentation.rb', line 158

attr_doc :license

#munge_copyright_year(input) ⇒ Object

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. 



295
296
297
298
299
300
301
302
303
304
305
306
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
 
# File 'lib/puppet/interface/documentation.rb', line 295

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

#notes(text) ⇒ void #notes ⇒ String

Overloads:

  • #notes(text) ⇒ void

    This method returns an undefined value.

    Sets optional notes.

    Parameters:

    • text (String) —

      The notes

  • #notes ⇒ String

    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 any optional notes

    Returns:

    • (String) —

      The notes



145
 
# File 'lib/puppet/interface/documentation.rb', line 145

attr_doc :notes

#short_description(value) ⇒ void #short_description ⇒ String?

Overloads:

  • #short_description(value) ⇒ void

    This method returns an undefined value.

    Sets a short description for this object.

    Parameters:

    • 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 TinyDocs#description.

  • #short_description ⇒ String?

    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.

    Get the short description for this object

    Returns:



176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/puppet/interface/documentation.rb', line 176

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