puppet 3.0.2 → 3.1.0.rc1

data/lib/puppet/interface/action.rb

@@ -3,11 +3,17 @@ require 'puppet/interface/documentation'
 require 'puppet/util/methodhelper'
 require 'prettyprint'
 
+# This represents an action that is attached to a face. Actions should
+# be constructed by calling {Puppet::Interface::ActionManager#action},
+# which is available on {Puppet::Interface}, and then calling methods of
+# {Puppet::Interface::ActionBuilder} in the supplied block.
+# @api private
 class Puppet::Interface::Action
   include Puppet::Util::MethodHelper
   extend  Puppet::Interface::DocGen
   include Puppet::Interface::FullDocs
 
+  # @api private
   def initialize(face, name, attrs = {})
     raise "#{name.inspect} is an invalid action name" unless name.to_s =~ /^[a-z]\w*$/
     @face    = face
@@ -32,6 +38,9 @@ class Puppet::Interface::Action
   # This is not nice, but it is the easiest way to make us behave like the
   # Ruby Method object rather than UnboundMethod.  Duplication is vaguely
   # annoying, but at least we are a shallow clone. --daniel 2011-04-12
+
+  # @return [void]
+  # @api private
   def __dup_and_rebind_to(to)
     bound_version = self.dup
     bound_version.instance_variable_set(:@face, to)
@@ -40,8 +49,17 @@ class Puppet::Interface::Action
 
   def to_s() "#{@face}##{@name}" end
 
+  # The name of this action
+  # @return [Symbol]
   attr_reader   :name
+
+  # The face this action is attached to
+  # @return [Puppet::Interface]
   attr_reader   :face
+
+  # Whether this is the default action for the face
+  # @return [Boolean]
+  # @api private
   attr_accessor :default
   def default?
     !!@default
@@ -57,6 +75,9 @@ class Puppet::Interface::Action
 
   ########################################################################
   # Support for rendering formats and all.
+
+
+  # @api private
   def when_rendering(type)
     unless type.is_a? Symbol
       raise ArgumentError, "The rendering format must be a symbol, not #{type.class.name}"
@@ -71,6 +92,8 @@ class Puppet::Interface::Action
     # Guess not, nothing to run.
     return nil
   end
+
+  # @api private
   def set_rendering_method_for(type, proc)
     unless proc.is_a? Proc
       msg = "The second argument to set_rendering_method_for must be a Proc"
@@ -103,12 +126,16 @@ class Puppet::Interface::Action
       @face.__send__( :__add_method, __render_method_name_for(type), proc)
   end
 
+  # @return [void]
+  # @api private
   def __render_method_name_for(type)
     :"#{name}_when_rendering_#{type}"
   end
   private :__render_method_name_for
 
 
+  # @api private
+  # @return [Symbol]
   attr_accessor :render_as
   def render_as=(value)
     @render_as = value.to_sym
@@ -169,7 +196,14 @@ class Puppet::Interface::Action
   # this stuff work, because it would have been cleaner.  Which gives you an
   # idea how motivated we were to make this cleaner.  Sorry.
   # --daniel 2011-03-31
+
+
+  # The arity of the action
+  # @return [Integer]
   attr_reader   :positional_arg_count
+
+  # The block that is executed when the action is invoked
+  # @return [block]
   attr_accessor :when_invoked
   def when_invoked=(block)
 
@@ -249,7 +283,7 @@ WRAPPER
   def options
     @face.options + @options
   end
-  
+
   def add_display_global_options(*args)
     @display_global_options ||= []
     [args].flatten.each do |refopt|
@@ -259,12 +293,12 @@ WRAPPER
     @display_global_options.uniq!
     @display_global_options
   end
-  
+
   def display_global_options(*args)
     args ? add_display_global_options(args) : @display_global_options + @face.display_global_options 
   end
   alias :display_global_option :display_global_options
-  
+
   def get_option(name, with_inherited_options = true)
     option = @options_hash[name.to_sym]
     if option.nil? and with_inherited_options
@@ -334,6 +368,8 @@ WRAPPER
   # Support code for action decoration; see puppet/interface.rb for the gory
   # details of why this is hidden away behind private. --daniel 2011-04-15
   private
+  # @return [void]
+  # @api private
   def __add_method(name, proc)
     @face.__send__ :__add_method, name, proc
   end

data/lib/puppet/interface/action_builder.rb

@@ -1,9 +1,20 @@
 require 'puppet/interface'
 require 'puppet/interface/action'
 
