(#6962) Add self-documentation data to puppet faces

This patch adds documentation strings to most of the faces, actions, and options
introduced in 2.7.0. There are a small number of TK notes remaining, and longer strings
have not been indented to take advantage of the patch from issue #7221.

1 files changed, 16 insertions, 0 deletions

diff --git a/lib/puppet/face/plugin.rb b/lib/puppet/face/plugin.rb
index 8a2559405..f55bd3b28 100644
--- a/lib/puppet/face/plugin.rb
+++ b/lib/puppet/face/plugin.rb
@@ -4,6 +4,16 @@ Puppet::Face.define(:plugin, '0.0.1') do
   license   "Apache 2 license; see COPYING"
 
   summary "Interact with the Puppet plugin system"
+  description <<-EOT
+This face provides network access to the puppet master's store of
+plugins. It is intended for use in other faces, rather than for direct
+command line access.
+  EOT
+  notes <<-EOT
+The puppet master can serve Ruby code collected from the lib directories
+of its modules. These plugins can be used on agent nodes to extend
+Facter and implement custom types and providers.
+  EOT
 
   action :download do
     summary "Download plugins from the configured master"
@@ -11,6 +21,12 @@ Puppet::Face.define(:plugin, '0.0.1') do
             An array containing the files actually downloaded.
             This will be empty array when everything was in sync.
             EOT
+    notes "This action modifies files on disk without returning any data."
+    examples <<-EOT
+Retrieve plugins from the puppet master:
+
+    Puppet::Face[:plugin, '0.0.1'].download
+    EOT
 
     when_invoked do |options|
       require 'puppet/configurer/downloader'