RDoc-ify documentation

See http://club.black.co.at/david/puppet/doc/ for a current version of the RDoc
output.

README

@@ -1,17 +1,22 @@
 
-The common module installs various functions that are required by other modules. This
+The common module installs various functions that are required by other
-module should be installed before any of the other module.
+modules. This module should be installed before any of the other module.
 
 To use this module, follow these directions:
 
-1. Your modules directory will need all the files included in this repository placed
+1. Your modules directory will need all the files included in this
-   under a directory called "common"
+   repository placed under a directory called "common"
 
 2. Add the following line to manifests/site.pp:
    
-   import "modules.pp"
+       import "modules.pp"
 
 3. Add the following line to manifests/modules.pp:
 
-   import "common"
+       import "common"
+
+
+Author::    David Schmitt (mailto:david@dasz.at)
+Copyright:: Copyright (c) 2007-2009 dasz.at OG
+License::   3-clause BSD
 

manifests/classes/lsb_release.pp

@@ -43,7 +43,7 @@ class assert_lsbdistcodename {
 
 }
 
-# To fail the complete compilation, include this class
+# To fail the complete compilation on a missing $lsbdistcodename, include this class
 class require_lsbdistcodename inherits assert_lsbdistcodename {
 	exec { "false # require_lsbdistcodename": require => Exec[require_lsbdistcodename], loglevel => err }
 }

manifests/defines/concatenated_file.pp

@@ -26,9 +26,9 @@ module_dir { "common/cf": }
 # Exec["concat_${name}"] if you want to force an update.
 # 
 # Usage:
