Improve docstrings

Author: ZipFile

src/sonyflake_turbo/_sonyflake.c

@@ -326,6 +326,9 @@ PyDoc_STRVAR(sonyflake_doc,
 "SonyFlake ID generator implementation that combines multiple ID generators into one to improve throughput.\n"
 "Upon counter overflow, it switches to the next machine ID and sleeps only when all machine ids are exhausted for time"
 "frame of 10ms. This produces always-increasing id sequence.\n"
+"\n"
+"Important:\n"
+"    Implementation uses thread locks and blocking sleeps.\n"
 );
 
 static PyType_Slot sonyflake_type_slots[] = {
@@ -423,6 +426,8 @@ PyDoc_STRVAR(machine_id_lcg_doc,
 "MachineIDLCG(seed, /)\n--\n\n"
 "LCG with params a=32309, c=13799, m=65536.\n"
 "Provides a thread-safe way to generate pseudo-random sequence of machine ids to be used as args to SonyFlake.\n"
+"\n"
+"You generally want to use this class as a singleton, i.e. create one instance and reuse it.\n"
 );
 
 

src/sonyflake_turbo/_sonyflake.pyi

@@ -14,11 +14,39 @@ SONYFLAKE_MACHINE_ID_OFFSET: int
 SONYFLAKE_TIME_OFFSET: int
 
 class SonyFlake:
-    def __init__(self, *machine_id: int, start_time: Optional[int] = None): ...
-    def __iter__(self) -> Self: ...
-    def __next__(self) -> int: ...
+    def __init__(self, *machine_id: int, start_time: Optional[int] = None):
+        """Initialize SonyFlake ID generator.
+
+        Args:
+            machine_id: Unique ID(s) of a SonyFlake instance.
+                A number in range [0, 0xFFFF]. Must be provided at least one,
+                at most 65536, and have no duplicates.
+            start_time: Time since which the SonyFlake time is defined as the
+                elapsed time. A UNIX timestamp in UTC time zone, if unset
+                defaults to 1409529600 (2014-09-01 00:00:00 UTC). Must be in
+                the past.
+
+        Raises:
+            ValueError: Invalid values of ``machine_id`` or ``start_time``.
+            TypeError: ``machine_id`` or ``start_time`` are not integers.
+        """
+
+    def __iter__(self) -> Self:
+        """Returns ``self``."""
+
+    def __next__(self) -> int:
+        """Produce a SonyFlake ID."""
 
 class MachineIDLCG:
-    def __init__(self, x: int, /) -> None: ...
-    def __iter__(self) -> Self: ...
-    def __next__(self) -> int: ...
+    def __new__(cls, seed: int, /) -> Self:
+        """Make a LCG.
+
+        Args:
+            seed: Starting seed.
+        """
+
+    def __iter__(self) -> Self:
+        """Returns ``self``."""
+
+    def __next__(self) -> int:
+        """Produce a Machine ID for :class:`SonyFlake`."""