Add inline docs and comments

deployment/puppet/keystone/manifests/config.pp

@@ -1,9 +1,58 @@
+# The keystone::config defined resource type is used
+# to model the keystone config file as fragments.
 #
-# Can be used to specify configuration
-# sections in keystone
+# File Fragments are a common Puppet pattern where Puppet creates its
+# own .d directory for a certain config file so that independently configuration
+# sections can be decoupled and managed independently.
 #
-# It will assume that the config
+# The resulting config file is constructed by concatenating all of these
+# fragments into the desired configuration file.
 #
+# == Parameters
+#
+#
+# [*parameters*]
+#
+#   [config] Hash of parameters that can be used to create the config section.
+#     This hash can be accessed from within a template. Optional. Defaults to {}
+#
+#   [content] Content used to create the file fragment. Optional. Defaults to
+#     template("keystone/${name}.erb"
+#
+#   [order] Used to determine how to order fragments in the resulting file. Accepts
+#   an integer. Optional. Defaults to undef.
+#
+# == Dependencies
+#
+#   from Class['keystone']
+#     Requires: Concat['/etc/keystone/keystone.conf'] which models the concatenation
+#       concat { '/etc/keystone/keystone.conf':}
+#     Requires: Class['concat::setup'] which sets up the fragment directories
+#
+# == Examples
+#
+#  # the following will use the template in templates/mysql.erb
+#  keystone::config { 'mysql':
+#    config => {
+#      user          => $user,
+#      password      => $password,
+#      host          => $host,
+#      dbname        => $dbname,
+#      idle_timeout  => $idle_timeout,
+#      min_pool_size => $min_pool_size,
+#      max_pool_size => $max_pool_size,
+#      pool_timeout  => $pool_timeout
+#    },
+#    order  => '02',
+#   }
+#
+# == Authors
+#
+#   Dan Bode dan@puppetlabs.com
+#
+# == Copyright
+#
+# Copyright 2012 Puppetlabs Inc, unless otherwise noted.
 #
 define keystone::config(
   $config    = {},

deployment/puppet/keystone/manifests/dev/install.pp

@@ -1,3 +1,16 @@
+#
+# Installs keystone from source. This is not yet fully implemented
+#
+# == Dependencies
+# == Examples
+# == Authors
+#
+#   Dan Bode dan@puppetlabs.com
+#
+# == Copyright
+#
+# Copyright 2012 Puppetlabs Inc, unless otherwise noted.
+#
 class keystone::dev::install(
   $source_dir = '/usr/local/keystone'
 ) {

deployment/puppet/keystone/manifests/init.pp

@@ -1,5 +1,42 @@
 #
-# module for installing keystone
+# Module for managing keystone config.
+#
+# == Parameters
+#
+#   [package_ensure] Desired ensure state of packages. Optional. Defaults to present.
+#     accepts latest or specific versions.
+#   [bind_host] Host that keystone binds to.
+#   [bind_port]
+#   [public_port]
+#   [admin_port] Port that can be used for admin tasks.
+#   [admin_token] Admin token that can be used to authenticate as a keystone
+#     admin.
+#   [compute_port] TODO
+#   [log_verbose] Rather keystone should log at verbose level. Optional.
+#     Defaults to False.
+#   [log_debug] Rather keystone should log at debug level. Optional.
+#     Defaults to False.
+#   [use_syslog] Rather or not keystone should log to syslog. Optional.
+#     Defaults to False.
+#   [catalog_type]
+#
+# == Dependencies
+#  None
+#
+# == Examples
+#
+#   class { 'keystone':
+#     log_verbose => 'True',
+#     admin_token => 'my_special_token',
+#   }
+#
+# == Authors
+#
+#   Dan Bode dan@puppetlabs.com
+#
+# == Copyright
+#
+# Copyright 2012 Puppetlabs Inc, unless otherwise noted.
 #
 class keystone(
   $package_ensure = 'present',
@@ -16,11 +53,11 @@ class keystone(
 
   validate_re($catalog_type, 'template|sql')
 
+  # TODO implement syslog features
   if ( $use_syslog != 'False') {
     fail('use syslog currently only accepts false')
   }
 
-  # this package dependency needs to be removed when it
   include 'keystone::params'
   include 'concat::setup'
 

deployment/puppet/keystone/manifests/ldap.pp

@@ -1,3 +1,19 @@
+#
+# This class implements a config fragment for
+# the ldap specific backend for keystone.
+#
+# TODO finish implementing this
+#
+# == Dependencies
+# == Examples
+# == Authors
+#
+#   Dan Bode dan@puppetlabs.com
+#
+# == Copyright
+#
+# Copyright 2012 Puppetlabs Inc, unless otherwise noted.
+#
 class keystone::ldap {
   keystone::config { 'ldap':
     order => '01',

deployment/puppet/keystone/manifests/mysql.pp

@@ -1,6 +1,35 @@
 #
 # implements mysql backend for keystone
 #
+# This class can be used to create tables, users and grant
+# privelege for a mysql keystone database.
+#
+# [*Parameters*]
+#
+# [password] Password that will be used for the keystone db user.
+#   Optional. Defaults to: 'keystone_default_password'
+#
+# [dbname] Name of keystone database. Optional. Defaults to keystone.
+#
+# [user] Name of keystone user. Optional. Defaults to keystone_admin.
+#
+# [host] Host where user should be allowed all priveleges for database.
+# Optional. Defaults to 127.0.0.1.
+#
+# [allowed_hosts] TODO implement.
+#
+# == Dependencies
+#   Class['mysql::server']
+#
+# == Examples
+# == Authors
+#
+#   Dan Bode dan@puppetlabs.com
+#
+# == Copyright
+#
+# Copyright 2012 Puppetlabs Inc, unless otherwise noted.
+#
 class keystone::mysql(
   $password      = 'keystone_default_password',
   $dbname        = 'keystone',
@@ -21,6 +50,7 @@ class keystone::mysql(
     user         => $user,
     password     => $password,
     host         => $host,
+    # TODO does it make sense to support other charsets?
     charset      => 'latin1',
     require      => Class['mysql::server'],
   }

deployment/puppet/keystone/manifests/params.pp

@@ -1,3 +1,6 @@
+#
+# This class contains the platform differences for keystone
+#
 class keystone::params {
   case $::osfamily {
     'Debian': {

deployment/puppet/keystone/manifests/repo/trunk.pp

@@ -1,3 +1,6 @@
+#
+# TODO - this is being deprecated
+#
 class keystone::repo::trunk {
   # update this to use adams repo which may require an upgrade to precise
   apt::ppa { 'ppa:openstack-ubuntu-testing/openstack-trunk-testing': }

deployment/puppet/keystone/manifests/roles/admin.pp

@@ -1,3 +1,33 @@
+#
+# This class implements some reasonable admin defaults for keystone.
+#
+# It relies on the Puppet native types that wrap the
+# keystone client command line tool.
+#
+# It creates the following keystone objects:
+#   - service tenant
+#   - openstack tenant
+#   - admin user (that defaults to openstack tenant)
+#   - admin role
+#   - Member role
+#   - adds admin role to admin user on openstack tenant
+# [*Parameters*]
+#
+# [email] The email address for the admin. Optional. Defaults to demo@puppetlabs.com.
+#    TODO should be required.
+# [password] The admin password. Optional. Defaults to ChangeMe
+#    TODO should be required.
+#
+# == Dependencies
+# == Examples
+# == Authors
+#
+#   Dan Bode dan@puppetlabs.com
+#
+# == Copyright
+#
+# Copyright 2012 Puppetlabs Inc, unless otherwise noted.
+#
 class keystone::roles::admin(
   $email    = 'demo@puppetlabs.com',
   $password = 'ChangeMe'