Adding an Indirection reference, along with the work

necessary to support it.

11 files changed, 57 insertions, 12 deletions

diff --git a/lib/puppet/indirector/configuration/compiler.rb b/lib/puppet/indirector/configuration/compiler.rb
index 598f50451..a0726a433 100644
--- a/lib/puppet/indirector/configuration/compiler.rb
+++ b/lib/puppet/indirector/configuration/compiler.rb
@@ -5,9 +5,8 @@ require 'puppet/parser/interpreter'
 require 'yaml'
 
 class Puppet::Node::Configuration::Compiler < Puppet::Indirector::Code
-    desc "Puppet's configuration compilation interface.  Passed a node name
-        or other key, retrieves information about the node (using the ``node_source``)
-        and returns a compiled configuration."
+    desc "Puppet's configuration compilation interface, and its back-end is
+        Puppet's compiler"
 
     include Puppet::Util
 
diff --git a/lib/puppet/indirector/facts/facter.rb b/lib/puppet/indirector/facts/facter.rb
index e3e82c9e6..96d22e0c1 100644
--- a/lib/puppet/indirector/facts/facter.rb
+++ b/lib/puppet/indirector/facts/facter.rb
@@ -3,7 +3,7 @@ require 'puppet/indirector/code'
 
 class Puppet::Node::Facts::Facter < Puppet::Indirector::Code
     desc "Retrieve facts from Facter.  This provides a somewhat abstract interface
-        between Puppet and Facter.  It's only 'somewhat' abstract because it always
+        between Puppet and Facter.  It's only `somewhat` abstract because it always
         returns the local host's facts, regardless of what you attempt to find."
 
     def destroy(facts)
diff --git a/lib/puppet/indirector/facts/yaml.rb b/lib/puppet/indirector/facts/yaml.rb
index 99d17d7b0..b8a8e3163 100644
--- a/lib/puppet/indirector/facts/yaml.rb
+++ b/lib/puppet/indirector/facts/yaml.rb
@@ -2,5 +2,6 @@ require 'puppet/node/facts'
 require 'puppet/indirector/yaml'
 
 class Puppet::Node::Facts::Yaml < Puppet::Indirector::Yaml
-    desc "Store client facts as flat files, serialized using YAML."
+    desc "Store client facts as flat files, serialized using YAML, or
+        return deserialized facts from disk."
 end
diff --git a/lib/puppet/indirector/indirection.rb b/lib/puppet/indirector/indirection.rb
index f6f867a5f..129676e9c 100644
--- a/lib/puppet/indirector/indirection.rb
+++ b/lib/puppet/indirector/indirection.rb
@@ -1,5 +1,11 @@
-# An actual indirection.
+require 'puppet/util/docs'
+
+# The class that connects functional classes with their different collection
+# back-ends.  Each indirection has a set of associated terminus classes,
+# each of which is a subclass of Puppet::Indirector::Terminus.
 class Puppet::Indirector::Indirection
+    include Puppet::Util::Docs
+
     @@indirections = []
 
     # Clear all cached termini from all indirections.
@@ -12,6 +18,12 @@ class Puppet::Indirector::Indirection
     def self.instance(name)
         @@indirections.find { |i| i.name == name }
     end
+
+    # Return a list of all known indirections.  Used to generate the
+    # reference.
+    def self.instances
+        @@indirections.collect { |i| i.name }
+    end
     
     # Find an indirected model by name.  This is provided so that Terminus classes
     # can specifically hook up with the indirections they are associated with.
@@ -53,6 +65,21 @@ class Puppet::Indirector::Indirection
         @@indirections.delete(self) if @@indirections.include?(self)
     end
 
+    # Generate the full doc string.
+    def doc
+        text = ""
+
+        if defined? @doc and @doc
+            text += scrub(@doc) + "\n\n"
+        end
+
+        if s = terminus_setting()
+            text += "* **Terminus Setting**: %s" % terminus_setting
+        end
+
+        text
+    end
+
     def initialize(model, name, options = {})
         @model = model
         @name = name
diff --git a/lib/puppet/indirector/node/exec.rb b/lib/puppet/indirector/node/exec.rb
index c6dde484c..ed76bce94 100644
--- a/lib/puppet/indirector/node/exec.rb
+++ b/lib/puppet/indirector/node/exec.rb
@@ -2,7 +2,8 @@ require 'puppet/node'
 require 'puppet/indirector/exec'
 
 class Puppet::Node::Exec < Puppet::Indirector::Exec
