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



273
274
275
 
# File 'lib/puppet/interface/documentation.rb', line 273

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) 


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

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.



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

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. 



228
229
230
231
232
233
234
235
236
237
 
# File 'lib/puppet/interface/documentation.rb', line 228

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.



223
224
225
 
# File 'lib/puppet/interface/documentation.rb', line 223

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.



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/puppet/interface/documentation.rb', line 252

def copyright(owner = nil, years = nil)
  if years.nil? and !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 copyright_years or copyright_owner then
    "Copyright #{copyright_years} by #{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



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

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



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

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. 



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
356
357
358
359
360
361
 
# 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
      # 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 #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



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

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:



178
179
180
181
182
183
184
185
186
187
188
189
190
 
# 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