more changes to documentation

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

7 files changed, 24 insertions, 15 deletions

diff --git a/lib/puppet/type.rb b/lib/puppet/type.rb
index 22ae80f0f..2d64740c7 100644
--- a/lib/puppet/type.rb
+++ b/lib/puppet/type.rb
@@ -79,11 +79,19 @@ class Type < Puppet::Element
         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"
+    @@metaparamdoc[:onerror] = "How to handle errors -- roll back innermost
+        transaction, roll back entire transaction, ignore, etc.  Currently
+        non-functional."
+    @@metaparamdoc[:noop] = "Boolean flag indicating whether work should actually
+        be done."
+    @@metaparamdoc[:schedule] = "On what schedule the object should be managed.
+        Currently non-functional."
+    @@metaparamdoc[:check] = "States which should have their values retrieved
+        but which should not actually be modified.  This is currently used
+        internally, but will eventually be used for querying."
+    @@metaparamdoc[:require] = "One or more objects that this object depends on.
+        Changes in the required objects result in the dependent objects being
+        refreshed (e.g., a service will get restarted)."
    
     #---------------------------------------------------------------
     #---------------------------------------------------------------
diff --git a/lib/puppet/type/exec.rb b/lib/puppet/type/exec.rb
index 9a2ef8094..4aa34c0fd 100755
--- a/lib/puppet/type/exec.rb
+++ b/lib/puppet/type/exec.rb
@@ -141,7 +141,7 @@ module Puppet
 
             @doc = "Executes external commands.  It is critical that all commands
                 executed using this mechanism can be run multiple times without
-                harm."
+                harm, i.e., they are *idempotent*."
             @name = :exec
             @namevar = :command
 
diff --git a/lib/puppet/type/package.rb b/lib/puppet/type/package.rb
index 1e82138bb..82bba1414 100644
--- a/lib/puppet/type/package.rb
+++ b/lib/puppet/type/package.rb
@@ -300,7 +300,8 @@ module Puppet
         class PackageInstalled < Puppet::State
             @name = :install
 
-            @doc = "What state the package should be in.  *true*/*false*/version"
+            @doc = "What state the package should be in.
+                *true*/*false*/``version``"
 
             def retrieve
                 unless defined? @is
@@ -375,7 +376,7 @@ module Puppet
 
             @paramdoc[:name] = "The package name."
             @paramdoc[:type] = "The package format.  Currently supports " +
-                PackagingType.types.collect{|p| "*" + p.to_s + "*"}.join(",") +
+                PackagingType.types.collect{|p| "``" + p.to_s + "``"}.join(", ") +
                 "."
             @paramdoc[:instance] = "A read-only parameter set by the package."
             @paramdoc[:status] = "A read-only parameter set by the package."
@@ -388,7 +389,7 @@ module Puppet
 
             @doc = "Manage packages.  Eventually will support retrieving packages
                 from remote sources but currently only supports packaging
-                systems which can retrieve their own packages, like *apt*."
+                systems which can retrieve their own packages, like ``apt``."
             @name = :package
             @namevar = :name
             @listed = false
diff --git a/lib/puppet/type/pfile.rb b/lib/puppet/type/pfile.rb
index 8a9bd8bda..5dc27290b 100644
--- a/lib/puppet/type/pfile.rb
+++ b/lib/puppet/type/pfile.rb
@@ -562,10 +562,10 @@ module Puppet
 
         class PFileCopy < Puppet::State
             attr_accessor :source, :local
-            @doc = "Copy a file over the current file.  Uses *checksum* to
+            @doc = "Copy a file over the current file.  Uses `checksum` to
                 determine when a file should be copied.  This is largely a support
-                state for the *source* parameter, which is what should generally
-                be used instead of *copy*."
+                state for the `source` parameter, which is what should generally
+                be used instead of `copy`."
             @name = :copy
 
             def retrieve
diff --git a/lib/puppet/type/pprocess.rb b/lib/puppet/type/pprocess.rb
index a49930754..b0b1a21d7 100644
--- a/lib/puppet/type/pprocess.rb
+++ b/lib/puppet/type/pprocess.rb
@@ -74,7 +74,7 @@ module Puppet
             @paramdoc[:binary] = "The binary to actually execute."
             @paramdoc[:arguments] = "The arguments to pass the binary."
 
-            @doc = "**Disabled.  Use *service* instead.** Manage running
+            @doc = "**Disabled.  Use `service` instead.** Manage running
                 processes."
 
 			@namevar = :pattern
diff --git a/lib/puppet/type/service.rb b/lib/puppet/type/service.rb
index 4c49fe86d..6d11dae99 100644
--- a/lib/puppet/type/service.rb
+++ b/lib/puppet/type/service.rb
@@ -118,7 +118,7 @@ module Puppet
             @doc = "Manage running services.  Rather than supporting managing
                 individual processes, puppet uses init scripts to simplify
                 specification of how to start, stop, or test processes.  The
-                *path* parameter is provided to enable creation of multiple
+                `path` parameter is provided to enable creation of multiple
                 init script directories, including supporting them for normal
                 users."
             @name = :service
diff --git a/lib/puppet/type/symlink.rb b/lib/puppet/type/symlink.rb
index b293de606..dca8f36ef 100755
--- a/lib/puppet/type/symlink.rb
+++ b/lib/puppet/type/symlink.rb
@@ -105,7 +105,7 @@ module Puppet
 
             @paramdoc[:path] = "Path of link to create."
             @paramdoc[:recurse] = "If target is a directory, recursively create
-                directories (using *file*'s *source* parameter) and link all
+                directories (using `file`'s `source` parameter) and link all
                 contained files."
             @doc = "Create symbolic links to existing files."
             @name = :symlink