Adding an Indirection reference, along with the work

necessary to support it.

15 files changed, 101 insertions, 16 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)
diff --git a/lib/puppet/node.rb b/lib/puppet/node.rb
index 4b3a8e9c9..c0628ecdc 100644
--- a/lib/puppet/node.rb
+++ b/lib/puppet/node.rb
@@ -1,6 +1,6 @@
 require 'puppet/indirector'
 
-# A simplistic class for managing the node information itself.
+# A class for managing nodes, including their facts and environment.
 class Puppet::Node
     require 'puppet/node/facts'
     require 'puppet/node/environment'
@@ -10,7 +10,8 @@ class Puppet::Node
     extend Puppet::Indirector
 
     # Use the node source as the indirection terminus.
-    indirects :node, :terminus_setting => :node_terminus
+    indirects :node, :terminus_setting => :node_terminus, :doc => "Where to find node information.
+        A node is composed of its name, its facts, and its environment."
 
     # Retrieve a node from the node source, with some additional munging
     # thrown in for kicks.
@@ -44,7 +45,7 @@ class Puppet::Node
 
     private
 
-    # Look up the node facts from our fact handler.
+    # Look up the node facts so we can generate the node names to use.
     def self.node_facts(key)
         if facts = Puppet::Node::Facts.find(key)
             facts.values
diff --git a/lib/puppet/reference/indirection.rb b/lib/puppet/reference/indirection.rb
new file mode 100644
index 000000000..074398120
--- /dev/null
+++ b/lib/puppet/reference/indirection.rb
@@ -0,0 +1,34 @@
+require 'puppet/indirector/indirection'
+require 'puppet/checksum'
+require 'puppet/file_serving/content'
+require 'puppet/file_serving/metadata'
+
+reference = Puppet::Util::Reference.newreference :indirection, :doc => "Indirection types and their terminus classes" do
+    text = ""
+    Puppet::Indirector::Indirection.instances.sort { |a,b| a.to_s <=> b.to_s }.each do |indirection|
+        ind = Puppet::Indirector::Indirection.instance(indirection)
+        name = indirection.to_s.capitalize
+        text += indirection.to_s + "\n" + ("-" * name.length) + "\n\n"
+
+        text += ind.doc + "\n\n"
+
+        Puppet::Indirector::Terminus.terminus_classes(ind.name).sort { |a,b| a.to_s <=> b.to_s }.each do |terminus|
+            text += terminus.to_s + "\n" + ("+" * terminus.to_s.length) + "\n\n"
+
+            term_class = Puppet::Indirector::Terminus.terminus_class(ind.name, terminus)
+
+            text += Puppet::Util::Docs.scrub(term_class.doc) + "\n\n"
+        end
+    end
+
+    text
+end
+
+reference.header = "This is the list of all indirections, their associated terminus classes, and how you select between them.
+
+In general, the appropriate terminus class is selected by the application for you (e.g., ``puppetd`` would always use the ``rest``
+terminus for most of its indirected classes), but some classes are tunable via normal settings.  These will have ``terminus setting``
+documentation listed with them.
+
+
+"
diff --git a/lib/puppet/util/docs.rb b/lib/puppet/util/docs.rb
index 01178e5f4..54d1052f3 100644
--- a/lib/puppet/util/docs.rb
+++ b/lib/puppet/util/docs.rb
@@ -14,9 +14,11 @@ module Puppet::Util::Docs
         meta_def method, &block
     end
 
+    attr_writer :doc
+
     # Generate the full doc string.
     def doc
-        extra = methods.find_all { |m| m.to_s =~ /^dochook_.+/ }.collect { |m|
+        extra = methods.find_all { |m| m.to_s =~ /^dochook_.+/ }.sort.collect { |m|
             self.send(m)
         }.join("  ")
 
diff --git a/lib/puppet/util/instance_loader.rb b/lib/puppet/util/instance_loader.rb
index f280014eb..bf4f9b77f 100755
--- a/lib/puppet/util/instance_loader.rb
+++ b/lib/puppet/util/instance_loader.rb
@@ -36,6 +36,9 @@ module Puppet::Util::InstanceLoader
     def instance_docs(type)
         docs = ""
 
+        # Load all instances.
+        instance_loader(type).loadall
+
         # Use this method so they all get loaded
         loaded_instances(type).sort { |a,b| a.to_s <=> b.to_s }.each do |name|
             mod = self.loaded_instance(name)