Lots of work related to generating more reference. Moving all of the individual references out of puppetdoc and into an external "reference" class, which itself can autoload, so it is now easy to add new types of references. Also adding a network reference, along with an unfinished provider reference.

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

10 files changed, 54 insertions, 0 deletions

diff --git a/lib/puppet/network/handler.rb b/lib/puppet/network/handler.rb
index 080997e98..33343e4fe 100644
--- a/lib/puppet/network/handler.rb
+++ b/lib/puppet/network/handler.rb
@@ -1,9 +1,12 @@
+require 'puppet/util/docs'
 require 'puppet/util/subclass_loader'
 
 module Puppet::Network
     # The base class for the different handlers.  The handlers are each responsible
     # for separate xmlrpc namespaces.
     class Handler
+        extend Puppet::Util::Docs
+
         # This is so that the handlers can subclass just 'Handler', rather
         # then having to specify the full class path.
         Handler = self
@@ -24,6 +27,20 @@ module Puppet::Network
             end
         end
 
+        # Set/Determine whether we're a client- or server-side handler.
+        def self.side(side = nil)
+            if side
+                side = side.intern if side.is_a?(String)
+                unless [:client, :server].include?(side)
+                    raise ArgumentError, "Invalid side registration '%s' for %s" % [side, self.name]
+                end
+                @side = side
+            else
+                @side ||= :server
+                return @side
+            end
+        end
+
         # Create an empty init method with the same signature.
         def initialize(hash = {})
         end
diff --git a/lib/puppet/network/handler/ca.rb b/lib/puppet/network/handler/ca.rb
index a52c1556e..875cfc926 100644
--- a/lib/puppet/network/handler/ca.rb
+++ b/lib/puppet/network/handler/ca.rb
@@ -10,6 +10,10 @@ class Puppet::Network::Handler
     class CA < Handler
         attr_reader :ca
 
+        desc "Provides an interface for signing CSRs.  Accepts a CSR and returns
+        the CA certificate and the signed certificate, or returns nil if
+        the cert is not signed."
+
         @interface = XMLRPC::Service::Interface.new("puppetca") { |iface|
             iface.add_method("array getcert(csr)")
         }
diff --git a/lib/puppet/network/handler/facts.rb b/lib/puppet/network/handler/facts.rb
index 46c94b91a..e0b93f942 100755
--- a/lib/puppet/network/handler/facts.rb
+++ b/lib/puppet/network/handler/facts.rb
@@ -4,6 +4,9 @@ require 'puppet/util/fact_store'
 class Puppet::Network::Handler
     # Receive logs from remote hosts.
     class Facts < Handler
