[src/trunk]: src/etc Add comments about the intended use of each type of meta...

[apb <apb%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/28d6c10640bf
branches:  trunk
changeset: 328600:28d6c10640bf
user:      apb <apb%NetBSD.org@localhost>
date:      Wed Apr 09 12:38:09 2014 +0000

description:
Add comments about the intended use of each type of metadata message.

diffstat:

 etc/rc |  26 +++++++++++++++++++++-----
 1 files changed, 21 insertions(+), 5 deletions(-)

diffs (74 lines):

diff -r 23507d20cfcb -r 28d6c10640bf etc/rc
--- a/etc/rc    Wed Apr 09 12:35:34 2014 +0000
+++ b/etc/rc    Wed Apr 09 12:38:09 2014 +0000
@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# $NetBSD: rc,v 1.166 2011/08/11 22:52:47 apb Exp $
+# $NetBSD: rc,v 1.167 2014/04/09 12:38:09 apb Exp $
 #
 # rc --
 #      Run the scripts in /etc/rc.d with rcorder, and log output
@@ -277,16 +277,20 @@
 
        case "$keyword" in
        start)
-               # $args contains a date/time
+               # Marks the start of the entire /etc/rc script.
+               # $args contains a date/time.
                rc_log_message "[$0 starting at $args]"
                if ! $rc_silent; then
                        printf "%s\n" "$args"
                fi
                ;;
        cmd-name)
+               # Marks the start of a child script (usually one of
+               # the /etc/rc.d/* scripts).
                rc_log_message "[running $1]"
                ;;
        cmd-status)
+               # Marks the end of a child script.
                # $1 is a command name, $2 is the command's exit status.
                # If the command failed, report it, and add it to a list.
                if [ "$2" != 0 ]; then
@@ -307,13 +311,21 @@
                ;;
        nop)
                # Do nothing.
+               # This has the side effect of flushing partial lines,
+               # and the echo() and printf() functions in rc.subr take
+               # advantage of this.
                ;;
        note)
+               # Unlike most metadata messages, which should be used
+               # only by /etc/rc and rc.subr, the "note" message may be
+               # used directly by /etc.rc.d/* and similar scripts.
+               # It adds a note to the log file, without displaying
+               # it to stdout.
                rc_log_message "[NOTE: $args]"
                ;;
        end)
-               #
-               # If any scripts (or other commands) failed, report them.
+               # Marks the end of processing, after the last child script.
+               # If any child scripts (or other commands) failed, report them.
                #
                if [ -n "$rc_failures" ]; then
                        rc_log_message "[failures]"
@@ -330,11 +342,15 @@
                printf "%s\n" "$args"
                ;;
        exit)
+               # Marks an exit from the rc_real_work() function.
+               # This may be a normal or abnormal exit.
+               #
                rc_log_message "[$0 exiting with status $1]"
                exit $1
                ;;
        interrupted)
-               # $args is a human-readable message
+               # Marks an interrupt trapped by the rc_real_work() function.
+               # $args is a human-readable message.
                rc_log_message "$args"
                printf "%s\n" "$args"
                ;;