Updating doc system to add the list of valid values to the doc string, and tweaking a few docs.

git-svn-id: https://reductivelabs.com/svn/puppet/trunk@1183 980ebf18-57e1-0310-9a29-db15c13687c0

7 files changed, 74 insertions, 19 deletions

diff --git a/bin/puppetdoc b/bin/puppetdoc
index b8e6619cd..314d4078b 100755
--- a/bin/puppetdoc
+++ b/bin/puppetdoc
@@ -99,7 +99,12 @@ def scrub(text)
     # indent from every line.
     if text =~ /^(\s+)/
         indent = $1
-        return text.gsub(/^#{indent}/,'')
+        begin
+            return text.gsub(/^#{indent}/,'')
+        rescue => detail
+            puts detail.backtrace
+            puts detail
+        end
     else
         return text
     end
@@ -141,7 +146,12 @@ argument is approprite or not.
     }.each do |name, object|
         puts "* **#{name.to_s}** (*#{object.section.to_s}*)"
         puts ""
-        puts "  " + object.desc.gsub(/\n/, " ")
+        begin
+            puts "  " + object.desc.gsub(/\n/, " ")
+        rescue => detail
+            puts detail.backtrace
+            puts detail
+        end
         puts ""
     end
 
@@ -185,6 +195,7 @@ in your manifest, including defined components.
             puts indent(scrub(Puppet::Type.metaparamdoc(param)), $tab)
         }
     rescue => detail
+        puts detail.backtrace
         puts "incorrect metaparams: %s" % detail
         exit(1)
     end
diff --git a/lib/puppet/parameter.rb b/lib/puppet/parameter.rb
index e0e4ee54b..f88e412ec 100644
--- a/lib/puppet/parameter.rb
+++ b/lib/puppet/parameter.rb
@@ -19,6 +19,48 @@ module Puppet
                 end
             end
 
+            # Return a documentation string.  If there are valid values,
+            # then tack them onto the string.
+            def doc
+                @doc ||= ""
+
+                unless defined? @addeddocvals
+                    unless values.empty?
+                        if @aliasvalues.empty?
+                            @doc += "  Valid values are ``" +
+                                values.join("``, ``") + "``."
+                        else
+                            @doc += "  Valid values are "
+
+                            @doc += values.collect do |value|
+                                ary = @aliasvalues.find do |name, val|
+                                    val == value
+                                end
+                                if ary
+                                    "``%s`` (also called ``%s``)" % [value, ary[0]]
+                                else
+                                    "``#{value}``"
+                                end
+                            end.join(", ") + "."
+                        end
+                    end
+
+                    if defined? @parameterregexes and ! @parameterregexes.empty?
+                        regs = @parameterregexes
+                        if @parameterregexes.is_a? Hash
+                            regs = @parameterregexes.keys
+                        end
+                        unless regs.empty?
+                            @doc += "  Values can also match ``" +
+                                regs.join("``, ``") + "``."
+                        end
+                    end
+                    @addeddocvals = true
+                end
+
+                @doc
+            end
+
             def nodefault
                 if public_method_defined? :default
                     undef_method :default
diff --git a/lib/puppet/type.rb b/lib/puppet/type.rb
index d525a9f25..7e20f3731 100644
--- a/lib/puppet/type.rb
+++ b/lib/puppet/type.rb
@@ -2192,11 +2192,9 @@ class Type < Puppet::Element
     end
 
     newmetaparam(:loglevel) do
-        desc "Sets the level that information will be logged:
-             ``debug``, ``info``, ``verbose``, ``notice``, ``warning``,
-             ``err``, ``alert``, ``emerg`` or ``crit``.  The log levels have
-             the biggest impact when logs are sent to syslog (which is
-             currently the default)."
+        desc "Sets the level that information will be logged.
+             The log levels have the biggest impact when logs are sent to
+             syslog (which is currently the default)."
         defaultto :notice
 
         newvalues(*Puppet::Log.levels)
@@ -2277,9 +2275,9 @@ class Type < Puppet::Element
             be useful to add your own tags to a given element.
 
             Tags are currently useful for things like applying a subset of a
-            host's configuration:
+            host's configuration::
                 
-                puppetd -v --tag mytag --onetime
+                puppetd --test --tag mytag
 
             This way, when you're testing a configuration you can run just the
             portion you're testing."
diff --git a/lib/puppet/type/exec.rb b/lib/puppet/type/exec.rb
index 2e455e7de..1431c1903 100755
--- a/lib/puppet/type/exec.rb
+++ b/lib/puppet/type/exec.rb
@@ -283,8 +283,7 @@ module Puppet
                     }
                 
                 Note that only ``subscribe`` can trigger actions, not ``require``,
-                so it only makes sense to use ``refreshonly`` with ``subscribe``.
-                "
+                so it only makes sense to use ``refreshonly`` with ``subscribe``."
 
             newvalues(:true, :false)
 
diff --git a/lib/puppet/type/package.rb b/lib/puppet/type/package.rb
index 5dee20c7e..778b14b47 100644
--- a/lib/puppet/type/package.rb
+++ b/lib/puppet/type/package.rb
@@ -108,11 +108,10 @@ module Puppet
         end
 
         ensurable do
-            desc "What state the package should be in.  The primary options
-                are *installed* (also called *present*), *uninstalled* (also
-                called *absent*), and *latest*.  *latest* only makes sense for
-                those packaging formats that can retrieve new packages on
-                their own."
+            desc "What state the package should be in.
+                *latest* only makes sense for those packaging formats that can
+                retrieve new packages on their own and will throw an error on
+                those that cannot."
 
             attr_accessor :latest
 
diff --git a/lib/puppet/type/pfile.rb b/lib/puppet/type/pfile.rb
index ef55eef0e..33593a42b 100644
--- a/lib/puppet/type/pfile.rb
+++ b/lib/puppet/type/pfile.rb
@@ -97,10 +97,16 @@ module Puppet
 
         newparam(:recurse) do
             desc "Whether and how deeply to do recursive
-                management.  **false**/*true*/*inf*/*number*"
+                management."
 
+            newvalues(:true, :false, :inf, /^[0-9]+$/)
             munge do |value|
-                value
+                case value
+                when :true: true
+                when :false: false
+                else
+                    value
+                end
             end
         end
 
diff --git a/lib/puppet/type/pfile/ensure.rb b/lib/puppet/type/pfile/ensure.rb
index 9f44b780f..cb3b8ae3e 100755
--- a/lib/puppet/type/pfile/ensure.rb
+++ b/lib/puppet/type/pfile/ensure.rb
@@ -14,7 +14,7 @@ module Puppet
                     ensure => \"/etc/inet/inetd.conf\"
                 }
             
-            You can make relative links:
+            You can make relative links::
                 
                 # Useful on solaris
                 file { \"/etc/inetd.conf\":