*: add some comments to service Start/Shutdown methods

pkg/consensus/consensus.go

@@ -67,8 +67,11 @@ type Service interface {
 	Name() string
 	// Start initializes dBFT and starts event loop for consensus service.
 	// It must be called only when the sufficient amount of peers are connected.
+	// The service only starts once, subsequent calls to Start are no-op.
 	Start()
-	// Shutdown stops dBFT event loop.
+	// Shutdown stops dBFT event loop. It can only be called once, subsequent calls
+	// to Shutdown on the same instance are no-op. The instance that was stopped can
+	// not be started again by calling Start (use a new instance if needed).
 	Shutdown()
 
 	// OnPayload is a callback to notify the Service about a newly received payload.

pkg/network/server.go

@@ -233,7 +233,8 @@ func (s *Server) ID() uint32 {
 	return s.id
 }
 
-// Start will start the server and its underlying transport.
+// Start will start the server and its underlying transport. Calling it twice
+// is an error.
 func (s *Server) Start(errChan chan error) {
 	s.log.Info("node started",
 		zap.Uint32("blockHeight", s.chain.BlockHeight()),
@@ -251,7 +252,8 @@ func (s *Server) Start(errChan chan error) {
 	s.run()
 }
 
-// Shutdown disconnects all peers and stops listening.
+// Shutdown disconnects all peers and stops listening. Calling it twice is an error,
+// once stopped the same intance of the Server can't be started again by calling Start.
 func (s *Server) Shutdown() {
 	s.log.Info("shutting down server", zap.Int("peers", s.PeerCount()))
 	s.transport.Close()

pkg/rpc/server/server.go

@@ -215,6 +215,7 @@ func (s *Server) Name() string {
 
 // Start creates a new JSON-RPC server listening on the configured port. It creates
 // goroutines needed internally and it returns its errors via errChan passed to New().
+// The Server only starts once, subsequent calls to Start are no-op.
 func (s *Server) Start() {
 	if !s.config.Enabled {
 		s.log.Info("RPC server is not enabled")
@@ -260,7 +261,10 @@ func (s *Server) Start() {
 	}()
 }
 
-// Shutdown stops the RPC server if it's running.
+// Shutdown stops the RPC server if it's running. It can only be called once,
+// subsequent calls to Shutdown on the same instance are no-op. The instance
+// that was stopped can not be started again by calling Start (use a new
+// instance if needed).
 func (s *Server) Shutdown() {
 	if !s.started.CAS(true, false) {
 		return

pkg/services/helpers/rpcbroadcaster/broadcaster.go

@@ -73,7 +73,8 @@ func (r *RPCBroadcaster) SendParams(params request.RawParams) {
 	}
 }
 
-// Shutdown implements oracle.Broadcaster.
+// Shutdown implements oracle.Broadcaster. The same instance can't be Run again
+// after the shutdown.
 func (r *RPCBroadcaster) Shutdown() {
 	close(r.close)
 	<-r.finished

pkg/services/notary/notary.go

@@ -164,6 +164,7 @@ func (n *Notary) Name() string {
 }
 
 // Start runs a Notary module in a separate goroutine.
+// The Notary only starts once, subsequent calls to Start are no-op.
 func (n *Notary) Start() {
 	if !n.started.CAS(false, true) {
 		return
@@ -211,7 +212,9 @@ drainLoop:
 	close(n.done)
 }
 
-// Shutdown stops the Notary module.
+// Shutdown stops the Notary module. It can only be called once, subsequent calls
+// to Shutdown on the same instance are no-op. The instance that was stopped can
+// not be started again by calling Start (use a new instance if needed).
 func (n *Notary) Shutdown() {
 	if !n.started.CAS(true, false) {
 		return

pkg/services/oracle/oracle.go

@@ -181,7 +181,9 @@ func (o *Oracle) Name() string {
 	return "oracle"
 }
 
-// Shutdown shutdowns Oracle.
+// Shutdown shutdowns Oracle. It can only be called once, subsequent calls
+// to Shutdown on the same instance are no-op. The instance that was stopped can
+// not be started again by calling Start (use a new instance if needed).
 func (o *Oracle) Shutdown() {
 	o.respMtx.Lock()
 	defer o.respMtx.Unlock()
@@ -195,6 +197,7 @@ func (o *Oracle) Shutdown() {
 }
 
 // Start runs the oracle service in a separate goroutine.
+// The Oracle only starts once, subsequent calls to Start are no-op.
 func (o *Oracle) Start() {
 	o.respMtx.Lock()
 	if o.running {

pkg/services/stateroot/service.go

@@ -33,7 +33,12 @@ type (
 		OnPayload(p *payload.Extensible) error
 		AddSignature(height uint32, validatorIndex int32, sig []byte) error
 		GetConfig() config.StateRoot
+		// Start runs service instance in a separate goroutine.
+		// The service only starts once, subsequent calls to Start are no-op.
 		Start()
+		// Shutdown stops the service. It can only be called once, subsequent calls
+		// to Shutdown on the same instance are no-op. The instance that was stopped can
+		// not be started again by calling Start (use a new instance if needed).
 		Shutdown()
 	}
 

pkg/services/stateroot/validators.go

@@ -23,6 +23,7 @@ func (s *service) Name() string {
 }
 
 // Start runs service instance in a separate goroutine.
+// The service only starts once, subsequent calls to Start are no-op.
 func (s *service) Start() {
 	if !s.started.CAS(false, true) {
 		return
@@ -63,7 +64,9 @@ drainloop:
 	close(s.done)
 }
 
-// Shutdown stops the service.
+// Shutdown stops the service. It can only be called once, subsequent calls
+// to Shutdown on the same instance are no-op. The instance that was stopped can
+// not be started again by calling Start (use a new instance if needed).
 func (s *service) Shutdown() {
 	if !s.started.CAS(true, false) {
 		return