Added / corrected comments for api, app & bees packages

api/api.go

@@ -18,7 +18,7 @@
  *      Christian Muehlhaeuser <[email protected]>
  */
 
-// beehive's RESTful api for introspection and configuration
+// Package api is Beehive's RESTful api for introspection and configuration
 package api
 
 import (
@@ -65,6 +65,7 @@ func imageFromPathParam(req *restful.Request, resp *restful.Response) {
 		actual)
 }
 
+// Run sets up the restful API container and an HTTP server go-routine
 func Run() {
 	// to see what happens in the package, uncomment the following
 	//restful.TraceLogger(log.New(os.Stdout, "[restful] ", log.LstdFlags|log.Lshortfile))

app/app.go

@@ -18,13 +18,15 @@
  *      Christian Muehlhaeuser <[email protected]>
  */
 
-// beehive's application container. Handles command-line arguments parsing.
+// Package app is Beehive's application container. Handles command-line arguments parsing.
 package app
 
 import (
 	"flag"
 )
 
+// A CliFlag can be added by Beehive modules to map a command-line parameter
+// to a local variable
 type CliFlag struct {
 	V     interface{}
 	Name  string
@@ -36,12 +38,14 @@ var (
 	appflags []CliFlag
 )
 
+// AddFlags adds CliFlags to appflags
 func AddFlags(flags []CliFlag) {
 	for _, flag := range flags {
 		appflags = append(appflags, flag)
 	}
 }
 
+// Run sets up all the cli-param mappings
 func Run() {
 	for _, f := range appflags {
 		switch f.Value.(type) {

bees/actions.go

@@ -18,6 +18,7 @@
  *      Christian Muehlhaeuser <[email protected]>
  */
 
+// Package bees is Beehive's central module system
 package bees
 
 import (
@@ -27,7 +28,7 @@ import (
 	"text/template"
 )
 
-// An Action
+// Action describes an action.
 type Action struct {
 	ID      string
 	Bee     string
@@ -39,10 +40,12 @@ var (
 	actions []Action
 )
 
+// GetActions returns all configured actions.
 func GetActions() []Action {
 	return actions
 }
 
+// GetAction returns one action with a specific ID.
 func GetAction(id string) *Action {
 	for _, a := range actions {
 		if a.ID == id {
@@ -53,11 +56,12 @@ func GetAction(id string) *Action {
 	return nil
 }
 
+// SetActions sets the currently configured actions.
 func SetActions(as []Action) {
 	actions = as
 }
 
-// Execute an action and map its ins & outs.
+// execAction executes an action and map its ins & outs.
 func execAction(action Action, opts map[string]interface{}) bool {
 	a := Action{
 		Bee:  action.Bee,

bees/bees.go

@@ -18,7 +18,7 @@
  *      Christian Muehlhaeuser <[email protected]>
  */
 
-// beehive's central module system.
+// Package bees is Beehive's central module system
 package bees
 
 import (
@@ -29,7 +29,7 @@ import (
 	uuid "github.com/nu7hatch/gouuid"
 )
 
-// Interface which all bees need to implement
+// BeeInterface is an interface all bees implement.
 type BeeInterface interface {
 	// Name of the bee
 	Name() string
@@ -72,15 +72,15 @@ type BeeInterface interface {
 	Action(action Action) []Placeholder
 }
 
-// An instance of a bee
+// BeeConfig contains all settings for a single Bee.
 type BeeConfig struct {
 	Name        string
 	Class       string
 	Description string
 	Options     BeeOptions
 }
 
-// Base-struct to be embedded by bee implementations
+// Bee is the base-struct to be embedded by bee implementations.
 type Bee struct {
 	config BeeConfig
 
@@ -97,14 +97,14 @@ var (
 	factories map[string]*BeeFactoryInterface = make(map[string]*BeeFactoryInterface)
 )
 
-// Bees need to call this method to register themselves
+// RegisterBee gets called by Bees to register themselves.
 func RegisterBee(bee BeeInterface) {
 	log.Println("Worker bee ready:", bee.Name(), "-", bee.Description())
 
 	bees[bee.Name()] = &bee
 }
 
-// Returns bee with this name
+// GetBee returns a bee with a specific name.
 func GetBee(identifier string) *BeeInterface {
 	bee, ok := bees[identifier]
 	if ok {
@@ -114,7 +114,7 @@ func GetBee(identifier string) *BeeInterface {
 	return nil
 }
 
-// Returns all known bees
+// GetBees returns all known bees.
 func GetBees() []*BeeInterface {
 	r := []*BeeInterface{}
 	for _, bee := range bees {
@@ -124,7 +124,7 @@ func GetBees() []*BeeInterface {
 	return r
 }
 
-// Starts a bee and recovers from panics
+// startBee starts a bee and recovers from panics.
 func startBee(bee *BeeInterface, fatals int) {
 	if fatals >= 3 {
 		log.Println("Terminating evil bee", (*bee).Name(), "after", fatals, "failed tries!")
@@ -142,6 +142,7 @@ func startBee(bee *BeeInterface, fatals int) {
 	(*bee).Run(eventsIn)
 }
 
+// NewBeeInstance sets up a new Bee with supplied config.
 func NewBeeInstance(bee BeeConfig) *BeeInterface {
 	factory := GetFactory(bee.Class)
 	if factory == nil {
@@ -153,13 +154,14 @@ func NewBeeInstance(bee BeeConfig) *BeeInterface {
 	return &mod
 }
 
+// DeleteBee removes a Bee instance.
 func DeleteBee(bee *BeeInterface) {
 	(*bee).Stop()
 
 	delete(bees, (*bee).Name())
 }
 
-// Starts all registered bees
+// StartBee starts a bee.
 func StartBee(bee BeeConfig) *BeeInterface {
 	b := NewBeeInstance(bee)
 
@@ -171,7 +173,7 @@ func StartBee(bee BeeConfig) *BeeInterface {
 	return b
 }
 
-// Starts all registered bees
+// StartBees starts all registered bees.
 func StartBees(beeList []BeeConfig) {
 	eventsIn = make(chan Event)
 	go handleEvents()
@@ -181,7 +183,7 @@ func StartBees(beeList []BeeConfig) {
 	}
 }
 
-// Stops all bees gracefully
+// StopBees stops all bees gracefully.
 func StopBees() {
 	for _, bee := range bees {
 		log.Println("Stopping bee:", (*bee).Name())
@@ -192,6 +194,7 @@ func StopBees() {
 	bees = make(map[string]*BeeInterface)
 }
 
+// RestartBee restarts a Bee.
 func RestartBee(bee *BeeInterface) {
 	(*bee).Stop()
 
@@ -203,13 +206,13 @@ func RestartBee(bee *BeeInterface) {
 	}(bee)
 }
 
-// Stops all running bees and restarts a new set of bees
+// RestartBees stops all running bees and restarts a new set of bees.
 func RestartBees(bees []BeeConfig) {
 	StopBees()
 	StartBees(bees)
 }
 
-// Returns a new bee and sets up sig-channel & waitGroup
+// NewBee returns a new bee and sets up sig-channel & waitGroup.
 func NewBee(name, factoryName, description string, options []BeeOption) Bee {
 	c := BeeConfig{
 		Name:        name,
@@ -227,6 +230,7 @@ func NewBee(name, factoryName, description string, options []BeeOption) Bee {
 	return b
 }
 
+// BeeConfigs returns configs for all Bees.
 func BeeConfigs() []BeeConfig {
 	bs := []BeeConfig{}
 	for _, b := range bees {
@@ -236,6 +240,7 @@ func BeeConfigs() []BeeConfig {
 	return bs
 }
 
+// UUID generates a new unique ID.
 func UUID() string {
 	u, _ := uuid.NewV4()
 	return u.String()

bees/chains.go

@@ -18,17 +18,18 @@
  *      Christian Muehlhaeuser <[email protected]>
  */
 
+// Package bees is Beehive's central module system
 package bees
 
 import "log"
 
-// An element in a Chain
+// ChainElement is an element in a Chain
 type ChainElement struct {
 	Action Action
 	Filter Filter
 }
 
-// A user defined Chain
+// Chain is a user defined chain
 type Chain struct {
 	Name        string
 	Description string
@@ -42,10 +43,12 @@ var (
 	chains []Chain
 )
 
+// GetChains returns all chains
 func GetChains() []Chain {
 	return chains
 }
 
+// GetChain returns a chain with a specific id
 func GetChain(id string) *Chain {
 	for _, c := range chains {
 		if c.Name == id {
@@ -56,7 +59,7 @@ func GetChain(id string) *Chain {
 	return nil
 }
 
-// Setter for chains
+// SetChains sets the currently configured chains
 func SetChains(cs []Chain) {
 	newcs := []Chain{}
 	// migrate old chain style
@@ -80,7 +83,7 @@ func SetChains(cs []Chain) {
 	chains = newcs
 }
 
-// Execute chains for an event we received.
+// execChains executes chains for an event we received
 func execChains(event *Event) {
 	for _, c := range chains {
 		if c.Event.Name != event.Name || c.Event.Bee != event.Bee {

bees/descriptors.go

@@ -18,17 +18,18 @@
  *      Christian Muehlhaeuser <[email protected]>
  */
 
+// Package bees is Beehive's central module system
 package bees
 
-// Modules provide events, which are described in an EventDescriptor.
+// EventDescriptor describes an Event provided by a Bee.
 type EventDescriptor struct {
 	Namespace   string
 	Name        string
 	Description string
 	Options     []PlaceholderDescriptor
 }
 
-// Modules offer actions, which are described in an ActionDescriptor.
+// ActionDescriptor describes an Action provided by a Bee.
 type ActionDescriptor struct {
 	Namespace   string
 	Name        string
@@ -52,7 +53,7 @@ type BeeOptionDescriptor struct {
 	Mandatory   bool
 }
 
-// Returns the ActionDescriptor matching an action.
+// GetActionDescriptor returns the ActionDescriptor matching an action.
 func GetActionDescriptor(action *Action) ActionDescriptor {
 	bee := GetBee(action.Bee)
 	if bee == nil {
@@ -68,7 +69,7 @@ func GetActionDescriptor(action *Action) ActionDescriptor {
 	return ActionDescriptor{}
 }
 
-// Returns the EventDescriptor matching an event.
+// GetEventDescriptor returns the EventDescriptor matching an event.
 func GetEventDescriptor(event *Event) EventDescriptor {
 	bee := GetBee(event.Bee)
 	if bee == nil {

bees/events.go

@@ -18,12 +18,12 @@
  *      Christian Muehlhaeuser <[email protected]>
  */
 
-// beehive's central module system.
+// Package bees is Beehive's central module system
 package bees
 
 import "log"
 
-// An Event
+// An Event describes an event including its parameters.
 type Event struct {
 	Bee     string
 	Name    string
@@ -34,7 +34,7 @@ var (
 	eventsIn = make(chan Event)
 )
 
-// Handles incoming events and executes matching Chains.
+// handleEvents handles incoming events and executes matching Chains.
 func handleEvents() {
 	for {
 		event, ok := <-eventsIn