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


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

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

Parameters:

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

    The copyright year or years.

Returns:

  • (String)

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

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.

    Parameters:

    • value (String)

      the name of the 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

    Returns:

    • (String, nil)

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


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

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.


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

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.

Returns:

  • (String)

    The list of authors, separated by newlines.


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

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.

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.


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

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.

    Parameters:

    • text (String)

      Example text

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

    Returns:

    • (String)

      The examples


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

attr_doc :examples

#license(text) ⇒ void #licenseString

Overloads:

  • #license(text) ⇒ void

    This method returns an undefined value.

    Sets the license text

    Parameters:

    • text (String)

      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

    Returns:

    • (String)

      The license


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

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.


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
355
# File 'lib/puppet/interface/documentation.rb', line 302

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.

    Parameters:

    • text (String)

      The 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

    Returns:

    • (String)

      The notes


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

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.

    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_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

    Returns:


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

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