Massive documentation and copyright clean-up.

5 files changed, 93 insertions, 31 deletions

diff --git a/sd_daemon/doc.go b/sd_daemon/doc.go
new file mode 100644
index 0000000..665e25e
--- /dev/null
+++ b/sd_daemon/doc.go
@@ -0,0 +1,16 @@
+// Copyright 2015 Luke Shumaker
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package sd provides APIs for systemd new-style daemons.
+package sd
diff --git a/sd_daemon/listen_fds.go b/sd_daemon/listen_fds.go
index 45ef699..fbd2247 100644
--- a/sd_daemon/listen_fds.go
+++ b/sd_daemon/listen_fds.go
@@ -13,8 +13,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package activation implements primitives for systemd socket activation.
-package sd_daemon
+package sd
 
 import (
 	"os"
@@ -25,6 +24,15 @@ import (
 //#include <systemd/sd-daemon.h>
 import "C"
 
+// Returns a list of file descriptors passed in by the service manager
+// as part of the socket-based activation logic.
+//
+// If unsetEnv is true, then (regarless of whether the function call
+// itself succeeds or not) it will unset the environmental variables
+// LISTEN_FDS and LISTEN_PID, which will cause further calls to this
+// function to fail.
+//
+// In the case of an error, this function returns nil.
 func ListenFds(unsetEnv bool) []*os.File {
 	if unsetEnv {
 		defer os.Unsetenv("LISTEN_PID")
diff --git a/sd_daemon/logger/logger.go b/sd_daemon/logger/logger.go
index f8f3bd6..850df1c 100644
--- a/sd_daemon/logger/logger.go
+++ b/sd_daemon/logger/logger.go
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package logger implements a simple stderr-based logger with systemd
+// log levels.
 package logger
 
 import (
@@ -23,15 +25,23 @@ import (
 import "C"
 
 func log(level string, format string, a ...interface{}) {
-        f := level + format + "\n"
-        fmt.Fprintf(os.Stderr, f, a...)
+	f := level + format + "\n"
+	fmt.Fprintf(os.Stderr, f, a...)
 }
-                
-/* system is unusable               */ func Emerg(  format string, a ...interface{}) { log(C.SD_EMERG  , format, a...); }
-/* action must be taken immediately */ func Alert(  format string, a ...interface{}) { log(C.SD_ALERT  , format, a...); }
-/* critical conditions              */ func Crit(   format string, a ...interface{}) { log(C.SD_CRIT   , format, a...); }
-/* error conditions                 */ func Err(    format string, a ...interface{}) { log(C.SD_ERR    , format, a...); }
-/* warning conditions               */ func Warning(format string, a ...interface{}) { log(C.SD_WARNING, format, a...); }
-/* normal but significant condition */ func Notice( format string, a ...interface{}) { log(C.SD_NOTICE , format, a...); }
-/* informational                    */ func Info(   format string, a ...interface{}) { log(C.SD_INFO   , format, a...); }
-/* debug-level messages             */ func Debug(  format string, a ...interface{}) { log(C.SD_DEBUG  , format, a...); }
+
+// system is unusable
+func Emerg(  format string, a ...interface{}) { log(C.SD_EMERG  , format, a...); }
+// action must be taken immediately
+func Alert(  format string, a ...interface{}) { log(C.SD_ALERT  , format, a...); }
+// critical conditions
+func Crit(   format string, a ...interface{}) { log(C.SD_CRIT   , format, a...); }
+// error conditions
+func Err(    format string, a ...interface{}) { log(C.SD_ERR    , format, a...); }
+// warning conditions
+func Warning(format string, a ...interface{}) { log(C.SD_WARNING, format, a...); }
+// normal but significant condition
+func Notice( format string, a ...interface{}) { log(C.SD_NOTICE , format, a...); }
+// informational
+func Info(   format string, a ...interface{}) { log(C.SD_INFO   , format, a...); }
+// debug-level messages
+func Debug(  format string, a ...interface{}) { log(C.SD_DEBUG  , format, a...); }
diff --git a/sd_daemon/lsb/exit-status.go b/sd_daemon/lsb/exit-status.go
index 41eaafd..cc1604d 100644
--- a/sd_daemon/lsb/exit-status.go
+++ b/sd_daemon/lsb/exit-status.go
@@ -1,3 +1,19 @@
+// Copyright 2015 Luke Shumaker
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package lsb provides constant exit codes specified by the Linux
+// Standard Base.
 package lsb
 
 import (
@@ -5,11 +21,10 @@ import (
 	"sd_daemon/logger"
 )
 
-/* systemd daemon(7) recommends using the exit codes defined in the
- * "LSB recomendations for SysV init scripts"[1].
- *
- * [1]: http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html
- */
+// systemd daemon(7) recommends using the exit codes defined in the
+// "LSB recomendations for SysV init scripts"[1].
+//
+// [1]: http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html
 const (
 	EXIT_SUCCESS         uint8 = 0
 	EXIT_FAILURE         uint8 = 1
@@ -19,13 +34,13 @@ const (
 	EXIT_NOTINSTALLED    uint8 = 5
 	EXIT_NOTCONFIGURED   uint8 = 6
 	EXIT_NOTRUNNING      uint8 = 7
-	/*   8- 99 are reserved for future LSB use */
-	/* 100-149 are reserved for distribution use */
-	/* 150-199 are reserved for application use */
-	/* 200-254 are reserved for init system use */
+	//   8- 99 are reserved for future LSB use
+	// 100-149 are reserved for distribution use
+	// 150-199 are reserved for application use
+	// 200-254 are reserved for init system use
 
-	/* Therefore, the following are taken from systemd's
-	/* `src/basic/exit-status.h` */
+	// Therefore, the following are taken from systemd's
+	// `src/basic/exit-status.h`
 	EXIT_CHDIR               uint8 = 200
 	EXIT_NICE                uint8 = 201
 	EXIT_FDS                 uint8 = 202
@@ -49,7 +64,7 @@ const (
 	EXIT_SETSID              uint8 = 220
 	EXIT_CONFIRM             uint8 = 221
 	EXIT_STDERR              uint8 = 222
-	_EXIT_RESERVED           uint8 = 223 /* used to be tcpwrap don't reuse! */
+	_EXIT_RESERVED           uint8 = 223 // used to be tcpwrap don't reuse!
 	EXIT_PAM                 uint8 = 224
 	EXIT_NETWORK             uint8 = 225
 	EXIT_NAMESPACE           uint8 = 226
@@ -66,6 +81,8 @@ const (
 	EXIT_SMACK_PROCESS_LABEL uint8 = 237
 )
 
+// This is a utility function to defer at the beginning of a goroutine
+// in order to have the correct exit code in the case of a panic.
 func Recover() {
 	if r := recover(); r != nil {
 		logger.Err("panic: %v", r)
diff --git a/sd_daemon/notify.go b/sd_daemon/notify.go
index a038f54..8fce6da 100644
--- a/sd_daemon/notify.go
+++ b/sd_daemon/notify.go
@@ -14,7 +14,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package sd_daemon
+package sd
 
 import (
 	"errors"
@@ -22,11 +22,22 @@ import (
 	"os"
 )
 
-// ErrNotifyNoSocket is an error returned if no socket was specified.
-var ErrNotifyNoSocket = errors.New("No socket")
+// errNotifyNoSocket is an error returned if no socket was specified.
+var errNotifyNoSocket = errors.New("No socket")
 
-// Notify sends a message to the init daemon. It is common to ignore
-// the error.
+// Notify sends a message to the service manager aobout state
+// changes.  It is common to ignore the error.
+//
+// If unsetEnv is true, then (regarless of whether the function call
+// itself succeeds or not) it will unset the environmental variable
+// NOTIFY_SOCKET, which will cause further calls to this function to
+// fail.
+//
+// The state parameter should countain a newline-separated list of
+// variable assignments.
+//
+// See the documentation for sd_notify(3) for well-known variable
+// assignments.
 func Notify(unsetEnv bool, state string) error {
 	if unsetEnv {
 		defer os.Unsetenv("NOTIFY_SOCKET")
@@ -38,7 +49,7 @@ func Notify(unsetEnv bool, state string) error {
 	}
 
 	if socketAddr.Name == "" {
-		return ErrNotifyNoSocket
+		return errNotifyNoSocket
 	}
 
 	conn, err := net.DialUnix(socketAddr.Net, nil, socketAddr)