added missing info to godoc + name refactoring

bgp/bgp_api.go

@@ -38,6 +38,7 @@ type WatchRegistration interface {
 
 // ToChan creates a callback that can be passed to the Watch function in order to receive
 // notifications through a channel.
+// Function uses given logger for debug purposes to print received ReachableIPRoutes.
 func ToChan(ch chan ReachableIPRoute, logger logging.Logger) func(info *ReachableIPRoute) {
 	return func(info *ReachableIPRoute) {
 		ch <- *info

bgp/bgp_api_helper_for_test.go

@@ -70,16 +70,21 @@ func (t *TestHelper) DefaultSetup() {
 	t.vars.channel = make(chan bgp.ReachableIPRoute, 1)
 }
 
+// WrappingFuncAsToChanResult adds Wrapping function (that is produced by bgp.ToChan) together with corresponding channel
+// (input for bgp.ToChan) to Given things that will be used in test later (see BDD Given).
 func (g *Given) WrappingFuncAsToChanResult() {
 	g.vars.wrappingFunc = bgp.ToChan(g.vars.channel, logrus.DefaultLogger())
 }
 
+// SentRouteToWrappingFunc creates route and passes it to previously Given wrapping function.
 func (w *When) SentRouteToWrappingFunc() {
 	w.vars.sentRoute = bgp.ReachableIPRoute{As: 1, Prefix: "1.2.3.4/32", Nexthop: net.IPv4(192, 168, 1, 1)}
 	w.vars.wrappingFunc(&w.vars.sentRoute)
 }
 
-func (t *Then) ChannelReceiveIt() {
+// ChannelReceivesIt assert that previously sent route to wrapping function is forwarded (or its copy is forwarded) to
+// channel that was input for wrapping function creation.
+func (t *Then) ChannelReceivesIt() {
 	Expect(t.vars.channel).ToNot(BeEmpty())
 	received := <-t.vars.channel
 	Expect(received).To(Equal(t.vars.sentRoute))

bgp/bgp_api_test.go

@@ -28,5 +28,5 @@ func TestToChan(x *testing.T) {
 
 	t.Given.WrappingFuncAsToChanResult()
 	t.When.SentRouteToWrappingFunc()
-	t.Then.ChannelReceiveIt()
+	t.Then.ChannelReceivesIt()
 }

bgp/gobgp/plugin_impl_gobgp.go

@@ -25,7 +25,9 @@ import (
 	"sync"
 )
 
-// Plugin is GoBGP Ligato BGP Plugin implementation
+// Plugin is GoBGP Ligato BGP Plugin implementation. Purpose of this plugin is to retrieve BGP related information and
+// expose it to watchers that can register to this plugin. To be able to communicate using BGP communication protocol,
+// this plugin uses GoBGP library
 type Plugin struct {
 	Deps
 	server                *server.BgpServer
@@ -79,7 +81,8 @@ func (plugin *Plugin) applyExternalConfig() {
 }
 
 // AfterInit starts gobgp with dedicated goroutine for watching gobgp and forwarding best path reachable ip routes to registered watchers.
-// After start of gobgp session, known neighbors from configuration are added to gobgp server.
+// After start of gobgp session, known neighbors from configuration are added to gobgp server. AfterInit fails if session start or
+// adding of known neighbors from configuration fails.
 // Due to fact that AfterInit is called once Init() of all plugins have returned without error, other plugins can be registered watchers
 // from the start of gobgp server if they call this plugin's WatchIPRoutes() in their Init(). In this way they won't miss any information
 // forwarded to registered watchers just because they registered too late.
@@ -134,6 +137,7 @@ func (plugin *Plugin) watchChanges(watcher *server.Watcher) {
 }
 
 //Close stops dedicated goroutine for watching gobgp. Then stops watcher provider by gobgp server and finally stops that gobgp server itself.
+//Close will fail if bgpServer fails to stop.
 func (plugin *Plugin) Close() error {
 	plugin.Log.Info("Closing goBgp plugin ", plugin.PluginName)
 	close(plugin.stopWatch) //command to stop watching
@@ -143,6 +147,9 @@ func (plugin *Plugin) Close() error {
 }
 
 //WatchIPRoutes register watcher to notifications for any new learned IP-based routes.
+//Watcher have to identify himself by name(watcher param) and provide callback so that GoBGP can sent information to watcher.
+//WatchIPRoutes returns bgp.WatchRegistration as way how to control the watcher-goBGPlugin agreement from the watcher side in the future.
+//It also returns error to indicate failure, but currently for this plugin is not known use case of failure.
 //WatchRegistration is not retroactive, that means that any IP-based routes learned in the past are not send to new watchers.
 //This also means that if you want be notified of all learned IP-based routes, you must register before calling of
 //AfterInit(). In case of external(=not other plugin started with this plugin) watchers this means before plugin start.
@@ -153,7 +160,7 @@ func (plugin *Plugin) WatchIPRoutes(watcher string, callback func(*bgp.Reachable
 	return &watchRegistration{watcher: watcherName(watcher), plugin: plugin}, nil
 }
 
-//startSession starts session on already running goBGP server
+//startSession starts session on already running goBGP server. It fails when start of goBGP server fails.
 func (plugin *Plugin) startSession() error {
 	if err := plugin.server.Start(&plugin.SessionConfig.Global); err != nil {
 		plugin.Log.Error("Failed to initialize go server", plugin.PluginName, err)
@@ -162,7 +169,7 @@ func (plugin *Plugin) startSession() error {
 	return nil
 }
 
-// addKnownNeighbors configures goBGP server for known neighbors from config
+// addKnownNeighbors configures goBGP server for known neighbors from config. It fails when direct adding of neighbors to goBGP server fails.
 func (plugin *Plugin) addKnownNeighbors() error {
 	for _, neighbor := range plugin.SessionConfig.Neighbors {
 		if err := plugin.server.AddNeighbor(&neighbor); err != nil {
@@ -182,6 +189,7 @@ type watchRegistration struct {
 }
 
 //Close ends the agreement between Plugin and watcher. Plugin stops sending watcher any further notifications.
+//It returns failure, but current goBGP implementation doesn't have failure use case.
 func (wr *watchRegistration) Close() error {
 	delete(wr.plugin.watchersWithCallbacks, wr.watcher)
 	return nil

bgp/gobgp/plugin_impl_gobgp_helper_for_test.go

@@ -36,7 +36,7 @@ const (
 	nextHop2                string = "10.0.0.3"
 	prefix1                 string = "10.0.0.0"
 	prefix2                 string = "10.0.0.2"
-	length                  uint8  = 24
+	prefixMaskLength        uint8  = 24
 	expectedReceivedAs             = uint32(65000)
 	maxSessionEstablishment        = 2 * time.Minute
 	timeoutForReceiving            = 30 * time.Second
@@ -195,17 +195,20 @@ func (g *Given) startPluginLifecycle() {
 
 // AddNewRoute adds first constant-based route to route reflector and asserts success.
 func (w *When) AddNewRoute() {
-	Expect(w.addNewRoute(prefix1, nextHop1, length)).To(BeNil(), "Can't add new route")
+	Expect(w.addNewRoute(prefix1, nextHop1, prefixMaskLength)).To(BeNil(), "Can't add new route")
 }
 
 // StopWatchingAndAddNewRoute closes watch registration and adds second constant-based route to route reflector. For both actions success is asserted.
 func (w *When) StopWatchingAndAddNewRoute() {
 	Expect(w.vars.watchRegistration.Close()).To(BeNil(), "Closing registration failed")
-	Expect(w.addNewRoute(prefix2, nextHop2, length)).To(BeNil(), "Can't add new route")
+	Expect(w.addNewRoute(prefix2, nextHop2, prefixMaskLength)).To(BeNil(), "Can't add new route")
 }
 
-// addNewRoute adds route to Route reflector. It returns nonnill error if addition was not successful.
-func (w *When) addNewRoute(prefix string, nextHop string, length uint8) error {
+// addNewRoute adds route to Route reflector.
+// New route is defined by prefix(full IPv4 address as string) with
+// prefixMaskLength(count of bit of network mask for prefix) and nextHop(full IPv4 address as string).
+// It returns nonnill error if addition was not successful.
+func (w *When) addNewRoute(prefix string, nextHop string, prefixMaskLength uint8) error {
 	attrs := []bgpPacket.PathAttributeInterface{
 		bgpPacket.NewPathAttributeOrigin(0),
 		bgpPacket.NewPathAttributeNextHop(nextHop),
@@ -214,7 +217,7 @@ func (w *When) addNewRoute(prefix string, nextHop string, length uint8) error {
 	_, err := w.vars.routeReflector.AddPath("",
 		[]*table.Path{table.NewPath(
 			nil,
-			bgpPacket.NewIPAddrPrefix(length, prefix),
+			bgpPacket.NewIPAddrPrefix(prefixMaskLength, prefix),
 			false,
 			attrs,
 			time.Now(),

examples/gobgp_watch_plugin/main.go

@@ -52,6 +52,7 @@ var (
 	flavor = &local.FlavorLocal{}
 )
 
+// main is the main function for running the whole example
 func main() {
 	goBgpPlugin := gobgp.New(gobgp.Deps{
 		PluginInfraDeps: *flavor.InfraDeps(goBgpPluginName, local.WithConf()),
@@ -72,13 +73,17 @@ func main() {
 	}
 }
 
+// pluginExample is cn-infra plugin that serves as example watcher registered in goBGPplugin.
+// Purpose of this plugin is to show process of registration/unregistration of goBGPPlugin watchers and also how could be the data
+// received by the registered watchers.
 type pluginExample struct {
 	local.PluginInfraDeps
 	reg         bgp.WatchRegistration
 	goBgpPlugin *gobgp.Plugin
 	closeCh     chan struct{}
 }
 
+// newExamplePlugin creates new pluginExample with reference to goBGPPlugin so it can use it later to register itself to goBGPPlugin as watcher.
 func newExamplePlugin(plugin *gobgp.Plugin) *pluginExample {
 	closeCh := make(chan struct{})
 	return &pluginExample{
@@ -87,6 +92,10 @@ func newExamplePlugin(plugin *gobgp.Plugin) *pluginExample {
 		closeCh:         closeCh}
 }
 
+// Init registers pluginExample as watcher in goBGPPlugin. Callback for registered pluginExample will receive first route
+// from goBGPPlugin and then stops the whole example.
+// In case of problems with watcher registration, error (forwarded from registration failure) is returned and initialization
+// of pluginExample fails.
 func (plugin *pluginExample) Init() error {
 	reg, err := plugin.goBgpPlugin.WatchIPRoutes("watcher", func(information *bgp.ReachableIPRoute) {
 		plugin.Log.Infof("Agent received path %v", information)
@@ -96,6 +105,8 @@ func (plugin *pluginExample) Init() error {
 	return err
 }
 
+// Close will unregister pluginExample as watcher in goBGPPlugin.
+// If unregister fails, pluginExample will fail too (with the same error).
 func (plugin *pluginExample) Close() error {
 	return plugin.reg.Close()
 }