Comment fixups in preperation for release.

In particular, add comments to the top of the sleep hooks describing what
each of them is for.

17 files changed, 52 insertions, 11 deletions

diff --git a/pm/defaults b/pm/defaults
index 449d34a..c0063c5 100644
--- a/pm/defaults
+++ b/pm/defaults
@@ -12,7 +12,7 @@
 # will be surrounded by [square brackets].
 # HIBERNATE_MODE="shutdown"
 
-# Whetner we need to post the video card when resuming from
+# Whether we need to post the video card when resuming from
 # hibernate. You should not normally need to set this.  
 # In the future pm-utils will get this setting from HAL.
 #
@@ -37,14 +37,13 @@
 # If you need to unload any modules to suspend/resume, add them here.
 # SUSPEND_MODULES=""
 
-# If you want to keep a hook from running even though it is installed,
-# add it here.
+# If you want to keep hooks from running, add their names  here.
 # HOOK_BLACKLIST=""
 
-# If you want to unconditionally add a parameter to the commandline,
-# add it here.
+# If you want to unconditionally add parameters to the commandline,
+# add them here.
 # ADD_PARAMETERS=""
 
-# If you want to ignore a commandline parameter, add it here.
+# If you want to ignore commandline parameters, add them here.
 # DROP_PARAMETERS=""
 
diff --git a/pm/functions.in b/pm/functions.in
index d804ad0..ba1eded 100644
--- a/pm/functions.in
+++ b/pm/functions.in
@@ -38,7 +38,7 @@ spin_lock()
 release_lock()
 {
 	# $1 = lockfile
-	# make sure it is ours first.i
+	# make sure it is ours first.
 	local lock="${LOCKDIR}/${1##*/}"
 	rm -f "${lock}"
 	return $?
@@ -73,6 +73,8 @@ get_power_status()
 	return $RETVAL
 }
 
+# TODO: Module loading and unloading is Linux-specific.  
+# Look into modularizing this into an os-specific set of support routines.
 _rmmod()
 {
 	if modprobe -r "$1"; then
@@ -120,6 +122,7 @@ modunload()
 }
 
 # reload all the modules in no particular order.
+# modprobe should take care of loading prerequisites for us.
 modreload()
 {
 	for x in "${STORAGEDIR}"/module:* ; do
@@ -130,6 +133,8 @@ modreload()
 	done
 }
 