+# This class is used to build {Puppet::Interface::Action actions}.
+# When an action is defined with
+# {Puppet::Interface::ActionManager#action} the block is evaluated
+# within the context of a new instance of this class.
+# @api public
 class Puppet::Interface::ActionBuilder
+  # The action under construction
+  # @return [Puppet::Interface::Action]
+  # @api private
   attr_reader :action
 
+  # Builds a new action.
+  # @return [Puppet::Interface::Action]
+  # @api private
   def self.build(face, name, &block)
     raise "Action #{name.inspect} must specify a block" unless block
     new(face, name, &block).action
@@ -12,10 +23,33 @@ class Puppet::Interface::ActionBuilder
   # Ideally the method we're defining here would be added to the action, and a
   # method on the face would defer to it, but we can't get scope correct, so
   # we stick with this. --daniel 2011-03-24
+
+  # Sets what the action does when it is invoked. This takes a block
+  # which will be called when the action is invoked. The action will
+  # accept arguments based on the arity of the block. It should always
+  # take at least one argument for options. Options will be the last
+  # argument.
+  #
+  # @overload when_invoked({|options| ... })
+  #   An action with no arguments
+  # @overload when_invoked({|arg1, arg2, options| ... })
+  #   An action with two arguments
+  # @return [void]
+  # @api public
+  # @dsl Faces
   def when_invoked(&block)
     @action.when_invoked = block
   end
 
+  # Sets a block to be run at the rendering stage, for a specific
+  # rendering type (eg JSON, YAML, console), after the block for
+  # when_invoked gets run. This manipulates the value returned by the
+  # action. It makes it possible to work around limitations in the
+  # underlying object returned, and should be avoided in favor of
+  # returning a more capable object.
+  # @api private
+  # @todo this needs more
+  # @dsl Faces
   def when_rendering(type = nil, &block)
     if type.nil? then           # the default error message sucks --daniel 2011-04-18
       raise ArgumentError, 'You must give a rendering format to when_rendering'
@@ -26,20 +60,59 @@ class Puppet::Interface::ActionBuilder
     @action.set_rendering_method_for(type, block)
   end
 
+  # Declare that this action can take a specific option, and provide the
+  # code to do so.  One or more strings are given, in the style of
+  # OptionParser (see example). These strings are parsed to derive a
+  # name for the option. Any `-` characters within the option name (ie
+  # excluding the intial `-` or `--` for an option) will be translated
+  # to `_`.The first long option will be used as the name, and the rest
+  # are retained as aliases. The original form of the option is used
+  # when invoking the face, the translated form is used internally.
+  #
+  # When the action is invoked the value of the option is available in
+  # a hash passed to the {Puppet::Interface::ActionBuilder#when_invoked
+  # when_invoked} block, using the option name in symbol form as the
+  # hash key.
+  #
+  # The block to this method is used to set attributes for the option
+  # (see {Puppet::Interface::OptionBuilder}).
+  #
+  # @param declaration [String] Option declarations, as described above
+  #   and in the example.
+  #
+  # @example Say hi
+  #   action :say_hi do
+  #     option "-u USER", "--user-name USER" do
+  #       summary "Who to say hi to"
+  #     end
+  #
+  #     when_invoked do |options|
+  #       "Hi, #{options[:user_name]}"
+  #     end
+  #   end
+  # @api public
+  # @dsl Faces
   def option(*declaration, &block)
     option = Puppet::Interface::OptionBuilder.build(@action, *declaration, &block)
     @action.add_option(option)
   end
 
+  # Set this as the default action for the face.
+  # @api public
+  # @dsl Faces
+  # @return [void]
   def default(value = true)
     @action.default = !!value
   end
-  
+
+  # @api private
   def display_global_options(*args)
     @action.add_display_global_options args
   end
   alias :display_global_option :display_global_options
 
+  # Sets the default rendering format
+  # @api private
   def render_as(value = nil)
     value.nil? and raise ArgumentError, "You must give a rendering format to render_as"
 

data/lib/puppet/interface/action_manager.rb

@@ -1,15 +1,30 @@
 require 'puppet/interface/action'
 require 'puppet/interface/action_builder'
 
+# This class is not actually public API, but the method
+# {Puppet::Interface::ActionManager#action action} is public when used
+# as part of the Faces DSL (i.e. from within a
+# {Puppet::Interface.define define} block).
+# @api public
 module Puppet::Interface::ActionManager
   # Declare that this app can take a specific action, and provide
   # the code to do so.
