From 5d6efb68e11ba90224d80db575e0869310a9a6aa Mon Sep 17 00:00:00 2001
From: zoldalma <46655437+zoldalma999@users.noreply.github.com>
Date: Wed, 25 Sep 2024 19:38:27 +0200
Subject: [PATCH] Document event.peek behaviour, minor doc and stub fixes

---
 buildconfig/stubs/pygame/event.pyi | 12 +++++++-----
 docs/reST/ref/event.rst            |  8 ++++++--
 src_c/doc/event_doc.h              |  2 +-
 src_c/event.c                      |  6 +++---
 4 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/buildconfig/stubs/pygame/event.pyi b/buildconfig/stubs/pygame/event.pyi
index 1987f96de9..b86299d903 100644
--- a/buildconfig/stubs/pygame/event.pyi
+++ b/buildconfig/stubs/pygame/event.pyi
@@ -11,8 +11,10 @@ from pygame.typing import SequenceLike
 
 @final
 class Event:
-    type: int
-    dict: Dict[str, Any]
+    @property
+    def type(self) -> int: ...
+    @property
+    def dict(self) -> Dict[str, Any]: ...
     __dict__: Dict[str, Any]
     __hash__: None  # type: ignore
     def __init__(
@@ -28,13 +30,13 @@ _EventTypes = Union[int, SequenceLike[int]]
 def pump() -> None: ...
 def get(
     eventtype: Optional[_EventTypes] = None,
-    pump: Any = True,
+    pump: bool = True,
     exclude: Optional[_EventTypes] = None,
 ) -> List[Event]: ...
 def poll() -> Event: ...
 def wait(timeout: int = 0) -> Event: ...
-def peek(eventtype: Optional[_EventTypes] = None, pump: Any = True) -> bool: ...
-def clear(eventtype: Optional[_EventTypes] = None, pump: Any = True) -> None: ...
+def peek(eventtype: Optional[_EventTypes] = None, pump: bool = True) -> bool: ...
+def clear(eventtype: Optional[_EventTypes] = None, pump: bool = True) -> None: ...
 def event_name(type: int, /) -> str: ...
 def set_blocked(type: Optional[_EventTypes], /) -> None: ...
 def set_allowed(type: Optional[_EventTypes], /) -> None: ...
diff --git a/docs/reST/ref/event.rst b/docs/reST/ref/event.rst
index b6c8349948..02d66d7c36 100644
--- a/docs/reST/ref/event.rst
+++ b/docs/reST/ref/event.rst
@@ -317,10 +317,14 @@ On Android, the following events can be generated
 .. function:: peek
 
    | :sl:`test if event types are waiting on the queue`
+   | :sg:`peek() -> Event`
    | :sg:`peek(eventtype=None) -> bool`
    | :sg:`peek(eventtype=None, pump=True) -> bool`
 
-   Returns ``True`` if there are any events of the given type waiting on the
+   If the ``eventtype`` argument is not passed or is ``None`` (the default), returns
+   the next event on the queue.
+
+   Otherwise it returns whether there's any events of the given type waiting on the
    queue. If a sequence of event types is passed, this will return ``True`` if
    any of those events are on the queue.
 
@@ -491,7 +495,7 @@ On Android, the following events can be generated
 
       Read-only. The event type identifier. For user created event
       objects, this is the ``type`` argument passed to
-      :func:`pygame.event.Event()`.
+      :class:`pygame.event.Event()`.
 
       For example, some predefined event identifiers are ``QUIT`` and
       ``MOUSEMOTION``.
diff --git a/src_c/doc/event_doc.h b/src_c/doc/event_doc.h
index 16b6f1b0a1..f91e32cc66 100644
--- a/src_c/doc/event_doc.h
+++ b/src_c/doc/event_doc.h
@@ -4,7 +4,7 @@
 #define DOC_EVENT_GET "get(eventtype=None) -> Eventlist\nget(eventtype=None, pump=True) -> Eventlist\nget(eventtype=None, pump=True, exclude=None) -> Eventlist\nget events from the queue"
 #define DOC_EVENT_POLL "poll() -> Event instance\nget a single event from the queue"
 #define DOC_EVENT_WAIT "wait() -> Event instance\nwait(timeout) -> Event instance\nwait for a single event from the queue"
-#define DOC_EVENT_PEEK "peek(eventtype=None) -> bool\npeek(eventtype=None, pump=True) -> bool\ntest if event types are waiting on the queue"
+#define DOC_EVENT_PEEK "peek() -> Event\npeek(eventtype=None) -> bool\npeek(eventtype=None, pump=True) -> bool\ntest if event types are waiting on the queue"
 #define DOC_EVENT_CLEAR "clear(eventtype=None) -> None\nclear(eventtype=None, pump=True) -> None\nremove all events from the queue"
 #define DOC_EVENT_EVENTNAME "event_name(type, /) -> string\nget the string name from an event id"
 #define DOC_EVENT_SETBLOCKED "set_blocked(type, /) -> None\nset_blocked(typelist, /) -> None\nset_blocked(None) -> None\ncontrol which events are blocked on the queue"
diff --git a/src_c/event.c b/src_c/event.c
index 59132e3330..13c9ee4331 100644
--- a/src_c/event.c
+++ b/src_c/event.c
@@ -1420,9 +1420,9 @@ static PyTypeObject pgEvent_Type;
 #define OFF(x) offsetof(pgEventObject, x)
 
 static PyMemberDef pg_event_members[] = {
-    {"__dict__", T_OBJECT, OFF(dict), READONLY},
-    {"type", T_INT, OFF(type), READONLY},
-    {"dict", T_OBJECT, OFF(dict), READONLY},
+    {"__dict__", T_OBJECT, OFF(dict), READONLY, DOC_EVENT_EVENT_DICT},
+    {"type", T_INT, OFF(type), READONLY, DOC_EVENT_EVENT_TYPE},
+    {"dict", T_OBJECT, OFF(dict), READONLY, DOC_EVENT_EVENT_DICT},
     {NULL} /* Sentinel */
 };