Updated doc/big-picture doc/structures, Added rst formating to puppetdoc, and added doc strings for types, states, params, and metaparams.

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

10 files changed, 115 insertions, 20 deletions

diff --git a/lib/puppet/type.rb b/lib/puppet/type.rb
index 44818630f..22ae80f0f 100644
--- a/lib/puppet/type.rb
+++ b/lib/puppet/type.rb
@@ -35,6 +35,7 @@ require 'puppet/type/state'
 module Puppet
 class Type < Puppet::Element
     attr_accessor :children, :parameters, :parent
+    attr_accessor :paramdoc
     include Enumerable
 
     @@retrieved = Hash.new(0)
@@ -53,6 +54,8 @@ class Type < Puppet::Element
     @states = []
     @parameters = [:notused]
 
+    #@paramdoc = Hash.new
+
     # the methods that can be called from within the language
     @allowedmethods = [:noop,:debug,:statefile]
 
@@ -65,6 +68,23 @@ class Type < Puppet::Element
         :require
     ]
 
+    @@metaparamdoc = Hash.new { |hash,key|
+        if key.is_a?(String)
+            key = key.intern
+        end
+        if hash.include?(key)
+            hash[key]
+        else
+            "Metaparam Documentation for %s not found" % key
+        end
+    }
+
+    @@metaparamdoc[:onerror] = "Value to return on an error"
+    @@metaparamdoc[:noop] = "Boolean flag indicating not to change states"
+    @@metaparamdoc[:schedule] = "...to be documented..."
+    @@metaparamdoc[:check] = "... to be documented..."
+    @@metaparamdoc[:require] = "?List? of objects required to be handled first"
+   
     #---------------------------------------------------------------
     #---------------------------------------------------------------
     # class methods dealing with Type management
@@ -144,6 +164,17 @@ class Type < Puppet::Element
         @validstates = {}
         @validparameters = {}
 
+        @paramdoc = Hash.new { |hash,key|
+          if key.is_a?(String)
+            key = key.intern
+          end
+          if hash.include?(key)
+            hash[key]
+          else
+            "Param Documentation for %s not found" % key
+          end
+        }
+
         unless defined? @doc
             @doc = ""
         end
@@ -621,6 +652,19 @@ class Type < Puppet::Element
             @parameters = Hash.new(false)
         end
 
+        #unless defined? @paramdoc
+        #   @paramdoc = Hash.new { |hash,key|
+        #      if key.is_a?(String)
+        #         key = key.intern
+        #      end
+        #      if hash.include?(key)
+        #         hash[key]
+        #      else
+        #         "Param Documentation for %s not found" % key
+        #      end
+        #   }
+        #end
+
         @noop = false
 
         # which objects to notify when we change
@@ -1011,11 +1055,16 @@ class Type < Puppet::Element
     # Documentation methods
     #---------------------------------------------------------------
     #---------------------------------------------------------------
-    def self.paramdoc?(param)
+    def self.paramdoc(param)
         @paramdoc[param]
     end
     #---------------------------------------------------------------
     #---------------------------------------------------------------
+    def self.metaparamdoc(metaparam)
+        @@metaparamdoc[metaparam]
+    end
+    #---------------------------------------------------------------
+    #---------------------------------------------------------------
 end # Puppet::Type
 end
 
diff --git a/lib/puppet/type/component.rb b/lib/puppet/type/component.rb
index 901d89326..2274c7c10 100644
--- a/lib/puppet/type/component.rb
+++ b/lib/puppet/type/component.rb
@@ -19,19 +19,6 @@ module Puppet
         @states = []
         @parameters = [:name,:type]
 
-        # yeah, this doc stuff is all pretty worthless right now
-        @doc = %{
-Component
----------
-}
-
-        @paramdoc = {
-            :name => %{
-},
-            :type => %{
-}
-        }
-
         def each
             @children.each { |child| yield child }
         end
diff --git a/lib/puppet/type/exec.rb b/lib/puppet/type/exec.rb
index 67eddcc66..81b38450f 100755
--- a/lib/puppet/type/exec.rb
+++ b/lib/puppet/type/exec.rb
@@ -12,6 +12,7 @@ module Puppet
         class Returns < Puppet::State
             attr_reader :output
 