+
+  # Defines a new action. This takes a block to build the action using
+  # the methods on {Puppet::Interface::ActionBuilder}.
+  # @param name [Symbol] The name that will be used to invoke the
+  #   action
+  # @overload action(name, {|| block})
+  # @return [void]
+  # @api public
+  # @dsl Faces
   def action(name, &block)
     @actions ||= {}
     Puppet.warning "Redefining action #{name} for #{self}" if action?(name)
 
     action = Puppet::Interface::ActionBuilder.build(self, name, &block)
 
+    # REVISIT: (#18042) doesn't this mean we can't redefine the default action? -- josh
     if action.default and current = get_default_action
       raise "Actions #{current.name} and #{name} cannot both be default"
     end
@@ -17,14 +32,21 @@ module Puppet::Interface::ActionManager
     @actions[action.name] = action
   end
 
-  # This is the short-form of an action definition; it doesn't use the
-  # builder, just creates the action directly from the block.
+  # Defines an action without using ActionBuilder. The block given is
+  # the code that will be executed when the action is invoked.
+  # @api public
+  # @deprecated
   def script(name, &block)
     @actions ||= {}
-    raise "Action #{name} already defined for #{self}" if action?(name)
+    Puppet.warning "Redefining action #{name} for #{self}" if action?(name)
+
+    # REVISIT: (#18048) it's possible to create multiple default actions
     @actions[name] = Puppet::Interface::Action.new(self, name, :when_invoked => block)
   end
 
+  # Returns the list of available actions for this face.
+  # @return [Array<Symbol>] The names of the actions for this face
+  # @api private
   def actions
     @actions ||= {}
     result = @actions.keys
@@ -40,6 +62,10 @@ module Puppet::Interface::ActionManager
     result.uniq.sort
   end
 
+  # Retrieves a named action
+  # @param name [Symbol] The name of the action
+  # @return [Puppet::Interface::Action] The action object
+  # @api private
   def get_action(name)
     @actions ||= {}
     result = @actions[name.to_sym]
@@ -60,6 +86,9 @@ module Puppet::Interface::ActionManager
     return result
   end
 
+  # Retrieves the default action for the face
+  # @return [Puppet::Interface::Action]
+  # @api private
   def get_default_action
     default = actions.map {|x| get_action(x) }.select {|x| x.default }
     if default.length > 1
@@ -68,6 +97,7 @@ module Puppet::Interface::ActionManager
     default.first
   end
 
+  # @api private
   def action?(name)
     actions.include?(name.to_sym)
   end

data/lib/puppet/interface/documentation.rb

@@ -1,6 +1,7 @@
-# This isn't usable outside Puppet::Interface; don't load it alone.
 class Puppet::Interface
+  # @api private
   module DocGen
+    # @api private
     def self.strip_whitespace(text)
       text.gsub!(/[ \t\f]+$/, '')
 
@@ -25,6 +26,8 @@ class Puppet::Interface
     #
     # This feels a bit like overkill, but at least the common code is common
     # now. --daniel 2011-04-29
+
+    # @api private
     def attr_doc(name, &validate)
       # Now, which form of the setter do we want, validated or not?
       get_arg = "value.to_s"
@@ -51,17 +54,30 @@ class Puppet::Interface
     end
   end
 
+  # This module can be mixed in to provide a minimal set of
+  # documentation attributes.
+  # @api public
   module TinyDocs
     extend Puppet::Interface::DocGen
 
+    # @!method summary(summary)
+    # Sets a summary of this object.
+    # @api public
+    # @dsl Faces
     attr_doc :summary do |value|
       value =~ /\n/ and
         raise ArgumentError, "Face summary should be a single line; put the long text in 'description' instead."
       value
     end
 
+    # @!method description(description)
+    # Sets the long description of this object.
+    # @param description [String] The description of this object.
+    # @api public
+    # @dsl Faces
     attr_doc :description
 
+    # @api private
     def build_synopsis(face, action = nil, arguments = nil)
       output = PrettyPrint.format do |s|
         s.text("puppet #{face}")
@@ -85,13 +101,13 @@ class Puppet::Interface
 
           s.breakable
         end
-        
+
         display_global_options.sort.each do |option|
           wrap = %w{ [ ] }
           s.group(0, *wrap) do
-        		desc = Puppet.settings.setting(option).desc
-        		type = Puppet.settings.setting(option).default
-        		type ||= Puppet.settings.setting(option).type.to_s.upcase
+            desc = Puppet.settings.setting(option).desc
+            type = Puppet.settings.setting(option).default
+            type ||= Puppet.settings.setting(option).type.to_s.upcase
             s.text "--#{option} #{type}"
             s.breakable
           end
