From 2947aa6619b95299dd934b517a5743eeaf0053bf Mon Sep 17 00:00:00 2001
From: laundmo <laurinschmidt2001@gmail.com>
Date: Mon, 17 Aug 2020 17:49:25 +0200
Subject: [PATCH] Added listener decorator documentation (#161)

* added decorator example to connection.rst

since decorators are more pythonic, it was put in front of the register method.

* Expanded listener decorator docstring

* changed autofunction to autodecorator

* removed whitespace in empty line

* remvoed trailing whitespace

i didn't even edit there WTF
---
 docs/connecting.rst                | 22 +++++++++++++++++++++-
 minecraft/networking/connection.py |  6 +++++-
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/docs/connecting.rst b/docs/connecting.rst
index 0e55d09..7049a66 100644
--- a/docs/connecting.rst
+++ b/docs/connecting.rst
@@ -39,7 +39,26 @@ multiple protocol versions.
 Listening for Certain Packets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Let's look at how to listen for certain packets, the relevant method being
+Let's look at how to listen for certain packets, the relevant decorator being
+
+A decorator can be used to register a packet listener:
+
+.. autodecorator:: Connection.listener
+
+Example usage::
+    
+    connection = Connection(options.address, options.port, auth_token=auth_token)
+    connection.connect()
+    
+    from minecraft.networking.packets.clientbound.play import ChatMessagePacket
+    
+    @connection.listener(ChatMessagePacket)
+    def print_chat(chat_packet):
+        print "Position: " + str(chat_packet.position)
+        print "Data: " + chat_packet.json_data
+
+
+Altenatively, packet listeners can also be registered seperate from the function definition.
 
 .. automethod:: Connection.register_packet_listener
 
@@ -57,6 +76,7 @@ An example of this can be found in the ``start.py`` headless client, it is recre
 
 The field names ``position`` and ``json_data`` are inferred by again looking at the definition attribute as before
 
+
 .. autoclass:: minecraft.networking.packets.clientbound.play.ChatMessagePacket
 	:undoc-members: 
 	:inherited-members:
diff --git a/minecraft/networking/connection.py b/minecraft/networking/connection.py
index f696743..31ce645 100644
--- a/minecraft/networking/connection.py
+++ b/minecraft/networking/connection.py
@@ -105,7 +105,7 @@ class Connection(object):
         """  # NOQA
 
         # This lock is re-entrant because it may be acquired in a re-entrant
-        # manner from within an outgoing packet listener
+        # manner from within an outgoing packet
         self._write_lock = RLock()
 
         self.networking_thread = None
@@ -195,6 +195,10 @@ class Connection(object):
     def listener(self, *packet_types, **kwds):
         """
         Shorthand decorator to register a function as a packet listener.
+
+        Wraps :meth:`minecraft.networking.connection.register_packet_listener`
+        :param packet_types: Packet types to listen for.
+        :param kwds: Keyword arguments for `register_packet_listener`
         """
         def listener_decorator(handler_func):
             self.register_packet_listener(handler_func, *packet_types, **kwds)