+            @doc = "..."
             @name = :returns
 
             # because this command always runs,
@@ -127,6 +128,13 @@ module Puppet
                 :command
             ]
 
+            @paramdoc[:path] = "..."
+            @paramdoc[:user] = "..."
+            @paramdoc[:cwd] = "..."
+            @paramdoc[:refreshonly] = "..."
+            @paramdoc[:command] = "..."
+
+            @doc = "Allows shell commands to be executed"
             @name = :exec
             @namevar = :command
 
diff --git a/lib/puppet/type/package.rb b/lib/puppet/type/package.rb
index b551ad65f..3805d3747 100644
--- a/lib/puppet/type/package.rb
+++ b/lib/puppet/type/package.rb
@@ -11,6 +11,8 @@ module Puppet
         class PackageInstalled < Puppet::State
             @name = :install
 
+            @doc = "boolean flag for defining the package to be installed"
+
             def retrieve
                 unless defined? @is
                     @parent.retrieve
@@ -82,6 +84,18 @@ module Puppet
                 :description
             ]
 
+            @paramdoc[:name] = "..."
+            @paramdoc[:type] = "..."
+            @paramdoc[:instance] = "..."
+            @paramdoc[:status] = "..."
+            @paramdoc[:version] = "..."
+            @paramdoc[:category] = "..."
+            @paramdoc[:platform] = "..."
+            @paramdoc[:root] = "..."
+            @paramdoc[:vendor] = "..."
+            @paramdoc[:description] = "..."
+
+            @doc = "Allows control of package objects"
             @name = :package
             @namevar = :name
             @listed = false
diff --git a/lib/puppet/type/pfile.rb b/lib/puppet/type/pfile.rb
index 52ae06b67..f22a0fe0f 100644
--- a/lib/puppet/type/pfile.rb
+++ b/lib/puppet/type/pfile.rb
@@ -14,6 +14,7 @@ module Puppet
     class State
         class PFileCreate < Puppet::State
             require 'etc'
+            @doc = "boolean flag to create file if it doesn't already exist"
             @name = :create
             @event = :file_created
 
@@ -85,7 +86,7 @@ module Puppet
 
         class PFileChecksum < Puppet::State
             attr_accessor :checktype
-
+            @doc = "String type of checksum used to validate file contents. Example: md5"
             @name = :checksum
             @event = :file_modified
 
@@ -256,6 +257,7 @@ module Puppet
 
         class PFileUID < Puppet::State
             require 'etc'
+            @doc = "String owner of file"
             @name = :owner
             @event = :inode_changed
 
@@ -374,7 +376,7 @@ module Puppet
         # I think MetaStates are the answer, but I'm not quite sure
         class PFileMode < Puppet::State
             require 'etc'
-
+            @doc = "Four digit mode setting: example 0755"
             @name = :mode
             @event = :inode_changed
 
@@ -456,7 +458,7 @@ module Puppet
         # metastates
         class PFileSetUID < Puppet::State
             require 'etc'
-
+            @doc = "Used to set UID"
             @parent = Puppet::State::PFileMode
 
             @name = :setuid
@@ -484,7 +486,7 @@ module Puppet
 
         class PFileGroup < Puppet::State
             require 'etc'
-
+            @doc = "String group of file"
             @name = :group
             @event = :inode_changed
 
@@ -585,7 +587,7 @@ module Puppet
 
         class PFileCopy < Puppet::State
             attr_accessor :source, :local
-
+            @doc = "...to be documented..."
             @name = :copy
 
             def retrieve
@@ -731,7 +733,7 @@ module Puppet
     class Type
         class PFile < Type
             attr_reader :params, :source, :srcbase
-
+            @doc = "Allows control of files"
             # class instance variable
                 #Puppet::State::PFileSource,
             @states = [
@@ -752,6 +754,12 @@ module Puppet
                 :source,
                 :filebucket
             ]
+            @paramdoc[:path] = "..."
+            @paramdoc[:backup] = "..."
+            @paramdoc[:linkmaker] = "..."
+            @paramdoc[:recurse] = "..."
+            @paramdoc[:source] = "..."
+            @paramdoc[:filebucket] = "..."
 
             @name = :file
             @namevar = :path