@@ -106,15 +122,68 @@ class Puppet::Interface
 
   end
 
+  # This module can be mixed in to provide a full set of documentation
+  # attributes. It is intended to be used for {Puppet::Interface}.
+  # @api public
   module FullDocs
     extend Puppet::Interface::DocGen
     include TinyDocs
 
+    # @!method examples
+    # @overload examples(text)
+    #   Sets examples.
+    #   @param text [String] Example text
+    #   @api public
+    #   @returns [void]
+    #   @dsl Faces
+    # @overload examples
+    #   Returns documentation of examples
+    #   @returns [String] The examples
+    #   @api private
     attr_doc :examples
+
+    # @!method notes(text)
+    # @overload notes(text)
+    #   Sets optional notes.
+    #   @param text [String] The notes
+    #   @api public
+    #   @returns [void]
+    #   @dsl Faces
+    # @overload notes
+    #   Returns any optional notes
+    #   @returns [String] The notes
+    #   @api private
     attr_doc :notes
+
+    # @!method license(text)
+    # @overload license(text)
+    #   Sets the license text
+    #   @param text [String] the license text
+    #   @api public
+    #   @returns [void]
+    #   @dsl Faces
+    # @overload license
+    #   Returns the license
+    #   @returns [String] The license
+    #   @api private
     attr_doc :license
 
     attr_doc :short_description
+    # @overload short_description(value)
+    #   Sets a short description for this object.
+    #   @param 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 {description}.
+    #   @return [void]
+    #   @api public
+    #   @dsl Faces
+    # @overload short_description
+    #   Get the short description for this object
+    #   @return [String, nil] The short description of this object. If none is
+    #     set it will be derived from {description}. Returns `nil` if
+    #     {description} is `nil`.
+    #   @api private
     def short_description(value = nil)
       self.short_description = value unless value.nil?
       if @short_description.nil? then
@@ -128,6 +197,17 @@ class Puppet::Interface
       @short_description
     end
 
+    # @overload author(value)
+    #   Adds an author to the documentation for this object. To set
+    #   multiple authors, call this once for each author.
+    #   @param value [String] the name of the author
+    #   @api public
+    #   @dsl Faces
+    # @overload author
+    #   Returns a list of authors
+    #   @return [String, nil] The names of all authors separated by
+    #     newlines, or `nil` if no authors have been set.
+    #   @api private
     def author(value = nil)
       unless value.nil? then
         unless value.is_a? String
@@ -141,10 +221,18 @@ class Puppet::Interface
       end
       @authors.empty? ? nil : @authors.join("\n")
     end
+
+    # Returns a list of authors. See {author}.
+    # @return [String] The list of authors, separated by newlines.
+    # @api private
     def authors
       @authors
     end
+
+    # @api private
     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
         raise ArgumentError, 'author should be a single line; use multiple statements'
       end
@@ -152,6 +240,18 @@ class Puppet::Interface
     end
     alias :authors= :author=
 
+    # 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.
+    # @param owner [String, Array<String>] The copyright owner or an
+    #   array of owners
+    # @param years [Integer, Range<Integer>, Array<Integer,Range<Integer>>]
+    #   The copyright year or years. Years can be specified with integers,
+    #   a range of integers, or an array of integers and ranges of
+    #   integers.
+    # @return [String] A string describing the copyright on this object.
+    # @api public
+    # @dsl Faces
     def copyright(owner = nil, years = nil)
       if years.nil? and not owner.nil? then
         raise ArgumentError, 'copyright takes the owners names, then the years covered'
@@ -166,6 +266,11 @@ class Puppet::Interface
       end
     end
 
+    # Sets the copyright owner
+    # @param value [String, Array<String>] The copyright owner or
+    #   owners.
+    # @return [String] Comma-separated list of copyright owners
+    # @api private
     attr_accessor :copyright_owner
     def copyright_owner=(value)
       case value
@@ -177,6 +282,11 @@ class Puppet::Interface
       @copyright_owner
     end
 
+    # Sets the copyright year
+    # @param value [Integer, Range<Integer>, Array<Integer, Range>] The
+    #   copyright year or years.
+    # @return [String]
+    # @api private
     attr_accessor :copyright_years
     def copyright_years=(value)
       years = munge_copyright_year value
@@ -192,6 +302,7 @@ class Puppet::Interface
       end.join(", ")
     end
 
+    # @api private
     def munge_copyright_year(input)
       case input
       when Range then input