Please review pull request #576: Minor docs edits opened by (nfagerlund)
Description:
Minor edits to the inline face documentation strings.
- Opened: Tue Mar 13 01:12:03 UTC 2012
- Based on: puppetlabs:geordi (2d5569ab4730833421b1061339302f0ff4c98467)
- Requested merge: nfagerlund:geordi (88ca28cd84ed55067b8172d314f7e76917b1cd91)
Diff follows:
diff --git a/lib/puppet/face/help/man.erb b/lib/puppet/face/help/man.erb
index 90e2796..5a3aa2c 100644
--- a/lib/puppet/face/help/man.erb
+++ b/lib/puppet/face/help/man.erb
@@ -71,7 +71,7 @@ ACTIONS
<% unique_options.sort.each do |name|
option = action.get_option name
- text = option.description || option.summary -%>
+ text = (option.description || option.summary).chomp + "\n" -%>
<%= '<' + option.optparse.join("> | <") + '>' %> -
<%= text.gsub(/^/, ' ') %>
<% end -%>
diff --git a/lib/puppet/face/module.rb b/lib/puppet/face/module.rb
index bab553c..deea906 100644
--- a/lib/puppet/face/module.rb
+++ b/lib/puppet/face/module.rb
@@ -7,6 +7,8 @@
summary "Creates, installs and searches for modules on the Puppet Forge."
description <<-EOT
- Creates, installs and searches for modules on the Puppet Forge.
+ This subcommand can find, install, and manage modules from the Puppet Forge,
+ a repository of user-contributed Puppet code. It can also generate empty
+ modules, and prepare locally developed modules for release on the Forge.
EOT
end
diff --git a/lib/puppet/face/module/build.rb b/lib/puppet/face/module/build.rb
index 2273634..f1a0ef4 100644
--- a/lib/puppet/face/module/build.rb
+++ b/lib/puppet/face/module/build.rb
@@ -2,9 +2,17 @@
action(:build) do
summary "Build a module release package."
description <<-EOT
- Build a module release archive file by processing the Modulefile in the
- module directory. The release archive file will be stored in the pkg
- directory of the module directory.
+ Prepares a local module for release on the Puppet Forge by building a
+ ready-to-upload archive file. Before using this action, make sure that
+ the module directory's name is in the standard <username>-<module>
+ format.
+
+ This action uses the Modulefile in the module directory to set metadata
+ used by the Forge. See <http://links.puppetlabs.com/modulefile> for more
+ about writing modulefiles.
+
+ After being built, the release archive file can be found in the module's
+ `pkg` directory.
EOT
returns "Pathname object representing the path to the release archive."
diff --git a/lib/puppet/face/module/changes.rb b/lib/puppet/face/module/changes.rb
index 0266611..602e423 100644
--- a/lib/puppet/face/module/changes.rb
+++ b/lib/puppet/face/module/changes.rb
@@ -2,9 +2,9 @@
action(:changes) do
summary "Show modified files of an installed module."
description <<-EOT
- Show files that have been modified after installation of a given module
- by comparing the on-disk md5 checksum of each file against the module's
- metadata.
+ Shows any files in a module that have been modified since it was
+ installed. This action compares the files on disk to the md5 checksums
+ included in the module's metadata.
EOT
returns "Array of strings representing paths of modified files."
diff --git a/lib/puppet/face/module/clean.rb b/lib/puppet/face/module/clean.rb
index 6372630..fb6e8b5 100644
--- a/lib/puppet/face/module/clean.rb
+++ b/lib/puppet/face/module/clean.rb
@@ -2,11 +2,11 @@
action(:clean) do
summary "Clean the module download cache."
description <<-EOT
- Clean the module download cache.
+ Cleans the module download cache.
EOT
returns <<-EOT
- Return a status Hash:
+ A status Hash:
{ :status => "success", :msg => "Cleaned module cache." }
EOT
diff --git a/lib/puppet/face/module/generate.rb b/lib/puppet/face/module/generate.rb
index b9dc354..8f1622c 100644
--- a/lib/puppet/face/module/generate.rb
+++ b/lib/puppet/face/module/generate.rb
@@ -2,9 +2,11 @@
action(:generate) do
summary "Generate boilerplate for a new module."
description <<-EOT
- Generate boilerplate for a new module by creating a directory
- pre-populated with a directory structure and files recommended for
- Puppet best practices.
+ Generates boilerplate for a new module by creating the directory
+ structure and files recommended for the Puppet community's best practices.
+
+ A module may need additional directories beyond this boilerplate
+ if it provides plugins, files, or templates.
EOT
returns "Array of Pathname objects representing paths of generated files."
diff --git a/lib/puppet/face/module/install.rb b/lib/puppet/face/module/install.rb
index 81cd8ed..5beb26c 100644
--- a/lib/puppet/face/module/install.rb
+++ b/lib/puppet/face/module/install.rb
@@ -2,10 +2,12 @@
action(:install) do
summary "Install a module from a repository or release archive."
description <<-EOT
- Install a module from a release archive file on-disk or by downloading
- one from a repository. Unpack the archive into the install directory
- specified by the --dir option, which defaults to
- #{Puppet.settings[:modulepath].split(File::PATH_SEPARATOR).first}
+ Installs a module from the Puppet Forge, from a release archive file
+ on-disk, or from a private Forge-like repository.
+
+ The specified module will be installed into the directory
+ specified with the --dir option, which defaults to
+ #{Puppet.settings[:modulepath].split(File::PATH_SEPARATOR).first}.
EOT
returns "Pathname object representing the path to the installed module."
@@ -59,7 +61,7 @@
default_to { Puppet.settings[:module_repository] }
summary "Module repository to use."
description <<-EOT
- Module repository to use.
+ The module repository to use, as a URL. Defaults to http://forge.puppetlabs.com.
EOT
end
@@ -73,7 +75,7 @@
option "--modulepath MODULEPATH" do
summary "Which directories to look for modules in"
description <<-EOT
- The directory into which modules are installed, defaults to the first
+ The directory into which modules are installed; defaults to the first
directory in the modulepath. If the dir option is also given, it is
prepended to the modulepath.
EOT
@@ -82,8 +84,8 @@
option "--version VER", "-v VER" do
summary "Module version to install."
description <<-EOT
- Module version to install, can be a requirement string, eg '>= 1.0.3',
- defaults to latest version.
+ Module version to install; can be an exact version or a requirement string,
+ eg '>= 1.0.3'. Defaults to latest version.
EOT
end
diff --git a/lib/puppet/face/module/list.rb b/lib/puppet/face/module/list.rb
index 36ae397..e21fb05 100644
--- a/lib/puppet/face/module/list.rb
+++ b/lib/puppet/face/module/list.rb
@@ -2,11 +2,12 @@
action(:list) do
summary "List installed modules"
description <<-HEREDOC
- List puppet modules from a specific environment, specified modulepath or
- default to listing modules in the default modulepath. The output will
- include information about unmet module dependencies based on information
- from module metadata.
- #{Puppet.settings[:modulepath]}
+ Lists the installed puppet modules. By default, this action scans the
+ modulepath from puppet.conf's `[main]` block; use the --modulepath
+ option to change which directories are scanned.
+
+ The output of this action includes information from the module's
+ metadata, including version numbers and unmet module dependencies.
HEREDOC
returns "hash of paths to module objects"
@@ -16,6 +17,10 @@
option "--modulepath MODULEPATH" do
summary "Which directories to look for modules in"
+ description <<-EOT
+ Which directories to look for modules in; use the system path separator
+ character (`:` on Unix-like systems) to specify multiple directories.
+ EOT
end
option "--tree" do
diff --git a/lib/puppet/face/module/search.rb b/lib/puppet/face/module/search.rb
index c6140ba..6594982 100644
--- a/lib/puppet/face/module/search.rb
+++ b/lib/puppet/face/module/search.rb
@@ -4,7 +4,8 @@
action(:search) do
summary "Search a repository for a module."
description <<-EOT
- Search a repository for modules whose names match a specific substring.
+ Searches a repository for modules whose names, descriptions, or keywords
+ match the provided search term.
EOT
returns "Array of module metadata hashes"
@@ -17,13 +18,13 @@
bacula This is a generic Apache module @puppetlabs backups
EOT
- arguments "<term>"
+ arguments "<search_term>"
option "--module-repository=", "-r=" do
default_to { Puppet.settings[:module_repository] }
- summary "Module repository to use."
+ summary "The module repository to use."
description <<-EOT
- Module repository to use.
+ The module repository to use. Defaults to http://forge.puppetlabs.com.
EOT
end
diff --git a/lib/puppet/face/module/uninstall.rb b/lib/puppet/face/module/uninstall.rb
index ce22524..dd8f8f1 100644
--- a/lib/puppet/face/module/uninstall.rb
+++ b/lib/puppet/face/module/uninstall.rb
@@ -2,9 +2,8 @@
action(:uninstall) do
summary "Uninstall a puppet module."
description <<-EOT
- Uninstall a puppet module from the modulepath or a specific
- target directory which defaults to
- #{Puppet.settings[:modulepath].split(File::PATH_SEPARATOR).join(', ')}.
+ Uninstalls a puppet module from the modulepath (or a specific
+ target directory).
EOT
returns "Hash of module objects representing uninstalled modules and related errors."
diff --git a/lib/puppet/face/module/upgrade.rb b/lib/puppet/face/module/upgrade.rb
index 3066c1f..ba78ea3 100644
--- a/lib/puppet/face/module/upgrade.rb
+++ b/lib/puppet/face/module/upgrade.rb
@@ -1,12 +1,12 @@
Puppet::Face.define(:module, '1.0.0') do
action(:upgrade) do
- summary "upgrade a puppet module."
+ summary "Upgrade a puppet module."
description <<-EOT
- upgrade a puppet module
+ Upgrades a puppet module.
EOT
-
+
returns "Hash"
-
+
examples <<-EOT
upgrade an installed module to the latest version
@@ -38,7 +38,7 @@
end
option "--ignore-dependencies" do
- summary "Do not attempt to install dependencies"
+ summary "Do not attempt to install dependencies."
description <<-EOT
Do not attempt to install dependencies
EOT
@@ -53,9 +53,9 @@
end
option "--version=" do
- summary "The version of the module to upgrade"
+ summary "The version of the module to upgrade to."
description <<-EOT
- The version of the module to upgrade.
+ The version of the module to upgrade to.
EOT
end
@@ -66,7 +66,7 @@
Puppet.notice "Preparing to upgrade '#{name}' ..."
Puppet::Module::Tool::Applications::Upgrader.new(name, options).run
end
-
+
when_rendering :console do |return_value|
if return_value[:result] == :failure
Puppet.err(return_value[:error][:multiline])
-- You received this message because you are subscribed to the Google Groups "Puppet Developers" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to [email protected].
For more options, visit this group at http://groups.google.com/group/puppet-dev?hl=en.
