diff --git a/configwatch.go b/configwatch.go
index 6be3b523..1477ab3a 100644
--- a/configwatch.go
+++ b/configwatch.go
@@ -47,7 +47,7 @@ func NewConfigWatcher() *ConfigWatcher {
 	}
 }
 
-// The Add method adds a new file path to watch for events on.
+// Add new file paths to watch for events on.
 func (obj *ConfigWatcher) Add(file ...string) {
 	if len(file) == 0 {
 		return
diff --git a/event/event.go b/event/event.go
index f6a4d542..d13051eb 100644
--- a/event/event.go
+++ b/event/event.go
@@ -23,8 +23,11 @@ import (
 )
 
 //go:generate stringer -type=EventName -output=eventname_stringer.go
+
+// EventName represents the type of event being passed.
 type EventName int
 
+// The different event names are used in different contexts.
 const (
 	EventNil EventName = iota
 	EventExit
diff --git a/global/global.go b/global/global.go
index 7ec1efa1..04433aff 100644
--- a/global/global.go
+++ b/global/global.go
@@ -18,6 +18,7 @@
 // Package global holds some global variables that are used throughout the code.
 package global
 
+// These constants are used throughout the program.
 const (
 	DEBUG   = false // add additional log messages
 	TRACE   = false // add execution flow log messages
diff --git a/pgraph/pgraph.go b/pgraph/pgraph.go
index b5ec0031..4203a0e1 100644
--- a/pgraph/pgraph.go
+++ b/pgraph/pgraph.go
@@ -714,7 +714,7 @@ func (g *Graph) Worker(v *Vertex) error {
 			<-timer.C // unnecessary, shouldn't happen
 		}
 		var delay = time.Duration(v.Meta().Delay) * time.Millisecond
-		var retry int16 = v.Meta().Retry // number of tries left, -1 for infinite
+		var retry = v.Meta().Retry // number of tries left, -1 for infinite
 		var saved event.Event
 	Loop:
 		for {
@@ -775,7 +775,7 @@ func (g *Graph) Worker(v *Vertex) error {
 	// NOTE: we're using the same retry and delay metaparams that CheckApply
 	// uses. This is for practicality. We can separate them later if needed!
 	var watchDelay time.Duration
-	var watchRetry int16 = v.Meta().Retry // number of tries left, -1 for infinite
+	var watchRetry = v.Meta().Retry // number of tries left, -1 for infinite
 	// watch blocks until it ends, & errors to retry
 	for {
 		// TODO: do we have to stop the converged-timeout when in this block (perhaps we're in the delay block!)
diff --git a/remote/remote.go b/remote/remote.go
index 21c8c1ed..5dfdc401 100644
--- a/remote/remote.go
+++ b/remote/remote.go
@@ -63,6 +63,7 @@ import (
 
 	cv "github.com/purpleidea/mgmt/converger"
 	"github.com/purpleidea/mgmt/gconfig"
+	"github.com/purpleidea/mgmt/global"
 	"github.com/purpleidea/mgmt/util"
 
 	"github.com/howeyc/gopass"
@@ -72,7 +73,6 @@ import (
 )
 
 const (
-	DEBUG = false
 	// FIXME: should this dir be in /var/ instead?
 	formatPattern                        = "/tmp/mgmt.%s/"                        // remote format, to match `mktemp`
 	formatChars                          = "abcdefghijklmnopqrstuvwxyz0123456789" // chars for fmt string // TODO: what does mktemp use?
@@ -143,7 +143,7 @@ func (obj *SSH) Close() error {
 	return obj.client.Close()
 }
 
-// The Sftp function uses the sftp protocol to create a remote dir and copy over
+// Sftp is a function for the sftp protocol to create a remote dir and copy over
 // the binary to run. On error the string represents the path to the remote dir.
 func (obj *SSH) Sftp() error {
 	var err error
@@ -446,7 +446,7 @@ func (obj *SSH) forward(remoteConn net.Conn) net.Conn {
 			log.Printf("Remote: io.Copy error: %s", err)
 			// FIXME: what should we do here???
 		}
-		if DEBUG {
+		if global.DEBUG {
 			log.Printf("Remote: io.Copy finished: %d", n)
 		}
 	}
@@ -705,7 +705,7 @@ type Remotes struct {
 	program string // name of the program
 }
 
-// The NewRemotes function builds a Remotes struct.
+// NewRemotes builds a Remotes struct.
 func NewRemotes(clientURLs, remoteURLs []string, noop bool, remotes []string, fileWatch chan string, cConns uint16, interactive bool, sshPrivIdRsa string, caching bool, depth uint16, prefix string, converger cv.Converger, convergerCb func(func(map[string]bool) error) (func(), error), program string) *Remotes {
 	return &Remotes{
 		clientURLs:   clientURLs,
@@ -890,8 +890,7 @@ func (obj *Remotes) passwordCallback(user, host string) func() (string, error) {
 	return cb
 }
 
-// The Run method of the Remotes struct kicks it all off. It is usually run from
-// a go routine.
+// Run kicks it all off. It is usually run from a go routine.
 func (obj *Remotes) Run() {
 	// TODO: we can disable a lot of this if we're not using --converged-timeout
 	// link in all the converged timeout checking and callbacks...
@@ -922,7 +921,7 @@ func (obj *Remotes) Run() {
 			if !ok { // no status on hostname means unconverged!
 				continue
 			}
-			if DEBUG {
+			if global.DEBUG {
 				log.Printf("Remote: Converged: Status: %+v", obj.converger.Status())
 			}
 			// if exiting, don't update, it will be unregistered...
@@ -1016,8 +1015,8 @@ func (obj *Remotes) Run() {
 	}
 }
 
-// The Exit method causes as much of the Remotes struct to shutdown as quickly
-// and as cleanly as possible. It only returns once everything is shutdown.
+// Exit causes as much of the Remotes struct to shutdown as quickly and as
+// cleanly as possible. It only returns once everything is shutdown.
 func (obj *Remotes) Exit() {
 	obj.lock.Lock()
 	obj.exiting = true // don't spawn new ones once this flag is set!
diff --git a/resources/exec.go b/resources/exec.go
index a1938088..8f9bff59 100644
--- a/resources/exec.go
+++ b/resources/exec.go
@@ -91,7 +91,7 @@ func (obj *ExecRes) Validate() error {
 	return nil
 }
 
-// wraps the scanner output in a channel
+// BufioChanScanner wraps the scanner output in a channel.
 func (obj *ExecRes) BufioChanScanner(scanner *bufio.Scanner) (chan string, chan error) {
 	ch, errch := make(chan string), make(chan error)
 	go func() {
@@ -348,8 +348,7 @@ type ExecUUID struct {
 	// TODO: add more elements here
 }
 
-// if and only if they are equivalent, return true
-// if they are not equivalent, return false
+// IFF aka if and only if they are equivalent, return true. If not, false.
 func (obj *ExecUUID) IFF(uuid ResUUID) bool {
 	res, ok := uuid.(*ExecUUID)
 	if !ok {
@@ -383,7 +382,7 @@ func (obj *ExecUUID) IFF(uuid ResUUID) bool {
 	return true
 }
 
-// The AutoEdges method returns the AutoEdges. In this case none are used.
+// AutoEdges returns the AutoEdge interface. In this case no autoedges are used.
 func (obj *ExecRes) AutoEdges() AutoEdge {
 	// TODO: parse as many exec params to look for auto edges, for example
 	// the path of the binary in the Cmd variable might be from in a pkg
diff --git a/resources/noop.go b/resources/noop.go
index 7ff3f1cc..3f4a0ceb 100644
--- a/resources/noop.go
+++ b/resources/noop.go
@@ -53,7 +53,7 @@ func (obj *NoopRes) Init() error {
 	return obj.BaseRes.Init() // call base init, b/c we're overriding
 }
 
-// validate if the params passed in are valid data
+// Validate if the params passed in are valid data.
 // FIXME: where should this get called ?
 func (obj *NoopRes) Validate() error {
 	return nil
@@ -124,7 +124,7 @@ type NoopUUID struct {
 	name string
 }
 
-// The AutoEdges method returns the AutoEdges. In this case none are used.
+// AutoEdges returns the AutoEdge interface. In this case no autoedges are used.
 func (obj *NoopRes) AutoEdges() AutoEdge {
 	return nil
 }
diff --git a/resources/pkg.go b/resources/pkg.go
index ea5d3a1b..7437b985 100644
--- a/resources/pkg.go
+++ b/resources/pkg.go
@@ -369,8 +369,7 @@ type PkgUUID struct {
 	state string // pkg state or "version"
 }
 
-// if and only if they are equivalent, return true
-// if they are not equivalent, return false
+// IFF aka if and only if they are equivalent, return true. If not, false.
 func (obj *PkgUUID) IFF(uuid ResUUID) bool {
 	res, ok := uuid.(*PkgUUID)
 	if !ok {
@@ -562,7 +561,7 @@ func (obj *PkgRes) Compare(res Res) bool {
 	return true
 }
 
-// return a list of svc names for matches like /usr/lib/systemd/system/*.service
+// ReturnSvcInFileList returns a list of svc names for matches like: `/usr/lib/systemd/system/*.service`.
 func ReturnSvcInFileList(fileList []string) []string {
 	result := []string{}
 	for _, x := range fileList {
diff --git a/resources/resources.go b/resources/resources.go
index 2d57a709..7d0a2904 100644
--- a/resources/resources.go
+++ b/resources/resources.go
@@ -31,8 +31,11 @@ import (
 )
 
 //go:generate stringer -type=ResState -output=resstate_stringer.go
+
+// The ResState type represents the current activity state of each resource.
 type ResState int
 
+// Each ResState should be set properly in the relevant part of the resource.
 const (
 	ResStateNil ResState = iota
 	ResStateWatching
diff --git a/resources/resources_test.go b/resources/resources_test.go
index 24f4b1e4..b688cd85 100644
--- a/resources/resources_test.go
+++ b/resources/resources_test.go
@@ -134,7 +134,7 @@ func TestReadEvent(t *testing.T) {
 		eventExit:     false,
 	}
 
-	for event, _ := range shouldExit {
+	for event := range shouldExit {
 		exit, poke := res.ReadEvent(&Event{Name: event})
 		if exit != shouldExit[event] {
 			t.Errorf("resource.ReadEvent returned wrong exit flag for a %v event (%v, should be %v)",
diff --git a/resources/svc.go b/resources/svc.go
index 43c088fd..8c36d538 100644
--- a/resources/svc.go
+++ b/resources/svc.go
@@ -362,8 +362,7 @@ type SvcUUID struct {
 	name string // the svc name
 }
 
-// if and only if they are equivalent, return true
-// if they are not equivalent, return false
+// IFF aka if and only if they are equivalent, return true. If not, false.
 func (obj *SvcUUID) IFF(uuid ResUUID) bool {
 	res, ok := uuid.(*SvcUUID)
 	if !ok {
@@ -411,7 +410,7 @@ func (obj *SvcResAutoEdges) Test(input []bool) bool {
 	return true // keep going
 }
 
-// The AutoEdges method returns the AutoEdges. In this case the systemd units.
+// AutoEdges returns the AutoEdge interface. In this case the systemd units.
 func (obj *SvcRes) AutoEdges() AutoEdge {
 	var data []ResUUID
 	svcFiles := []string{
diff --git a/resources/timer.go b/resources/timer.go
index 829e9dfb..a84e8107 100644
--- a/resources/timer.go
+++ b/resources/timer.go
@@ -134,7 +134,7 @@ func (obj *TimerRes) GetUUIDs() []ResUUID {
 	return []ResUUID{x}
 }
 
-// The AutoEdges method returns the AutoEdges. In this case none are used.
+// AutoEdges returns the AutoEdge interface. In this case no autoedges are used.
 func (obj *TimerRes) AutoEdges() AutoEdge {
 	return nil
 }