Round of golint fixes to improve documentation.

This is really boring :(

exec.go

@@ -31,6 +31,7 @@ func init() {
 	gob.Register(&ExecRes{})
 }
 
+// ExecRes is an exec resource for running commands.
 type ExecRes struct {
 	BaseRes    `yaml:",inline"`
 	State      string `yaml:"state"`      // state: exists/present?, absent, (undefined?)
@@ -320,6 +321,7 @@ func (obj *ExecRes) CheckApply(apply bool) (checkok bool, err error) {
 	return false, nil    // success
 }
 
+// ExecUUID is the UUID struct for ExecRes.
 type ExecUUID struct {
 	BaseUUID
 	Cmd   string
@@ -362,6 +364,7 @@ func (obj *ExecUUID) IFF(uuid ResUUID) bool {
 	return true
 }
 
+// The AutoEdges method returns the AutoEdges. In this case none 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

file.go

@@ -36,6 +36,7 @@ func init() {
 	gob.Register(&FileRes{})
 }
 
+// FileRes is a file and directory resource.
 type FileRes struct {
 	BaseRes   `yaml:",inline"`
 	Path      string `yaml:"path"` // path variable (should default to name)
@@ -381,6 +382,7 @@ func (obj *FileRes) CheckApply(apply bool) (checkok bool, err error) {
 	return false, nil // success
 }
 
+// FileUUID is the UUID struct for FileRes.
 type FileUUID struct {
 	BaseUUID
 	path string
@@ -433,7 +435,8 @@ func (obj *FileResAutoEdges) Test(input []bool) bool {
 	return true // keep going
 }
 
-// generate a simple linear sequence of each parent directory from bottom up!
+// AutoEdges generates a simple linear sequence of each parent directory from
+// the bottom up!
 func (obj *FileRes) AutoEdges() AutoEdge {
 	var data []ResUUID                             // store linear result chain here...
 	values := PathSplitFullReversed(obj.GetPath()) // build it

misc.go

@@ -25,12 +25,12 @@ import (
 	"time"
 )
 
-// returns the string with the first character capitalized
+// FirstToUpper returns the string with the first character capitalized.
 func FirstToUpper(str string) string {
 	return strings.ToUpper(str[0:1]) + str[1:]
 }
 
-// return true if a string exists inside a list, otherwise false
+// StrInList returns true if a string exists inside a list, otherwise false.
 func StrInList(needle string, haystack []string) bool {
 	for _, x := range haystack {
 		if needle == x {
@@ -40,6 +40,8 @@ func StrInList(needle string, haystack []string) bool {
 	return false
 }
 
+// Uint64KeyFromStrInMap returns true if needle is found in haystack of keys
+// that have uint64 type.
 func Uint64KeyFromStrInMap(needle string, haystack map[uint64]string) (uint64, bool) {
 	for k, v := range haystack {
 		if v == needle {
@@ -49,8 +51,8 @@ func Uint64KeyFromStrInMap(needle string, haystack map[uint64]string) (uint64, b
 	return 0, false
 }
 
-// remove any duplicate values in the list
-// possibly sub-optimal, O(n^2)? implementation
+// StrRemoveDuplicatesInList removes any duplicate values in the list.
+// This is a possibly sub-optimal, O(n^2)? implementation.
 func StrRemoveDuplicatesInList(list []string) []string {
 	unique := []string{}
 	for _, x := range list {
@@ -61,7 +63,8 @@ func StrRemoveDuplicatesInList(list []string) []string {
 	return unique
 }
 
-// remove any of the elements in filter, if they exist in list
+// StrFilterElementsInList removes any of the elements in filter, if they exist
+// in the list.
 func StrFilterElementsInList(filter []string, list []string) []string {
 	result := []string{}
 	for _, x := range list {
@@ -72,8 +75,8 @@ func StrFilterElementsInList(filter []string, list []string) []string {
 	return result
 }
 
-// remove any of the elements in filter, if they don't exist in list
-// this is an in order intersection of two lists
+// StrListIntersection removes any of the elements in filter, if they don't
+// exist in the list. This is an in order intersection of two lists.
 func StrListIntersection(list1 []string, list2 []string) []string {
 	result := []string{}
 	for _, x := range list1 {
@@ -84,7 +87,7 @@ func StrListIntersection(list1 []string, list2 []string) []string {
 	return result
 }
 
-// reverse a list of strings
+// ReverseStringList reverses a list of strings.
 func ReverseStringList(in []string) []string {
 	var out []string // empty list
 	l := len(in)
@@ -94,7 +97,7 @@ func ReverseStringList(in []string) []string {
 	return out
 }
 
-// return the sorted list of string keys in a map with string keys
+// StrMapKeys return the sorted list of string keys in a map with string keys.
 // NOTE: i thought it would be nice for this to use: map[string]interface{} but
 // it turns out that's not allowed. I know we don't have generics, but come on!
 func StrMapKeys(m map[string]string) []string {
@@ -106,6 +109,8 @@ func StrMapKeys(m map[string]string) []string {
 	return result
 }
 
+// StrMapKeysUint64 return the sorted list of string keys in a map with string
+// keys but uint64 values.
 func StrMapKeysUint64(m map[string]uint64) []string {
 	result := []string{}
 	for k := range m {
@@ -115,7 +120,8 @@ func StrMapKeysUint64(m map[string]uint64) []string {
 	return result
 }
 
-// return the sorted list of bool values in a map with string values
+// BoolMapValues returns the sorted list of bool values in a map with string
+// values.
 func BoolMapValues(m map[string]bool) []bool {
 	result := []bool{}
 	for _, v := range m {
@@ -125,7 +131,8 @@ func BoolMapValues(m map[string]bool) []bool {
 	return result
 }
 
-// return the sorted list of string values in a map with string values
+// StrMapValues returns the sorted list of string values in a map with string
+// values.
 func StrMapValues(m map[string]string) []string {
 	result := []string{}
 	for _, v := range m {
@@ -135,7 +142,8 @@ func StrMapValues(m map[string]string) []string {
 	return result
 }
 
-// return the sorted list of string values in a map with string values
+// StrMapValuesUint64 return the sorted list of string values in a map with
+// string values.
 func StrMapValuesUint64(m map[uint64]string) []string {
 	result := []string{}
 	for _, v := range m {
@@ -145,7 +153,7 @@ func StrMapValuesUint64(m map[uint64]string) []string {
 	return result
 }
 
-// return true if everyone is true
+// BoolMapTrue returns true if everyone in the list is true.
 func BoolMapTrue(l []bool) bool {
 	for _, b := range l {
 		if !b {
@@ -155,7 +163,7 @@ func BoolMapTrue(l []bool) bool {
 	return true
 }
 
-// Similar to the GNU dirname command
+// Dirname is similar to the GNU dirname command.
 func Dirname(p string) string {
 	if p == "/" {
 		return ""
@@ -164,6 +172,7 @@ func Dirname(p string) string {
 	return d
 }
 
+// Basename is the base of a path string.
 func Basename(p string) string {
 	_, b := path.Split(path.Clean(p))
 	if p == "" {
@@ -175,7 +184,8 @@ func Basename(p string) string {
 	return b
 }
 
-// Split a path into an array of tokens excluding any trailing empty tokens
+// PathSplit splits a path into an array of tokens excluding any trailing empty
+// tokens.
 func PathSplit(p string) []string {
 	if p == "/" { // TODO: can't this all be expressed nicely in one line?
 		return []string{""}
@@ -183,7 +193,7 @@ func PathSplit(p string) []string {
 	return strings.Split(path.Clean(p), "/")
 }
 
-// Does path string contain the given path prefix in it?
+// HasPathPrefix tells us if a path string contain the given path prefix in it.
 func HasPathPrefix(p, prefix string) bool {
 
 	patharray := PathSplit(p)
@@ -202,6 +212,8 @@ func HasPathPrefix(p, prefix string) bool {
 	return true
 }
 
+// StrInPathPrefixList returns true if the needle is a PathPrefix in the
+// haystack.
 func StrInPathPrefixList(needle string, haystack []string) bool {
 	for _, x := range haystack {
 		if HasPathPrefix(x, needle) {
@@ -211,7 +223,8 @@ func StrInPathPrefixList(needle string, haystack []string) bool {
 	return false
 }
 
-// remove redundant file path prefixes that are under the tree of other files
+// RemoveCommonFilePrefixes removes redundant file path prefixes that are under
+// the tree of other files.
 func RemoveCommonFilePrefixes(paths []string) []string {
 	var result = make([]string, len(paths))
 	for i := 0; i < len(paths); i++ { // copy, b/c append can modify the args!!
@@ -242,7 +255,8 @@ loop:
 	return result
 }
 
-// Delta of path prefix, tells you how many path tokens different the prefix is
+// PathPrefixDelta returns the delta of the path prefix, which tells you how
+// many path tokens different the prefix is.
 func PathPrefixDelta(p, prefix string) int {
 
 	if !HasPathPrefix(p, prefix) {
@@ -253,11 +267,13 @@ func PathPrefixDelta(p, prefix string) int {
 	return len(patharray) - len(prefixarray)
 }
 
+// PathIsDir returns true if there is a trailing slash.
 func PathIsDir(p string) bool {
 	return p[len(p)-1:] == "/" // a dir has a trailing slash in this context
 }
 
-// return the full list of "dependency" paths for a given path in reverse order
+// PathSplitFullReversed returns the full list of "dependency" paths for a given
+// path in reverse order.
 func PathSplitFullReversed(p string) []string {
 	var result []string
 	split := PathSplit(p)
@@ -273,8 +289,8 @@ func PathSplitFullReversed(p string) []string {
 	return ReverseStringList(result)
 }
 
-// add trailing slashes to any likely dirs in a package manager fileList
-// if removeDirs is true, instead, don't keep the dirs in our output
+// DirifyFileList adds trailing slashes to any likely dirs in a package manager
+// fileList if removeDirs is true, otherwise, don't keep the dirs in our output.
 func DirifyFileList(fileList []string, removeDirs bool) []string {
 	dirs := []string{}
 	for _, file := range fileList {
@@ -320,8 +336,9 @@ func FlattenListWithSplit(input []string, split []string) []string {
 	return out
 }
 
-// special version of time.After that blocks when given a negative integer
-// when used in a case statement, the timer restarts on each select call to it
+// TimeAfterOrBlock is aspecial version of time.After that blocks when given a
+// negative integer. When used in a case statement, the timer restarts on each
+// select call to it.
 func TimeAfterOrBlock(t int) <-chan time.Time {
 	if t < 0 {
 		return make(chan time.Time) // blocks forever
@@ -329,8 +346,8 @@ func TimeAfterOrBlock(t int) <-chan time.Time {
 	return time.After(time.Duration(t) * time.Second)
 }
 
-// making using the private bus usable, should be upstream:
-// TODO: https://github.com/godbus/dbus/issues/15
+// SystemBusPrivateUsable makes using the private bus usable
+// TODO: should be upstream: https://github.com/godbus/dbus/issues/15
 func SystemBusPrivateUsable() (conn *dbus.Conn, err error) {
 	conn, err = dbus.SystemBusPrivate()
 	if err != nil {

noop.go

@@ -26,6 +26,7 @@ func init() {
 	gob.Register(&NoopRes{})
 }
 
+// NoopRes is a no-op resource that does nothing.
 type NoopRes struct {
 	BaseRes `yaml:",inline"`
 	Comment string `yaml:"comment"` // extra field for example purposes
@@ -97,11 +98,13 @@ func (obj *NoopRes) CheckApply(apply bool) (checkok bool, err error) {
 	return true, nil // state is always okay
 }
 
+// NoopUUID is the UUID struct for NoopRes.
 type NoopUUID struct {
 	BaseUUID
 	name string
 }
 
+// The AutoEdges method returns the AutoEdges. In this case none are used.
 func (obj *NoopRes) AutoEdges() AutoEdge {
 	return nil
 }

pkg.go

@@ -31,6 +31,7 @@ func init() {
 	gob.Register(&PkgRes{})
 }
 
+// PkgRes is a package resource for packagekit.
 type PkgRes struct {
 	BaseRes          `yaml:",inline"`
 	State            string `yaml:"state"`            // state: installed, uninstalled, newest, <version>
@@ -41,7 +42,7 @@ type PkgRes struct {
 	fileList []string // FIXME: update if pkg changes
 }
 
-// helper function for creating new pkg resources that calls Init()
+// NewPkgRes is a helper function for creating new resources that call Init().
 func NewPkgRes(name, state string, allowuntrusted, allownonfree, allowunsupported bool) *PkgRes {
 	obj := &PkgRes{
 		BaseRes: BaseRes{
@@ -340,6 +341,7 @@ func (obj *PkgRes) CheckApply(apply bool) (checkok bool, err error) {
 	return false, nil    // success
 }
 
+// PkgUUID is the UUID struct for PkgRes.
 type PkgUUID struct {
 	BaseUUID
 	name  string // pkg name
@@ -442,7 +444,8 @@ func (obj *PkgResAutoEdges) Test(input []bool) bool {
 	return true // continue, there are more files!
 }
 
-// produce an object which generates a minimal pkg file optimization sequence
+// AutoEdges produces an object which generates a minimal pkg file optimization
+// sequence of edges.
 func (obj *PkgRes) AutoEdges() AutoEdge {
 	// in contrast with the FileRes AutoEdges() function which contains
 	// more of the mechanics, most of the AutoEdge mechanics for the PkgRes

resources.go

@@ -36,7 +36,7 @@ const (
 	resStatePoking
 )
 
-// a unique identifier for a resource, namely it's name, and the kind ("type")
+// ResUUID is a unique identifier for a resource, namely it's name, and the kind ("type").
 type ResUUID interface {
 	GetName() string
 	Kind() string
@@ -45,6 +45,7 @@ type ResUUID interface {
 	Reversed() bool // true means this resource happens before the generator
 }
 
+// The BaseUUID struct is used to provide a unique resource identifier.
 type BaseUUID struct {
 	name string // name and kind are the values of where this is coming from
 	kind string
@@ -52,19 +53,21 @@ type BaseUUID struct {
 	reversed *bool // piggyback edge information here
 }
 
+// The AutoEdge interface is used to implement the autoedges feature.
 type AutoEdge interface {
 	Next() []ResUUID  // call to get list of edges to add
 	Test([]bool) bool // call until false
 }
 
+// MetaParams is a struct will all params that apply to every resource.
 type MetaParams struct {
 	AutoEdge  bool `yaml:"autoedge"`  // metaparam, should we generate auto edges? // XXX should default to true
 	AutoGroup bool `yaml:"autogroup"` // metaparam, should we auto group? // XXX should default to true
 	Noop      bool `yaml:"noop"`
 }
 
-// this interface is everything that is common to all resources
-// everything here only needs to be implemented once, in the BaseRes
+// The Base interface is everything that is common to all resources.
+// Everything here only needs to be implemented once, in the BaseRes.
 type Base interface {
 	GetName() string // can't be named "Name()" because of struct field
 	SetName(string)
@@ -86,7 +89,7 @@ type Base interface {
 	SetGroup([]Res)
 }
 
-// this is the minimum interface you need to implement to make a new resource
+// Res is the minimum interface you need to implement to define a new resource.
 type Res interface {
 	Base // include everything from the Base interface
 	Init()
@@ -99,6 +102,7 @@ type Res interface {
 	CollectPattern(string) // XXX: temporary until Res collection is more advanced
 }
 
+// BaseRes is the base struct that gets used in every resource.
 type BaseRes struct {
 	Name       string     `yaml:"name"`
 	MetaParams MetaParams `yaml:"meta"` // struct of all the metaparams
@@ -112,7 +116,7 @@ type BaseRes struct {
 	grouped    []Res // list of any grouped resources
 }
 
-// wraps the IFF method when used with a list of UUID's
+// UUIDExistsInUUIDs wraps the IFF method when used with a list of UUID's.
 func UUIDExistsInUUIDs(uuid ResUUID, uuids []ResUUID) bool {
 	for _, u := range uuids {
 		if uuid.IFF(u) {
@@ -122,18 +126,20 @@ func UUIDExistsInUUIDs(uuid ResUUID, uuids []ResUUID) bool {
 	return false
 }
 
+// GetName returns the name of the resource.
 func (obj *BaseUUID) GetName() string {
 	return obj.name
 }
 
+// Kind returns the kind of resource.
 func (obj *BaseUUID) Kind() string {
 	return obj.kind
 }
 
-// if and only if they are equivalent, return true
-// if they are not equivalent, return false
-// most resource will want to override this method, since it does the important
-// work of actually discerning if two resources are identical in function
+// IFF looks at two UUID's and if and only if they are equivalent, returns true.
+// If they are not equivalent, it returns false.
+// Most resources will want to override this method, since it does the important
+// work of actually discerning if two resources are identical in function.
 func (obj *BaseUUID) IFF(uuid ResUUID) bool {
 	res, ok := uuid.(*BaseUUID)
 	if !ok {
@@ -142,6 +148,8 @@ func (obj *BaseUUID) IFF(uuid ResUUID) bool {
 	return obj.name == res.name
 }
 
+// Reversed is part of the ResUUID interface, and true means this resource
+// happens before the generator.
 func (obj *BaseUUID) Reversed() bool {
 	if obj.reversed == nil {
 		log.Fatal("Programming error!")
@@ -149,16 +157,17 @@ func (obj *BaseUUID) Reversed() bool {
 	return *obj.reversed
 }
 
-// initialize structures like channels if created without New constructor
+// Init initializes structures like channels if created without New constructor.
 func (obj *BaseRes) Init() {
 	obj.events = make(chan Event) // unbuffered chan size to avoid stale events
 }
 
-// this method gets used by all the resources
+// GetName is used by all the resources to Get the name.
 func (obj *BaseRes) GetName() string {
 	return obj.Name
 }
 
+// SetName is used to set the name of the resource.
 func (obj *BaseRes) SetName(name string) {
 	obj.Name = name
 }
@@ -168,34 +177,37 @@ func (obj *BaseRes) setKind(kind string) {
 	obj.kind = kind
 }
 
-// Kind returns the kind of resource this is
+// Kind returns the kind of resource this is.
 func (obj *BaseRes) Kind() string {
 	return obj.kind
 }
 
+// Meta returns the MetaParams as a reference, which we can then get/set on.
 func (obj *BaseRes) Meta() *MetaParams {
 	return &obj.MetaParams
 }
 
-// AssociateData associates some data with the object in question
+// AssociateData associates some data with the object in question.
 func (obj *BaseRes) AssociateData(converger Converger) {
 	obj.converger = converger
 }
 
-// is the Watch() function running?
+// IsWatching tells us if the Watch() function is running.
 func (obj *BaseRes) IsWatching() bool {
 	return obj.watching
 }
 
-// store status of if the Watch() function is running
+// SetWatching stores the status of if the Watch() function is running.
 func (obj *BaseRes) SetWatching(b bool) {
 	obj.watching = b
 }
 
+// GetState returns the state of the resource.
 func (obj *BaseRes) GetState() resState {
 	return obj.state
 }
 
+// SetState sets the state of the resource.
 func (obj *BaseRes) SetState(state resState) {
 	if DEBUG {
 		log.Printf("%v[%v]: State: %v -> %v", obj.Kind(), obj.GetName(), obj.GetState(), state)
@@ -203,7 +215,7 @@ func (obj *BaseRes) SetState(state resState) {
 	obj.state = state
 }
 
-// push an event into the message queue for a particular vertex
+// SendEvent pushes an event into the message queue for a particular vertex
 func (obj *BaseRes) SendEvent(event eventName, sync bool, activity bool) bool {
 	// TODO: isn't this race-y ?
 	if !obj.IsWatching() { // element has already exited
@@ -225,8 +237,8 @@ func (obj *BaseRes) SendEvent(event eventName, sync bool, activity bool) bool {
 	}
 }
 
-// process events when a select gets one, this handles the pause code too!
-// the return values specify if we should exit and poke respectively
+// ReadEvent processes events when a select gets one, and handles the pause
+// code too! The return values specify if we should exit and poke respectively.
 func (obj *BaseRes) ReadEvent(event *Event) (exit, poke bool) {
 	event.ACK()
 	switch event.Name {
@@ -269,6 +281,7 @@ func (obj *BaseRes) GroupCmp(res Res) bool {
 	return false // base implementation assumes false, override me!
 }
 
+// GroupRes groups resource (arg) into self.
 func (obj *BaseRes) GroupRes(res Res) error {
 	if l := len(res.GetGroup()); l > 0 {
 		return fmt.Errorf("Res: %v already contains %d grouped resources!", res, l)
@@ -282,18 +295,22 @@ func (obj *BaseRes) GroupRes(res Res) error {
 	return nil
 }
 
+// IsGrouped determines if we are grouped.
 func (obj *BaseRes) IsGrouped() bool { // am I grouped?
 	return obj.isGrouped
 }
 
+// SetGrouped sets a flag to tell if we are grouped.
 func (obj *BaseRes) SetGrouped(b bool) {
 	obj.isGrouped = b
 }
 
+// GetGroup returns everyone grouped inside me.
 func (obj *BaseRes) GetGroup() []Res { // return everyone grouped inside me
 	return obj.grouped
 }
 
+// SetGroup sets the grouped resources into me.
 func (obj *BaseRes) SetGroup(g []Res) {
 	obj.grouped = g
 }
@@ -311,6 +328,7 @@ func (obj *BaseRes) Compare(res Res) bool {
 	return true
 }
 
+// CollectPattern is used for resource collection.
 func (obj *BaseRes) CollectPattern(pattern string) {
 	// XXX: default method is empty
 }

svc.go

@@ -33,6 +33,7 @@ func init() {
 	gob.Register(&SvcRes{})
 }
 
+// SvcRes is a service resource for systemd units.
 type SvcRes struct {
 	BaseRes `yaml:",inline"`
 	State   string `yaml:"state"`   // state: running, stopped, undefined
@@ -320,6 +321,7 @@ func (obj *SvcRes) CheckApply(apply bool) (checkok bool, err error) {
 	return false, nil // success
 }
 
+// SvcUUID is the UUID struct for SvcRes.
 type SvcUUID struct {
 	// NOTE: there is also a name variable in the BaseUUID struct, this is
 	// information about where this UUID came from, and is unrelated to the
@@ -376,6 +378,7 @@ func (obj *SvcResAutoEdges) Test(input []bool) bool {
 	return true // keep going
 }
 
+// The AutoEdges method returns the AutoEdges. In this case the systemd units.
 func (obj *SvcRes) AutoEdges() AutoEdge {
 	var data []ResUUID
 	svcFiles := []string{

timer.go

@@ -27,18 +27,19 @@ func init() {
 	gob.Register(&TimerRes{})
 }
 
-// TimerRes is a timer resource
+// TimerRes is a timer resource for time based events.
 type TimerRes struct {
 	BaseRes  `yaml:",inline"`
 	Interval int `yaml:"interval"` // Interval : Interval between runs
 }
 
+// TimerUUID is the UUID struct for TimerRes.
 type TimerUUID struct {
 	BaseUUID
 	name string
 }
 
-// NewTimerRes creates a new TimerRes
+// NewTimerRes creates a new TimerRes.
 func NewTimerRes(name string, interval int) *TimerRes {
 	obj := &TimerRes{
 		BaseRes: BaseRes{
@@ -114,6 +115,7 @@ func (obj *TimerRes) GetUUIDs() []ResUUID {
 	return []ResUUID{x}
 }
 
+// The AutoEdges method returns the AutoEdges. In this case none are used.
 func (obj *TimerRes) AutoEdges() AutoEdge {
 	return nil
 }