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



268
269
270
 
# File 'lib/puppet/interface/documentation.rb', line 268

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) 


285
286
287
 
# File 'lib/puppet/interface/documentation.rb', line 285

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.



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

def author(value = nil)
  unless value.nil? then
    unless value.is_a? String
      #TRANSLATORS 'author' is an attribute name and should not be translated
      raise ArgumentError, _('author must be a string; use multiple statements for multiple authors')
    end

    if value =~ /\n/ then
      #TRANSLATORS 'author' is an attribute name and should not be translated
      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. 



225
226
227
228
229
230
231
232
233
 
# File 'lib/puppet/interface/documentation.rb', line 225

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
    #TRANSLATORS 'author' is an attribute name and should not be translated
    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.



220
221
222
 
# File 'lib/puppet/interface/documentation.rb', line 220

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.



248
249
250
251
252
253
254
255
256
257
258
259
260
261
 
# File 'lib/puppet/interface/documentation.rb', line 248

def copyright(owner = nil, years = nil)
  if years.nil? and not owner.nil? then
    #TRANSLATORS 'copyright' is an attribute name and should not be translated
    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



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

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



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

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. 



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
341
342
343
344
345
346
347
348
349
350
351
 
# File 'lib/puppet/interface/documentation.rb', line 301

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
      #TRANSLATORS 'copyright' is an attribute name and should not be translated
      raise ArgumentError, _("copyright with a year %{value} is very strange; did you accidentally add or subtract two years?") %
          { value: fault }
    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+$/ }
          #TRANSLATORS 'copyright' is an attribute name and should not be translated
          raise ArgumentError, _("%{value} is not a good copyright year or range") % { value: part.inspect }
        end
        Range.new(found[0].to_i, found[1].to_i)
      else
        #TRANSLATORS 'copyright' is an attribute name and should not be translated
        raise ArgumentError, _("%{value} is not a good copyright year or range") % { value: part.inspect }
      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
    #TRANSLATORS 'copyright' is an attribute name and should not be translated
    raise ArgumentError, _("%{value} is not a good copyright year, set, or range") % { value: input.inspect }
  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



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

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:



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

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