Maint: Rewrite comments about symlinks to reflect best practice.

Don't use ensure => 'path/to/file', because it's hard to read. Use
ensure => link and specify a target =>.

2 files changed, 25 insertions, 18 deletions

diff --git a/lib/puppet/type/file/ensure.rb b/lib/puppet/type/file/ensure.rb
index 4a68551ee..99652ecc6 100755
--- a/lib/puppet/type/file/ensure.rb
+++ b/lib/puppet/type/file/ensure.rb
@@ -7,29 +7,23 @@ module Puppet
       if the file is missing will create an empty file. Specifying
       `absent` will delete the file (and directory if recurse => true).
 
-      Anything other than those values will be considered to be a symlink.
-      For instance, the following text creates a link:
+      Anything other than those values will create a symlink. In the interest of readability and clarity, you should use `ensure => link` and explicitly specify a
+      target; however, if a `target` attribute isn't provided, the value of the `ensure`
+      attribute will be used as the symlink target:
 
-          # Useful on solaris
+          # (Useful on Solaris)
+          # Less maintainable: 
           file { \"/etc/inetd.conf\":
-            ensure => \"/etc/inet/inetd.conf\"
+            ensure => \"/etc/inet/inetd.conf\",
           }
 
-      You can make relative links:
-
-          # Useful on solaris
+          # More maintainable:
           file { \"/etc/inetd.conf\":
-            ensure => \"inet/inetd.conf\"
+            ensure => link,
+            target => \"/etc/inet/inetd.conf\",
           }
-
-      If you need to make a relative link to a file named the same
-      as one of the valid values, you must prefix it with `./` or
-      something similar.
-
-      You can also make recursive symlinks, which will create a
-      directory structure that maps to the target directory,
-      with directories corresponding to each directory
-      and links corresponding to each file."
+      
+      These two declarations are equivalent."
 
     # Most 'ensure' properties have a default, but with files we, um, don't.
     nodefault
diff --git a/lib/puppet/type/file/target.rb b/lib/puppet/type/file/target.rb
index b9fe9213b..7d391e672 100644
--- a/lib/puppet/type/file/target.rb
+++ b/lib/puppet/type/file/target.rb
@@ -1,7 +1,20 @@
 module Puppet
   Puppet::Type.type(:file).newproperty(:target) do
     desc "The target for creating a link.  Currently, symlinks are the
-      only type supported."
+      only type supported.
+      
+      You can make relative links:
+
+          # (Useful on Solaris)
+          file { \"/etc/inetd.conf\":
+            ensure => link,
+            target => \"inet/inetd.conf\",
+          }
+    
+      You can also make recursive symlinks, which will create a
+      directory structure that maps to the target directory,
+      with directories corresponding to each directory
+      and links corresponding to each file."
 
     newvalue(:notlink) do
       # We do nothing if the value is absent