+# Service management is sysv dependent.
+# TODO: modularize this to make it work with other init systems.
 if ! command_exists service; then
 	service()
 	{
diff --git a/pm/pm-functions.in b/pm/pm-functions.in
index 6ea3e75..f69d5fa 100644
--- a/pm/pm-functions.in
+++ b/pm/pm-functions.in
@@ -140,9 +140,9 @@ hook_exit_status(){
 hook_ok()
 {
 	local hook="${1##*/}"
-	## the actual name as passed to us.
+	# the actual name as passed to us.
 	[ -f "$STORAGEDIR/disable_hook:$hook" ] && return $DX
-	## name with zeros chopped off the filename
+	# name with leading digits chopped off the filename
 	[ -f "$STORAGEDIR/disable_hook:${hook#[0-9][0-9]}" ] && return $DX
 	[ -x "$1" ] || return $NX
 	return 0
diff --git a/pm/sleep.d/00clear b/pm/sleep.d/00clear
index eca811c..47a2c85 100755
--- a/pm/sleep.d/00clear
+++ b/pm/sleep.d/00clear
@@ -1,4 +1,7 @@
 #!/bin/sh
+# Ensure we eare in text mode by switching to an unused vt.
+# Also avoids lots of ghastly suspend/resume errors due to trying
+# to suspend/resume while running in X.
 
 . "${PM_FUNCTIONS}"
 
diff --git a/pm/sleep.d/00logging b/pm/sleep.d/00logging
index 7990a50..0642f3f 100755
--- a/pm/sleep.d/00logging
+++ b/pm/sleep.d/00logging
@@ -1,4 +1,6 @@
 #!/bin/sh
+# Log some extra information at the beginning of a suspend/resume cycle.
+# TODO: Make this hook only run when PM_DEBUG is true?
 
 . "${PM_FUNCTIONS}"
 
diff --git a/pm/sleep.d/01grub b/pm/sleep.d/01grub
index 61656a9..096ffa7 100644
--- a/pm/sleep.d/01grub
+++ b/pm/sleep.d/01grub
@@ -1,4 +1,6 @@
 #!/bin/sh
+# Ensure grub will load the correct kernel on resume from hibernate,
+# TODO: This is rather redhat specific, and very grub specific.
 
 default_resume_kernel()
 {
diff --git a/pm/sleep.d/05led b/pm/sleep.d/05led
index 84bef1b..b4bb970 100755
--- a/pm/sleep.d/05led
+++ b/pm/sleep.d/05led
@@ -1,4 +1,6 @@
 #!/bin/sh
+# On an IBM system. make the suspend LED blink.
+# TODO: Merge with 95led?  Should be trivial.
 
 [ -f /proc/acpi/ibm/led ] || exit $NA
 
diff --git a/pm/sleep.d/10NetworkManager b/pm/sleep.d/10NetworkManager
index 8538d6b..244e2c7 100755
--- a/pm/sleep.d/10NetworkManager
+++ b/pm/sleep.d/10NetworkManager
@@ -1,4 +1,10 @@
 #!/bin/sh
+# If we are running NetworkManager, tell it we are going to sleep.
+# TODO: Make NetworkManager smarter about how to handle sleep/resume
+#       If we are asleep for less time than it takes for TCP to reset a
+#       connection, and we are assigned the same IP on resume, we should
+#       not break established connections.  Apple can do this, and it is
+#       rather nifty.
 
 . "${PM_FUNCTIONS}"
 
diff --git a/pm/sleep.d/49bluetooth b/pm/sleep.d/49bluetooth
index dcc792d..d46ba49 100755
--- a/pm/sleep.d/49bluetooth
+++ b/pm/sleep.d/49bluetooth
@@ -1,4 +1,7 @@
 #!/bin/sh
+# IBM specific hack to disable/enable bluetooth.
+# TODO: Doesn't the working USB suspend/resume functionality
+#       make this code more or less obsolete?
 
 . "${PM_FUNCTIONS}"
 
diff --git a/pm/sleep.d/50modules b/pm/sleep.d/50modules
index 338529b..3f292e4 100755
--- a/pm/sleep.d/50modules
+++ b/pm/sleep.d/50modules
@@ -1,4 +1,5 @@
 #!/bin/sh
+# Unload requested modules.
 
 . "${PM_FUNCTIONS}"
 
diff --git a/pm/sleep.d/55battery b/pm/sleep.d/55battery
index 0486c88..1944e98 100755
--- a/pm/sleep.d/55battery
+++ b/pm/sleep.d/55battery
@@ -1,4 +1,6 @@
 #!/bin/sh
+# Have HAL rescan batteries on resume.
+# TODO: Merge this code back into HAL, it should not be in pm-utils.
 
 . "${PM_FUNCTIONS}"
 
diff --git a/pm/sleep.d/65alsa b/pm/sleep.d/65alsa
index 5fc729e..37ba3fe 100755
--- a/pm/sleep.d/65alsa
+++ b/pm/sleep.d/65alsa
@@ -1,4 +1,7 @@
 #!/bin/sh
+# Ensure that ALSA state is saved and restored correctly.
+# TODO: Modern ALSA does not need this hack.  Is it worth trying to detect
+#       that and disable this hook if we do not need it?
 
 . "${PM_FUNCTIONS}"
 
diff --git a/pm/sleep.d/90clock b/pm/sleep.d/90clock
index f69c8c9..985b266 100755
--- a/pm/sleep.d/90clock
+++ b/pm/sleep.d/90clock
@@ -1,4 +1,9 @@
 #!/bin/sh
+# Synchronize system time with hardware time.
+# TODO: Split NTP handling to its own hook. Having it here is ugly and silly.
+#       Do modern kernels handle this correctly?  If so, we should detect that
+#       and skip this hook.
+
 . "${PM_FUNCTIONS}"
 
 NTPD_LOCK="pm-ntpd.lock"
diff --git a/pm/sleep.d/94cpufreq b/pm/sleep.d/94cpufreq
index 03fa09f..6807681 100755
--- a/pm/sleep.d/94cpufreq
+++ b/pm/sleep.d/94cpufreq
@@ -1,4 +1,7 @@
 #!/bin/sh
+# Ensure cpu governor is set to something sane.
+# TODO: Which of the cpu governors is still insane?  File bugs against
+#       those that are.
 
 . "${PM_FUNCTIONS}"
 
diff --git a/pm/sleep.d/95led b/pm/sleep.d/95led
index 20fb64a..253f0b6 100755
--- a/pm/sleep.d/95led
+++ b/pm/sleep.d/95led
@@ -1,4 +1,6 @@
 #!/bin/sh
+# IBM specific hook to handle the suspend LED.
+# TODO: Merge with 05led.
 
 [ -f /proc/acpi/ibm/led ] || exit $NA
 
diff --git a/pm/sleep.d/99video b/pm/sleep.d/99video
index 1f99f85..8e8dd7c 100755
--- a/pm/sleep.d/99video
+++ b/pm/sleep.d/99video
@@ -7,6 +7,11 @@
 # it under the terms of version 2 of the GNU General Public License as
 # published by the Free Software Foundation.
 
+# Handle video quirks.  If you are having suspend/resume issues,
+# troubleshooting using this hook is probably the best place to start.
+# If it weren't for video card quirks, suspend/resume on Linux would be 
+# a whole lot more stable.
+
 . "${PM_FUNCTIONS}"
 
 for opt in $PM_CMDLINE; do
diff --git a/src/pm-action.in b/src/pm-action.in
index 61bf4f3..14d773f 100644
--- a/src/pm-action.in
+++ b/src/pm-action.in
@@ -28,7 +28,6 @@
 
 . "@PM-UTILS-LIBDIR@/pm-functions"
 
-# save the command line parameters for the hooks.
 help()
 {
 	echo "${0##*/} [options]"
@@ -43,7 +42,6 @@ if [ "$(id -u)" != "0" ]; then
 	echo This utility may only be run by the root user. 1>&2
 	exit 1
 fi
-# 
 take_suspend_lock || exit 1
 
 # make sure we release the lock no matter how we exit