Merge pull request #1556 from deis/docs/syslog

docs(logger/syslog): amend syslog server docs

Author: Xe

logger/syslog/README.md

@@ -0,0 +1,6 @@
+# syslog
+
+[![GoDoc](https://godoc.org/github.com/deis/deis/logger/syslog?status.svg)](https://godoc.org/github.com/deis/deis/logger/syslog)
+
+Package syslog implements a syslog server library. It is based on RFC 3164, as 
+such it does not properly parse packets with an RFC 5424 header format.

logger/syslog/filehandler.go

@@ -7,7 +7,7 @@ import (
 	"syscall"
 )
 
-// FileHandler implements Handler interface in the way to save messages into a
+// FileHandler implements Handler interface to save messages into a
 // text file. It properly handles logrotate HUP signal (closes a file and tries
 // to open/create new one).
 type FileHandler struct {
@@ -89,6 +89,7 @@ func (h *FileHandler) checkErr(err error) bool {
 	return true
 }
 
+// See BaseHandler.Handle
 func (h *FileHandler) Handle(m *Message) *Message {
 	return h.bh.Handle(m)
 }

logger/syslog/handler.go

@@ -2,13 +2,13 @@ package syslog
 
 // Handler handles syslog messages
 type Handler interface {
-	// Handle should return Message (mayby modified) for future processing by
+	// Handle should return Message (maybe modified) for future processing by
 	// other handlers or return nil. If Handle is called with nil message it
 	// should complete all remaining work and properly shutdown before return.
 	Handle(*Message) *Message
 }
 
-// BaseHandler is desigend for simplify the creation of real handlers. It
+// BaseHandler is designed to simplify the creation of real handlers. It
 // implements Handler interface using nonblocking queuing of messages and
 // simple message filtering.
 type BaseHandler struct {
@@ -18,7 +18,7 @@ type BaseHandler struct {
 	ft     bool
 }
 
-// NewBaseHandler creates BaseHandler using specified filter. If filter is nil
+// NewBaseHandler creates BaseHandler using a specified filter. If filter is nil
 // or if it returns true messages are passed to BaseHandler internal queue
 // (of qlen length). If filter returns false or ft is true messages are returned
 // to server for future processing by other handlers.
@@ -36,7 +36,7 @@ func NewBaseHandler(qlen int, filter func(*Message) bool, ft bool) *BaseHandler
 // before return.
 func (h *BaseHandler) Handle(m *Message) *Message {
 	if m == nil {
-		close(h.queue) // signal that ther is no more messages for processing
+		close(h.queue) // signal that there is no more messages for processing
 		<-h.end        // wait for handler shutdown
 		return nil
 	}
@@ -66,15 +66,15 @@ func (h *BaseHandler) Get() *Message {
 	return nil
 }
 
-// Queue returns BaseHandler internal queue as read-only channel. You can use
-// it directly, especially if your handler need to select from multiple channels
+// Queue returns the BaseHandler internal queue as a read-only channel. You can use
+// it directly, especially if your handler needs to select from multiple channels
 // or have to work without blocking. You need to check if this channel is closed by
 // sender and properly shutdown in this case.
 func (h *BaseHandler) Queue() <-chan *Message {
 	return h.queue
 }
 
-// End signals the server that handler properly shutdown. You need to call End
+// End signals the server that the handler properly shutdown. You need to call End
 // only if Get has returned nil before.
 func (h *BaseHandler) End() {
 	close(h.end)

logger/syslog/message.go

@@ -6,11 +6,12 @@ import (
 	"time"
 )
 
+// Struct Message defines an RFC 3164 syslog message.
 type Message struct {
-	Time   time.Time
-	Source net.Addr
-	Facility
-	Severity
+	Time   time.Time    // time the message was logged
+	Source net.Addr     // source address of the log message
+	Facility            // facility tag (see type Facility)
+	Severity            // severity tag (see type Severity)
 	Timestamp time.Time // optional
 	Hostname  string    // optional
 	Tag       string    // message tag as defined in RFC 3164
@@ -33,6 +34,8 @@ func (m *Message) NetSrc() string {
 	return m.Source.String()
 }
 
+// String returns the Message in a string format. This satisfies the fmt.Stringer
+// interface.
 func (m *Message) String() string {
 	timeLayout := "2006-01-02 15:04:05"
 	return fmt.Sprintf(

logger/syslog/priority.go

@@ -2,31 +2,32 @@ package syslog
 
 type Facility byte
 
+// The following is a list of Facilities as defined by RFC 3164.
 const (
-	Kern Facility = iota
-	User
-	Mail
-	Daemon
-	Auth
-	Syslog
-	Lpr
-	News
-	Uucp
-	Cron
-	Authpriv
-	System0
-	System1
-	System2
-	System3
-	System4
-	Local0
-	Local1
-	Local2
-	Local3
-	Local4
-	Local5
-	Local6
-	Local7
+	Kern Facility = iota // kernel messages
+	User                 // user-level messages
+	Mail                 // mail system
+	Daemon               // system daemons
+	Auth                 // security/authorization messages
+	Syslog               // messages internal to syslogd
+	Lpr                  // line printer subsystem
+	News                 // newtork news subsystem
+	Uucp                 // UUCP subsystem
+	Cron                 // cron messages
+	Authpriv             // security/authorization messages
+	System0              // historically FTP daemon
+	System1              // historically NTP subsystem
+	System2              // historically log audit
+	System3              // historically log alert
+	System4              // historically clock daemon, some operating systems use this for cron
+	Local0               // local use 0
+	Local1               // local use 1
+	Local2               // local use 2
+	Local3               // local use 3
+	Local4               // local use 4
+	Local5               // local use 5
+	Local6               // local use 6
+	Local7               // local use 7
 )
 
 var facToStr = [...]string{
@@ -56,6 +57,8 @@ var facToStr = [...]string{
 	"local7",
 }
 
+// String returns a string representation of the Facility. This satisfies the
+// fmt.Stringer interface.
 func (f Facility) String() string {
 	if f > Local7 {
 		return "unknown"
@@ -66,14 +69,14 @@ func (f Facility) String() string {
 type Severity byte
 
 const (
-	Emerg Severity = iota
-	Alert
-	Crit
-	Err
-	Warning
-	Notice
-	Info
-	Debug
+	Emerg Severity = iota // Emergency: system is unusable
+	Alert                 // immediate action required
+	Crit                  // critical conditions
+	Err                   // error conditions
+	Warning               // warning conditions
+	Notice                // normal but significant condition
+	Info                  // information message
+	Debug                 // debug-level message
 )
 
 var sevToStr = [...]string{
@@ -87,6 +90,8 @@ var sevToStr = [...]string{
 	"debug",
 }
 
+// String returns a string representation of the Severity. This satisfies the
+// fmt.Stringer interface.
 func (s Severity) String() string {
 	if s > Debug {
 		return "unknown"

logger/syslog/server.go

@@ -1,5 +1,5 @@
-// Syslog server library. It is based on RFC 3164 so it doesn't parse properly
-// packets with new header format (described in RFC 5424).
+// Package syslog implements a syslog server library. It is based on RFC 3164,
+// as such it does not properly parse packets with an RFC 5424 header format.
 package syslog
 
 import (
@@ -13,14 +13,15 @@ import (
 	"unicode"
 )
 
+// Struct Server is the wrapper for a syslog server.
 type Server struct {
 	conns    []net.PacketConn
 	handlers []Handler
 	shutdown bool
 	l        FatalLogger
 }
 
-//  NewServer creates idle server
+//  NewServer creates an idle server
 func NewServer() *Server {
 	return &Server{l: log.New(os.Stderr, "", log.LstdFlags)}
 }