-    desc "Call an external program to get node information."
+    desc "Call an external program to get node information.  See
+    the `ExternalNodes`:trac: page for more information."
     include Puppet::Util
 
     def command
diff --git a/lib/puppet/indirector/node/ldap.rb b/lib/puppet/indirector/node/ldap.rb
index a1c3c3a71..dd11f4e9b 100644
--- a/lib/puppet/indirector/node/ldap.rb
+++ b/lib/puppet/indirector/node/ldap.rb
@@ -2,7 +2,8 @@ require 'puppet/node'
 require 'puppet/indirector/ldap'
 
 class Puppet::Node::Ldap < Puppet::Indirector::Ldap
-    desc "Search in LDAP for node configuration information."
+    desc "Search in LDAP for node configuration information.  See
+    the `LdapNodes`:trac: page for more information."
 
     # The attributes that Puppet class information is stored in.
     def class_attributes
diff --git a/lib/puppet/indirector/node/memory.rb b/lib/puppet/indirector/node/memory.rb
index 0710f82ac..de0ed8ab2 100644
--- a/lib/puppet/indirector/node/memory.rb
+++ b/lib/puppet/indirector/node/memory.rb
@@ -5,5 +5,6 @@ class Puppet::Node::Memory < Puppet::Indirector::Memory
     desc "Keep track of nodes in memory but nowhere else.  This is used for
         one-time compiles, such as what the stand-alone ``puppet`` does.
         To use this terminus, you must load it with the data you want it
-        to contain."
+        to contain; it is only useful for developers and should generally not
+        be chosen by a normal user."
 end
diff --git a/lib/puppet/indirector/node/null.rb b/lib/puppet/indirector/node/null.rb
index 4c5c1261b..f7c4d25ea 100644
--- a/lib/puppet/indirector/node/null.rb
+++ b/lib/puppet/indirector/node/null.rb
@@ -4,7 +4,10 @@ require 'puppet/indirector/null'
 class Puppet::Node::Null < Puppet::Indirector::Null
     desc "Always return an empty node object.  This is the node source you should
         use when you don't have some other, functional source you want to use,
-        as the compiler will not work without this node information."
+        as the compiler will not work without a valid node terminus.
+        
+        Note that class is responsible for merging the node's facts into the node
+        instance before it is returned."
 
     # Just return an empty node.
     def find(name)
diff --git a/lib/puppet/indirector/node/rest.rb b/lib/puppet/indirector/node/rest.rb
index ed78e5937..c5d2f97fb 100644
--- a/lib/puppet/indirector/node/rest.rb
+++ b/lib/puppet/indirector/node/rest.rb
@@ -2,6 +2,6 @@ require 'puppet/node'
 require 'puppet/indirector/rest'
 
 class Puppet::Node::REST < Puppet::Indirector::REST
-    desc "TODO: FIXME"
+    desc "This will eventually be a REST-based mechanism for finding nodes.  It is currently non-functional."
     # TODO/FIXME
 end
diff --git a/lib/puppet/indirector/node/yaml.rb b/lib/puppet/indirector/node/yaml.rb
index bb96b280a..f2873479d 100644
--- a/lib/puppet/indirector/node/yaml.rb
+++ b/lib/puppet/indirector/node/yaml.rb
@@ -2,5 +2,6 @@ require 'puppet/node'
 require 'puppet/indirector/yaml'
 
 class Puppet::Node::Yaml < Puppet::Indirector::Yaml
-    desc "Store node information as flat files, serialized using YAML."
+    desc "Store node information as flat files, serialized using YAML,
+        or deserialize stored YAML nodes."
 end
diff --git a/lib/puppet/indirector/terminus.rb b/lib/puppet/indirector/terminus.rb
index 882afde41..a0623b284 100644
--- a/lib/puppet/indirector/terminus.rb
+++ b/lib/puppet/indirector/terminus.rb
@@ -107,6 +107,17 @@ class Puppet::Indirector::Terminus
             loaded_instance(indirection_name, terminus_type)
         end
 
+        # Return all terminus classes for a given indirection.
+        def terminus_classes(indirection_name)
+            setup_instance_loading indirection_name
+            
+            # Load them all.
+            instance_loader(indirection_name).loadall
+
+            # And return the list of names.
+            loaded_instances(indirection_name)
+        end
+
         private
 
         def setup_instance_loading(type)