+        desc "An interface for storing and retrieving client facts.  Currently only
+        used internally by Puppet."
+
         @interface = XMLRPC::Service::Interface.new("facts") { |iface|
             iface.add_method("void set(string, string)")
             iface.add_method("string get(string)")
diff --git a/lib/puppet/network/handler/filebucket.rb b/lib/puppet/network/handler/filebucket.rb
index 705a4eee9..bb6a0e6d3 100755
--- a/lib/puppet/network/handler/filebucket.rb
+++ b/lib/puppet/network/handler/filebucket.rb
@@ -8,6 +8,9 @@ class Puppet::Network::Handler # :nodoc:
     # to the client.  Alternatively, accept an md5 sum and return the
     # associated content.
     class FileBucket < Handler
+        desc "The interface to Puppet's FileBucket system.  Can be used to store
+        files in and retrieve files from a filebucket."
+
         @interface = XMLRPC::Service::Interface.new("puppetbucket") { |iface|
             iface.add_method("string addfile(string, string)")
             iface.add_method("string getfile(string)")
diff --git a/lib/puppet/network/handler/fileserver.rb b/lib/puppet/network/handler/fileserver.rb
index 0170eae7b..4331d27fd 100755
--- a/lib/puppet/network/handler/fileserver.rb
+++ b/lib/puppet/network/handler/fileserver.rb
@@ -7,6 +7,8 @@ require 'delegate'
 class Puppet::Network::Handler
     class FileServerError < Puppet::Error; end
     class FileServer < Handler
+        desc "The interface to Puppet's fileserving abilities."
+
         attr_accessor :local
 
         CHECKPARAMS = [:mode, :type, :owner, :group, :checksum]
diff --git a/lib/puppet/network/handler/master.rb b/lib/puppet/network/handler/master.rb
index 1082d3aaa..963b7841a 100644
--- a/lib/puppet/network/handler/master.rb
+++ b/lib/puppet/network/handler/master.rb
@@ -8,6 +8,9 @@ require 'yaml'
 class Puppet::Network::Handler
     class MasterError < Puppet::Error; end
     class Master < Handler
+        desc "Puppet's configuration interface.  Used for all interactions related to
+        generating client configurations."
+
         include Puppet::Util
 
         attr_accessor :ast, :local
diff --git a/lib/puppet/network/handler/report.rb b/lib/puppet/network/handler/report.rb
index e21acb810..ce5176a36 100755
--- a/lib/puppet/network/handler/report.rb
+++ b/lib/puppet/network/handler/report.rb
@@ -3,6 +3,8 @@ require 'puppet/util/instance_loader'
 # A simple server for triggering a new run on a Puppet client.
 class Puppet::Network::Handler
     class Report < Handler
+        desc "Accepts a Puppet transaction report and processes it."
+
         extend Puppet::Util::ClassGen
         extend Puppet::Util::InstanceLoader
 
diff --git a/lib/puppet/network/handler/resource.rb b/lib/puppet/network/handler/resource.rb
index 2937aa7be..349f73537 100755
--- a/lib/puppet/network/handler/resource.rb
+++ b/lib/puppet/network/handler/resource.rb
@@ -4,6 +4,16 @@ require 'puppet/network/handler'
 # Serve Puppet elements.  Useful for querying, copying, and, um, other stuff.
 class Puppet::Network::Handler
     class Resource < Handler
+        desc "An interface for interacting with client-based resources that can
+        be used for querying or managing remote machines without using Puppet's
+        central server tools.
+        
+        The ``describe`` and ``list`` methods return TransBuckets containing
+        TransObject instances (``describe`` returns a single TransBucket),
+        and the ``apply`` method accepts a TransBucket of TransObjects and
+        applies them locally.
+        "
+
         attr_accessor :local
 
         @interface = XMLRPC::Service::Interface.new("resource") { |iface|
@@ -12,6 +22,8 @@ class Puppet::Network::Handler
             iface.add_method("string list(string, array, string)")
         }
 
+        side :client
+
         # Apply a TransBucket as a transaction.
         def apply(bucket, format = "yaml", client = nil, clientip = nil)
             unless @local
diff --git a/lib/puppet/network/handler/runner.rb b/lib/puppet/network/handler/runner.rb
index 79084f847..c41e83608 100755
--- a/lib/puppet/network/handler/runner.rb
+++ b/lib/puppet/network/handler/runner.rb
@@ -2,10 +2,14 @@ class Puppet::Network::Handler
     class MissingMasterError < RuntimeError; end # Cannot find the master client
     # A simple server for triggering a new run on a Puppet client.
     class Runner < Handler
+        desc "An interface for triggering client configuration runs."
+
         @interface = XMLRPC::Service::Interface.new("puppetrunner") { |iface|
             iface.add_method("string run(string, string)")
         }
 
+        side :client
+
         # Run the client configuration right now, optionally specifying
         # tags and whether to ignore schedules
         def run(tags = nil, ignoreschedules = false, fg = true, client = nil, clientip = nil)
diff --git a/lib/puppet/network/handler/status.rb b/lib/puppet/network/handler/status.rb
index 774c49f6d..48668ca47 100644
--- a/lib/puppet/network/handler/status.rb
+++ b/lib/puppet/network/handler/status.rb
@@ -1,5 +1,9 @@
 class Puppet::Network::Handler
     class Status < Handler
+        desc "A simple interface for testing Puppet connectivity."
+
+        side :client
+
         @interface = XMLRPC::Service::Interface.new("status") { |iface|
             iface.add_method("int status()")
         }