Merge pull request #88 from pymeasure/fix-documentation

Fix listener documentation.

CONTRIBUTING.md

@@ -39,8 +39,8 @@ If you want to add a new feature, please open an issue first in order to discuss
 
 ### Development
 
-Once the general idea is tied down, you can open a pull request with your code.
-We encourage to open a pull request early on.
+Once the general idea is tied down, you can open a pull request (towards the `main` branch) with your code.
+We encourage to open a pull request early on, to incorporate review comments from the beginning.
 
 For development, we recommend _test driven development_, that is writing tests and the features at the same time supporting each other.
 

README.md

@@ -8,9 +8,6 @@
 
 Python reference implementation of the [Laboratory Experiment COntrol (LECO) protocol](https://github.com/pymeasure/leco-protocol).
 
-The [reviewed branch](https://github.com/pymeasure/pyleco/tree/reviewed) contains reviewed code, which does not yet contain all necessary modules and classes.
-Development happens in the [main](https://github.com/pymeasure/pyleco/tree/main) branch.
-
 **Note**: LECO is still under development, such that the code and API might change.
 The LECO protocol branch [pyleco-state](https://github.com/pymeasure/leco-protocol/tree/pyleco-state) contains the assumptions used in this project, which are not yet accepted into the LECO main branch.
 See this [documentation](https://leco-laboratory-experiment-control-protocol--69.org.readthedocs.build/en/69/) for the LECO definitions including these assumptions.

pyleco/utils/listener.py

@@ -36,9 +36,9 @@
 
 
 class Listener:
-    """Listening on published data and opening a configuration port, both in a separate thread.
+    """Listening on incoming messages in a separate thread.
 
-    On one side it handles incoming messages (in another thread).
+    On one side it handles incoming messages (data and control protocol) in another thread.
     On the other side, it offers the :meth:`get_communicator` method, which returns a
     :class:`Communicator`, offering communication to the network.
 
@@ -129,7 +129,7 @@ def start_listen(self) -> None:
         raise TimeoutError("PipeHandler has not started after 0.5 s.")
 
     def get_communicator(self, **kwargs) -> CommunicatorPipe:
-        """Get the communicator for this thread, creating one if necessary."""
+        """Get the communicator for the calling thread, creating one if necessary."""
         kwargs.setdefault("timeout", self.timeout)
         return self.message_handler.get_communicator(**kwargs)
 

pyleco/utils/qt_listener.py

@@ -91,21 +91,18 @@ def handle_subscription_message(self, message: DataMessage) -> None:
 
 
 class QtListener(Listener):
-    """
-    Listening on published data and opening a configuration port. PyQt version.
+    """Listening on incoming messages in a separate thread - PyQt version.
+
+    On one side it handles incoming messages (data and control protocol) in another thread.
+    On the other side, it offers the :meth:`get_communicator` method, which returns a
+    :class:`Communicator`, offering communication to the network.
 
-    Call `listener.start_listen()` to actually listen.
+    Call :meth:`.start_listen()` to actually listen.
 
-    You may send a dictionary to the configuration port, which will be handed
-    to the parent program via the 'command' signal. The listener responds with
-    an acknowledgement or error.
-    Special dictionary keys:
-        - 'query': The listener does not respond, but places the response address
-        into the 'query' entry, that the parent program may respond.
-        - 'save': The listener does not respond, but emits a 'save' signal
-        with the response address.
+    It emits signals from :attr:`signals` if a control or data message arrives.
+    It also emits the `signals.name_changed` signal, whenever the Communicator changes its name.
 
-    :param int port: Configure the port to be used for configuration.
+    :param int data_port: Configure the port to be used for configuration.
     :param logger: Logger instance whose logs should be published. Defaults to "__main__".
     """