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


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

def copyright_owner
  @copyright_owner
end

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


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

def copyright_years
  @copyright_years
end

Instance Method Details

#author(value) ⇒ Object #authorString?

Overloads:

  • #author(value) ⇒ Object

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

  • #authorString?

    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


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

#authorsString

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.


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

def authors
  @authors
end

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.


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 #examplesString

Overloads:

  • #examples(text) ⇒ void

    This method returns an undefined value.

    Sets examples.

  • #examplesString

    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


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

attr_doc :examples

#license(text) ⇒ void #licenseString

Overloads:

  • #license(text) ⇒ void

    This method returns an undefined value.

    Sets the license text

  • #licenseString

    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


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

attr_doc :license

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
352
353
354
# 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+$/
        part.to_i
      else
        found = part.split(/-/)
        if found
          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
    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 #notesString

Overloads:

  • #notes(text) ⇒ void

    This method returns an undefined value.

    Sets optional notes.

  • #notesString

    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


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

attr_doc :notes

#short_description(value) ⇒ void #short_descriptionString?

Overloads:

  • #short_description(value) ⇒ void

    This method returns an undefined value.

    Sets a short description for this object.

  • #short_descriptionString?

    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


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