updating changelog and docs for :alias

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

2 files changed, 36 insertions, 17 deletions

diff --git a/lib/puppet/statechange.rb b/lib/puppet/statechange.rb
index b260f0bd3..b77931c4e 100644
--- a/lib/puppet/statechange.rb
+++ b/lib/puppet/statechange.rb
@@ -37,7 +37,8 @@ module Puppet
                 return nil
             end
 
-            #@state.info "Is: %s, Should: %s" % [@state.is.inspect, @state.should.inspect]
+            #@state.info "Is: %s, Should: %s" %
+            #    [@state.is.inspect, @state.should.inspect]
 
             begin
                 events = @state.sync
diff --git a/lib/puppet/type.rb b/lib/puppet/type.rb
index df001bc7d..a03a5dfd5 100644
--- a/lib/puppet/type.rb
+++ b/lib/puppet/type.rb
@@ -2123,26 +2123,44 @@ class Type < Puppet::Element
     end
 
     newmetaparam(:alias) do
-        desc "Creates an alias for the object.  This simplifies lookup of the
-            object so is useful in the language.  It is especially useful when
-            you are creating long commands using exec or when many different
-            systems call a given package_ different names::
-
+        desc "Creates an alias for the object.  Puppet uses this internally when you
+            provide a symbolic name:
             
-                file { \"/usr/local/scripts/myscript\":
-                    source => \"puppet://server/module/myscript\",
-                    mode => 755,
-                    alias => myscript
+                file { sshdconfig:
+                    path => $operatingsystem ? {
+                        solaris => \"/usr/local/etc/ssh/sshd_config\",
+                        default => \"/etc/ssh/sshd_config\"
+                    },
+                    source => \"...\"
                 }
 
-                exec { \"/usr/local/scripts/myscript\":
-                    require => file[myscript]
+                service { sshd:
+                    subscribe => file[sshdconfig]
                 }
-            
-            Again, this is somewhat redundant, since any sane person would
-            just use a variable (unless the two statements were in different
-            scopes), and Puppet will autorequire the script anyway, but it
-            gets the point across."
+
+            When you use this feature, the parser sets *sshdconfig* as the name,
+            and the library sets that as an alias for the file so the dependency
+            lookup for *sshd* works.  You can use this parameter yourself,
+            but note that only the library can use these aliases; for instance,
+            the following code will not work:
+
+                file { \"/etc/ssh/sshd_config\":
+                    owner => root,
+                    group => root,
+                    alias => sshdconfig
+                }
+
+                file { sshdconfig:
+                    mode => 644
+                }
+
+            There's no way here for the Puppet parser to know that these two stanzas
+            should be affecting the same file.
+
+            See the `language tutorial`_ for more information.
+
+            .. _language tutorial: http://reductivelabs.com/projects/puppet/documentation/languagetutorial
+            "
 
         munge do |aliases|
             unless aliases.is_a?(Array)