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

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

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

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