diff --git a/lib/puppet/type/pprocess.rb b/lib/puppet/type/pprocess.rb
index 78e7b6091..fe9bb7c71 100644
--- a/lib/puppet/type/pprocess.rb
+++ b/lib/puppet/type/pprocess.rb
@@ -6,6 +6,7 @@
 module Puppet
     class State
         class PProcessRunning < State
+            @doc = "...to be documented..."
             def retrieve
                 running = 0
                 regex = Regexp.new(@params[:pattern])
@@ -62,6 +63,14 @@ module Puppet
 			attr_reader :stat, :path
 			@parameters = [:start, :stop, :user, :pattern, :binary, :arguments]
             @name = :process
+                        @paramdoc[:start] = "...to be documented..."
+                        @paramdoc[:stop] = "...to be documented..."
+                        @paramdoc[:user] = "...to be documented..."
+                        @paramdoc[:pattern] = "...to be documented..."
+                        @paramdoc[:binary] = "...to be documented..."
+                        @paramdoc[:arguments] = "...to be documented..."
+
+                        @doc = "...to be documented..."
 
 			@namevar = :pattern
 
diff --git a/lib/puppet/type/service.rb b/lib/puppet/type/service.rb
index 28e9275a6..48a19a154 100644
--- a/lib/puppet/type/service.rb
+++ b/lib/puppet/type/service.rb
@@ -11,6 +11,7 @@
 module Puppet
     class State
         class ServiceRunning < State
+            @doc = "Boolean flag indicating if service should be running"
             @name = :running
             #@event = :file_created
 
@@ -105,10 +106,15 @@ module Puppet
                 :path
             ]
 
+            @paramdoc[:name] = "..."
+            @paramdoc[:pattern] = "..."
+            @paramdoc[:path] = "..."
+
             @functions = [
                 :setpath
             ]
 
+            @doc = "Allows control of services managed by the node"
             @name = :service
 			@namevar = :name
 
diff --git a/lib/puppet/type/state.rb b/lib/puppet/type/state.rb
index 716f6336c..38cd51fa9 100644
--- a/lib/puppet/type/state.rb
+++ b/lib/puppet/type/state.rb
@@ -123,5 +123,11 @@ class State < Puppet::Element
         return "%s(%s)" % [@parent.name,self.name]
     end
     #---------------------------------------------------------------
+
+    #---------------------------------------------------------------
+    def self.doc
+        @doc
+    end
+    #---------------------------------------------------------------
 end
 end
diff --git a/lib/puppet/type/symlink.rb b/lib/puppet/type/symlink.rb
index 3c0140401..4cbd67083 100755
--- a/lib/puppet/type/symlink.rb
+++ b/lib/puppet/type/symlink.rb
@@ -14,6 +14,7 @@ module Puppet
             require 'etc'
             attr_reader :link
 
+            @doc = "... to be documented ..."
             @name = :link
 
             # create the link
@@ -97,6 +98,7 @@ module Puppet
             require 'etc'
             attr_accessor :file
 
+            @doc = "String file and path name pointed at by link"
             @name = :target
 
             def create
@@ -182,6 +184,9 @@ module Puppet
                 :recurse
             ]
 
+            @paramdoc[:path] = "Path of sym link to create"
+            @paramdoc[:recurse] = "If target is dir, recurse and link dir contents."
+            @doc = "Symbolic link of name from path to a target"
             @name = :symlink
             @namevar = :path
 
diff --git a/lib/puppet/type/typegen.rb b/lib/puppet/type/typegen.rb
index eafc58c66..9855ae99a 100644
--- a/lib/puppet/type/typegen.rb
+++ b/lib/puppet/type/typegen.rb
@@ -12,6 +12,7 @@ module Puppet
 class TypeGenerator < Puppet::Type
     include Enumerable
 
+    @doc = "..."
     @namevar = :name
     @name = :typegen
     @abstract = true
@@ -19,6 +20,8 @@ class TypeGenerator < Puppet::Type
     @parameters = [:name]
     @states = []
 
+    @paramdoc[:name] = "..."
+
     #---------------------------------------------------------------
     def TypeGenerator.[](name)
         return @subclasses[name]