(#5944) Improve documentation of defined() function

The differences in the way defined() handles different types of entities weren't well-explained. Documentation was also added for the behavior of defined(Node["somenode.domain.com"]).

1 files changed, 41 insertions, 6 deletions

diff --git a/lib/puppet/parser/functions/defined.rb b/lib/puppet/parser/functions/defined.rb
index 90632af2f..c3efc5f76 100644
--- a/lib/puppet/parser/functions/defined.rb
+++ b/lib/puppet/parser/functions/defined.rb
@@ -1,10 +1,45 @@
 # Test whether a given class or definition is defined
-Puppet::Parser::Functions::newfunction(:defined, :type => :rvalue, :doc => "Determine whether a given
-  type is defined, either as a native type or a defined type, or whether a class is defined.
-  This is useful for checking whether a class is defined and only including it if it is.
-  This function can also test whether a resource has been defined, using resource references
-  (e.g., `if defined(File['/tmp/myfile']) { ... }`).  This function is unfortunately
-  dependent on the parse order of the configuration when testing whether a resource is defined.") do |vals|
+Puppet::Parser::Functions::newfunction(:defined, :type => :rvalue, :doc => "Determine whether
+  a given type, class, resource, or node is defined, and return
+  true or false. Accepts class names, type names, resource references, and node
+  references.
+  
+  The `defined` function checks both native and defined types, including types
+  provided as plugins via modules. Types are checked using their names:
+  
+      defined(\"file\")
+      defined(\"customtype\")
+  
+  Classes are also checked using their names:
+  
+      defined(\"foo\")
+      defined(\"foo::bar\")
+  
+  Unlike classes and types, resource definitions are checked using resource
+  references, e.g. `defined( File['/tmp/myfile'] )`. Checking whether a given
+  resource defined is, unfortunately, dependent on the parse order of the
+  configuration, and the following code will not work:
+  
+      if defined(File['/tmp/foo']) {
+          notify(\"This configuration includes the /tmp/foo file.\")
+      }
+      file {\"/tmp/foo\":
+          ensure => present,
+      }
+  
+  However, this order requirement refers to parse order only, and ordering of
+  resources in the configuration graph (e.g. with `begin` or `require`) does not
+  affect the behavior of `defined`.
+  
+  You can also use `defined` to check whether a node is defined using syntax
+  resembling a resource reference, like `Node[\"testnode.domain.com\"]`. This usage
+  is not necessarily recommended, and is included here only in the spirit of
+  completeness. Checking for node definitions behaves differently from the other
+  uses of `defined`: it will only return true if a definition for the specified
+  node (the name of which must match exactly) exists in the manifest **AND** the
+  specified node matches the node whose configuration is being compiled (either
+  directly or through node inheritance). The `define` function cannot be used to
+  introspect information returned by an external node classifier. ") do |vals|
     result = false
     vals = [vals] unless vals.is_a?(Array)
     vals.each do |val|