Merge pull request #44328 from rallytime/doc-fixes

Add some clarifications to event and architecture documentation

doc/topics/development/architecture.rst

@@ -68,8 +68,8 @@ Each salt minion establishes a connection to the master Publisher.
 EventPublisher
 --------------
 
-The EventPublisher publishes events onto the event bus. It is bound to the
-following:
+The EventPublisher publishes master events out to any event listeners. It is
+bound to the following:
 
     * IPC: master_event_pull.ipc
     * IPC: master_event_pub.ipc

doc/topics/event/events.rst

@@ -4,12 +4,25 @@ Event System
 
 The Salt Event System is used to fire off events enabling third party
 applications or external processes to react to behavior within Salt.
+The event system uses a publish-subscribe pattern, otherwise know as pub/sub.
 
-The event system is comprised of a two primary components:
+Event Bus
+=========
+
+The event system is comprised of a two primary components, which make up the
+concept of an Event Bus:
 
     * The event sockets which publishes events.
     * The event library which can listen to events and send events into the salt system.
 
+Events are published onto the event bus and event bus subscribers listen for the
+published events.
+
+The event bus is used for both inter-process communication as well as network transport
+in Salt. Inter-process communication is provided through UNIX domain sockets (UDX).
+
+The Salt Master and each Salt Minion has their own event bus.
+
 Event types
 ===========
 
@@ -21,7 +34,7 @@ Event types
 Listening for Events
 ====================
 
-Salt's Event Bus is used heavily within Salt and it is also written to
+Salt's event system is used heavily within Salt and it is also written to
 integrate heavily with existing tooling and scripts. There is a variety of
 ways to consume it.
 

salt/minion.py

@@ -1037,7 +1037,7 @@ class Minion(MinionBase):
                     u'may result in loss of contact with minions. Please '
                     u'upgrade your ZMQ!'
                 )
-        # Late setup the of the opts grains, so we can log from the grains
+        # Late setup of the opts grains, so we can log from the grains
         # module.  If this is a proxy, however, we need to init the proxymodule
         # before we can get the grains.  We do this for proxies in the
         # post_master_init

salt/transport/zeromq.py

@@ -177,7 +177,7 @@ class AsyncZeroMQReqChannel(salt.transport.client.ReqChannel):
     @tornado.gen.coroutine
     def crypted_transfer_decode_dictentry(self, load, dictkey=None, tries=3, timeout=60):
         if not self.auth.authenticated:
-            # Return controle back to the caller, continue when authentication succeeds
+            # Return control back to the caller, continue when authentication succeeds
             yield self.auth.authenticate()
         # Return control to the caller. When send() completes, resume by populating ret with the Future.result
         ret = yield self.message_client.send(
@@ -569,7 +569,7 @@ class ZeroMQReqServerChannel(salt.transport.mixins.auth.AESReqServerMixin, salt.
     @tornado.gen.coroutine
     def handle_message(self, stream, payload):
         '''
-        Handle incoming messages from underylying TCP streams
+        Handle incoming messages from underlying TCP streams
 
         :stream ZMQStream stream: A ZeroMQ stream.
         See http://zeromq.github.io/pyzmq/api/generated/zmq.eventloop.zmqstream.html
@@ -876,7 +876,7 @@ class AsyncReqMessageClientPool(salt.transport.MessageClientPool):
 # TODO: unit tests!
 class AsyncReqMessageClient(object):
     '''
-    This class wraps the underylying zeromq REQ socket and gives a future-based
+    This class wraps the underlying zeromq REQ socket and gives a future-based
     interface to sending and recieving messages. This works around the primary
     limitation of serialized send/recv on the underlying socket by queueing the
     message sends in this class. In the future if we decide to attempt to multiplex

salt/utils/event.py

@@ -420,7 +420,7 @@ class SaltEvent(object):
                     self.pulluri,
                     io_loop=self.io_loop
                 )
-            # For the async case, the connect will be defered to when
+            # For the async case, the connect will be deferred to when
             # fire_event() is invoked.
             self.cpush = True
         return self.cpush
@@ -576,16 +576,17 @@ class SaltEvent(object):
                   auto_reconnect=False):
         '''
         Get a single publication.
-        IF no publication available THEN block for up to wait seconds
-        AND either return publication OR None IF no publication available.
+        If no publication is available, then block for up to ``wait`` seconds.
+        Return publication if it is available or ``None`` if no publication is
+        available.
 
-        IF wait is 0 then block forever.
+        If wait is 0, then block forever.
 
         tag
             Only return events matching the given tag. If not specified, or set
             to an empty string, all events are returned. It is recommended to
             always be selective on what is to be returned in the event that
-            multiple requests are being multiplexed
+            multiple requests are being multiplexed.
 
         match_type
             Set the function to match the search tag with event tags.
@@ -646,7 +647,8 @@ class SaltEvent(object):
             return ret['data']
 
     def get_event_noblock(self):
-        '''Get the raw event without blocking or any other niceties
+        '''
+        Get the raw event without blocking or any other niceties
         '''
         assert self._run_io_loop_sync
 
@@ -660,8 +662,9 @@ class SaltEvent(object):
         return {'data': data, 'tag': mtag}
 
     def get_event_block(self):
-        '''Get the raw event in a blocking fashion
-           Slower, but decreases the possibility of dropped events
+        '''
+        Get the raw event in a blocking fashion. This is slower, but it decreases the
+        possibility of dropped events.
         '''
         assert self._run_io_loop_sync