edit docs

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2019 gottadiveintopython
+Copyright 2019-2025 gottadiveintopython
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

README.md

@@ -127,24 +127,28 @@ For more details, read the [documentation](https://asyncgui.github.io/asynckivy/
 
 ## Why this even exists
 
-Kivy supports two legitimate async libraries, [asyncio][asyncio] and [Trio][trio], starting from version 2.0.0, so developing another one seems like [reinventing the wheel][reinventing].
-Actually, I started this one just to learn how the async/await syntax works, so it initially was "reinventing the wheel".
-
-But after playing with Trio and Kivy for a while, I noticed that Trio is not suitable for the situation where fast reactions are required e.g. touch events.
-The same is true of asyncio.
-You can confirm that by running `investigation/why_xxx_is_not_suitable_for_handling_touch_events.py`, and mashing a mouse button as quickly as possible.
-You'll see sometimes `up` is not paired with `down`.
-You'll see the coordinates aren't relative to the `RelativeLayout` even though the `target` belongs to it.
-
-The cause of those problems is that `trio.Event.set()` and `asyncio.Event.set()` don't *immediately* resume the tasks waiting for the `Event` to be set.
-They just schedule the tasks to resume.
-Same thing can be said to `nursery.start_soon()` and `asyncio.create_task()`.
+Starting from version 2.0.0, Kivy supports two legitimate async libraries: [asyncio][asyncio] and [Trio][trio].
+At first glance, developing another one might seem like [reinventing the wheel][reinventing].
+Actually, I originally started this project just to learn how the async/await syntax works--
+so at first, it really was 'reinventing the wheel'.
+
+But after experimenting with Trio in combination with Kivy for a while,
+I noticed that Trio isn't suitable for situations requiring fast reactions, such as handling touch events.
+The same applies to asyncio.
+You can confirm this by running `investigation/why_xxx_is_not_suitable_for_handling_touch_events.py` and rapidly clicking a mouse button.
+You'll notice that sometimes `'up'` isn't paired with a corresponding `'down'` in the console output.
+You'll also see that the touch coordinates aren't relative to a `RelativeLayout`,
+even though the widget receiving the touches belongs to it.
+
+The cause of these problems is that `trio.Event.set()` and `asyncio.Event.set()` don't *immediately* resume the tasks waiting for the `Event` to be set--
+they merely schedule them to resume.
+The same is true for `nursery.start_soon()` and `asyncio.create_task()`.
 
 Trio and asyncio are async **I/O** libraries after all.
-They probably don't have to immediately resumes/starts tasks, which I think necessary for touch handling in Kivy.
-(If you fail to handle touches promptly, their state might undergo changes, leaving no time to wait for tasks to resume/start).
-Their core design might not be suitable for GUI in the first place.
-That's why I'm still developing this `asynckivy` library to this day.
+They probably don't need to resume or start tasks immediately, but I believe this is essential for touch handling in Kivy.
+If touch events aren't processed promptly, their state might change before tasks even have a chance to handle them.
+Their core design might not be ideal for GUI applications in the first place.
+That's why I continue to develop the asynckivy library to this day.
 
 [asyncio]:https://docs.python.org/3/library/asyncio.html
 [trio]:https://trio.readthedocs.io/en/stable/

sphinx/notes.rst

@@ -105,7 +105,7 @@ Here is a list of them:
 Places where async operations are disallowed
 --------------------------------------------
 
-Most of the asynckivy APIs that return an async iterator don't allow to perform async operations during the iteration.
+Most asynckivy APIs that return an async iterator don't allow async operations during iteration.
 Here is a list of them:
 
 - :func:`asynckivy.rest_of_touch_events`

src/asynckivy/_anim_with_xxx.py

@@ -36,7 +36,7 @@ def callback(dt):
 
 async def anim_with_et(*, step=0):
     '''
-    Generates the elapsed time of the loop.
+    Returns an async iterator that yields the elapsed time since the start of the iteration.
 
     .. code-block::
 
@@ -82,6 +82,8 @@ async def anim_with_dt_et(*, step=0):
 
 async def anim_with_ratio(*, base, step=0):
     '''
+    Returns an async iterator that yields the elapsed time since the start of the iteration, divided by ``base``.
+
     .. code-block::
 
         async for p in anim_with_ratio(base=3):
@@ -92,7 +94,7 @@ async def anim_with_ratio(*, base, step=0):
     .. code-block::
 
         base = 3
-        async for et in anim_with_et(...):
+        async for et in anim_with_et():
             p = et / base
             print(p)