-# concatenated_file { "/etc/some.conf":
+#  concatenated_file { "/etc/some.conf":
-# 	dir => "/etc/some.conf.d",
+#  	dir => "/etc/some.conf.d",
-# }
+#  }
 define concatenated_file (
 	# where the snippets are located
 	$dir = '',

manifests/defines/config_file.pp

@@ -5,30 +5,31 @@
 # A simple wrapper to give all configuration files common defaults.
 # 
 # Usage:
-# config_file { filename:
+#  config_file { filename:
-# 	content => "....\n",
+#  	content => "....\n",
-# }
+#  }
 #
 # Examples: 
 #
 # To create the file /etc/vservers/${vs_name}/context with specific
 # content:
 #
-# config_file { "/etc/vservers/${vs_name}/context":
+#  config_file {
-#              content => "${context}\n",
+#  	"/etc/vservers/${vs_name}/context":
-#              notify => Exec["vs_restart_${vs_name}"],
+#  		content => "${context}\n",
-#              require => Exec["vs_create_${vs_name}"];
+#  		notify => Exec["vs_restart_${vs_name}"],
+#  		require => Exec["vs_create_${vs_name}"];
 # }
 #
 # To create the file /etc/apache2/sites-available/munin-stats with the
 # content pulled from a template:
 #
-# config_file { "/etc/apache2/sites-available/munin-stats":
+#  config_file {
-#              content => template("apache/munin-stats"),
+# 		"/etc/apache2/sites-available/munin-stats":
-#              require => Package["apache2"],
+#  		content => template("apache/munin-stats"),
-#              notify => Exec["reload-apache2"]
+#  		require => Package["apache2"],
-# }
+#  		notify => Exec["reload-apache2"];
-
+#  }
 define config_file (
 	$content = '',
 	$source = '',

manifests/defines/line.pp

@@ -2,36 +2,38 @@
 # Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
 # See LICENSE for the full license granted to you.
 
-# Ensures that a specific line is present or absent in a file. This can be very
+# Ensures that a specific line is present or absent in a file. This can
-# brittle, since even small changes can throw this off.
+# be very brittle, since even small changes can throw this off.
 #
 # If the line is not present yet, it will be appended to the file.
 # 
 # The name of the define is not used. Just keep it (globally) unique and
 # descriptive.
 #
-# Use this only for very trivial stuff.
+# Use this only for very trivial stuff. Usually replacing the whole file
+# is a more stable solution with less maintenance headaches afterwards.
 #
 # Usage:
-# line { description:
+#  line {
-# 	file => "filename",
+#  	description:
-# 	line => "content",
+# 			file => "filename",
-# 	ensure => {absent,*present*}
+#  		line => "content",
-# }
+# 			ensure => {absent,*present*}
+#  }
 #
 # Example:
-# The following ensures that the line "allow ^$munin_host$" exists
+# The following ensures that the line "allow ^$munin_host$" exists in
-# in /etc/munin/munin-node.conf, and if there are any changes notify the service for
+# /etc/munin/munin-node.conf, and if there are any changes notify the
-# a restart
+# service for a restart
-#
-# line { allow_munin_host:
-#       file => "/etc/munin/munin-node.conf",
-#       line => "allow ^$munin_host$",
-#       ensure => present,
-#       notify => Service[munin-node],
-#       require => Package[munin-node],
-# }
 #
+#  line {
+#  	allow_munin_host:
+#  		file => "/etc/munin/munin-node.conf",
+#  		line => "allow ^$munin_host$",
+#  		ensure => present,
+#  		notify => Service[munin-node],
+#  		require => Package[munin-node];
+#  }
 define line(
 	$file,
 	$line,

manifests/defines/module_dir.pp

@@ -4,21 +4,17 @@
 # Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
 # See LICENSE for the full license granted to you.
 
-# Use this variable to reference the base path. Thus you are safe from any
-# changes.
-$module_dir_path = '/var/lib/puppet/modules'
-
 # A module_dir is a storage place for all the stuff a module might want to
 # store. According to the FHS, this should go to /var/lib. Since this is a part
 # of puppet, the full path is /var/lib/puppet/modules/${name}. Every module
 # should # prefix its module_dirs with its name.
 # 
 # By default, the module_dir is loaded from "puppet:///${name}/module_dir". If
-# that doesn't exist an empty directory is taken as template. The directory is
+# that doesn't exist an empty directory is taken as source. The directory is
 # purged so that modules do not have to worry about removing cruft.
 # 
 # Usage:
-# module_dir { ["common", "common/dir1", "common/dir2" ]: }
+#  module_dir { ["common", "common/dir1", "common/dir2" ]: }
 define module_dir (
 		$mode = 0644,
 		$owner = root,
@@ -41,3 +37,6 @@ define module_dir (
 	}
 }
 
+# Use this variable to reference the base path. Thus you are safe from any
+# changes.
+$module_dir_path = '/var/lib/puppet/modules'

manifests/defines/module_file.pp

@@ -4,12 +4,12 @@
 # Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
 # See LICENSE for the full license granted to you.
 
+# Put a file into module-local storage.
+#
 # Usage:
-# module_file { "module/file":
+#  module_file {
-# 		source => "puppet://..",
+#  	"module/file":
-# 		mode   => 644,   # default
+# 			source => "puppet://..",
-# 		owner  => root,  # default
-#		group  => root,  # default
 # }
 define module_file (
 		$source,

manifests/defines/replace.pp

@@ -8,6 +8,9 @@
 # creating a template is often better than this hack.
 #
 # This define uses perl regular expressions.
+#
+# Use this only for very trivial stuff. Usually replacing the whole file is a
+# more stable solution with less maintenance headaches afterwards. 
 # 
 # Usage:
 #
@@ -20,12 +23,12 @@
 # To replace the current port in /etc/munin/munin-node.conf
 # with a new port, but only disturbing the file when needed:
 #
-# replace { set_munin_node_port:
+#  replace {
-# 	file => "/etc/munin/munin-node.conf",
+#  	set_munin_node_port:
-# 	pattern => "^port (?!$port)[0-9]*",
+#  		file => "/etc/munin/munin-node.conf",
-# 	replacement => "port $port"
+#  		pattern => "^port (?!$port)[0-9]*",
-# }  
+#  		replacement => "port $port"
-
+#  }  
 define replace($file, $pattern, $replacement) {
 	$pattern_no_slashes = regsubst($pattern, '/', '\\/', 'G', 'U')
 	$replacement_no_slashes = regsubst($replacement, '/', '\\/', 'G', 'U')

plugins/puppet/parser/functions/basename.rb

@@ -1,9 +1,15 @@
-# basename(string) : string
+# This function has two modes of operation:
-# basename(string[]) : string[]
+#
+#  basename(string) : string
 #
 # Returns the last component of the filename given as argument, which must be
-# formed using forward slashes (``/..) regardless of the separator used on the
+# formed using forward slashes ("/") regardless of the separator used on the
 # local file system.
+#
+#  basename(string[]) : string[]
+#
+# Returns an array of strings with the basename of each item from the argument.
+#
 module Puppet::Parser::Functions
 	newfunction(:basename, :type => :rvalue) do |args|
 		if args[0].is_a?(Array)

plugins/puppet/parser/functions/dirname.rb

@@ -1,9 +1,15 @@
-# dirname(string) : string
+# This function has two modes of operation:
-# dirname(string[]) : string[]
+# 
+#  dirname(string) : string
 #
 # Returns all components of the filename given as argument except the last
 # one. The filename must be formed using forward slashes (``/..) regardless of
 # the separator used on the local file system.
+#
+#  dirname(string[]) : string[]
+#
+# Returns an array of strings with the basename of each item from the argument. 
+#
 module Puppet::Parser::Functions
 	newfunction(:dirname, :type => :rvalue) do |args|
 		if args[0].is_a?(Array)

plugins/puppet/parser/functions/gsub.rb

@@ -1,9 +1,13 @@
+#
+# A thin wrapper around the ruby gsub function.
+# 
+#  gsub($string, $pattern, $replacement)
+#
+# will replace all occurrences of $pattern in $string with $replacement.
+# $string can be either a single value or an array. In the latter case, each
+# element of the array will be processed in turn.
+#
 module Puppet::Parser::Functions
-	# thin wrapper around the ruby gsub function
-	# gsub($string, $pattern, $replacement) will replace all occurrences of
-	# $pattern in $string with $replacement. $string can be either a singel
-	# value or an array. In the latter case, each element of the array will
-	# be processed in turn.
 	newfunction(:gsub, :type => :rvalue) do |args|
 		if args[0].is_a?(Array)
 			args[0].collect do |val|

plugins/puppet/parser/functions/prefix_with.rb

@@ -1,5 +1,15 @@
-# prefix arguments 2..n with first argument
+# Prefixes arguments 2..n with first argument.
-
+#
+#  prefix_with(string prefix, string[] arguments) : string[]
+#
+# Example:
+#
+#  prefix_with("php-", [ "blah", "foo" ])
+#
+# will result in this array:
+#
+#  [ "php-blah", "php-foo" ]
+#
 module Puppet::Parser::Functions
 	newfunction(:prefix_with, :type => :rvalue) do |args|
 		prefix = args.shift

plugins/puppet/parser/functions/re_escape.rb

@@ -1,4 +1,4 @@
-# apply regexp escaping to a string
+# apply ruby regexp escaping to a string
 module Puppet::Parser::Functions
 	newfunction(:re_escape, :type => :rvalue) do |args|
 		Regexp.escape(args[0])

plugins/puppet/parser/functions/split.rb

@@ -1,9 +1,15 @@
-# split($string, $delimiter) : $string
+# This function has two modes of operation: 
-# split($string[], $delimiter) : $string[][]
 #
-# Split the first argument(s) on every $delimiter. $delimiter is interpreted as
+#  split($string, $delimiter) : $string
+#
+# Split the first argument on every $delimiter. $delimiter is interpreted as
 # Ruby regular expression.
 #
+#  split($string[], $delimiter) : $string[][]
+#
+# Returns an array of split results with the result of applying split to each
+# item from the first argument. 
+#
 # For long-term portability it is recommended to refrain from using Ruby's
 # extended RE features.
 module Puppet::Parser::Functions