update documentation

Author: josephlim94

.clinerules/python-best-practices.md

@@ -132,9 +132,11 @@ async def test_plugin_attach():
 ## Documentation Requirements
 
 ### Docstrings
-- **Format:** Use Google-style docstrings
-- **Required:** All public classes, methods, and functions
-- **Parameters:** Document all parameters with types
+- **Format:** Use Google-style docstrings exclusively
+- **Required:** All public classes, methods, and functions must have docstrings
+- **Conciseness:** Keep documentation as concise as possible while being clear
+- **No Implementation Details:** Focus on what the function does, not how it does it
+- **Parameters:** Document all parameters with types and brief descriptions
 - **Returns:** Document return values and types
 - **Raises:** Document exceptions that may be raised
 - **Example:**
@@ -156,6 +158,15 @@ async def join_room(self, room_id: int, username: str, pin: Optional[str] = None
     """
 ```
 
+### Documentation Style Guidelines
+- **Concise Descriptions:** Use clear, brief descriptions that focus on purpose and behavior
+- **Avoid Implementation Details:** Don't document internal algorithms, data structures, or implementation specifics
+- **User-Focused:** Write from the perspective of someone using the API, not implementing it
+- **Consistent Terminology:** Use consistent terms throughout the codebase
+- **Examples:** Include usage examples for complex functions when helpful
+- **Bad Example:** "This method iterates through the internal session dictionary and calls the transport's send method with a JSON-serialized message"
+- **Good Example:** "Send a message to the Janus server and return a transaction for tracking the response"
+
 ### Code Comments
 - **Complex Logic:** Comment complex algorithms or WebRTC-specific code
 - **TODOs:** Use `# TODO:` for future improvements

janus_client/plugin_base.py

@@ -1,5 +1,6 @@
 import logging
 from abc import ABC, abstractmethod
+from typing import Optional
 
 from aiortc import (
     RTCPeerConnection,
@@ -14,43 +15,50 @@
 
 
 class JanusPlugin(ABC):
-    """Base class to inherit when implementing a plugin"""
+    """Base class for implementing Janus plugins."""
 
     name: str = "janus.plugin.base.dummy"
-    """Plugin name
+    """Plugin name that must match the plugin name in Janus server."""
 
-    Must override to match plugin name in Janus server.
-    """
-
-    __id: str
-    """Plugin handle ID. Given by Janus."""
+    __id: Optional[int]
+    """Plugin handle ID assigned by Janus."""
 
     __session: JanusSession
-    """Session instance this plugin is created from."""
+    """Session instance this plugin is attached to."""
 
     _pc: RTCPeerConnection
-    """A WebRTC PeerConnection. A plugin handle is expected to have
-    only 1 PC.
-    """
+    """WebRTC PeerConnection for this plugin handle."""
 
     def __init__(self) -> None:
         self.__id = None
         self._pc = RTCPeerConnection()
 
     @property
-    def id(self) -> int:
+    def id(self) -> Optional[int]:
+        """Get the plugin handle ID.
+
+        Returns:
+            The plugin handle ID assigned by Janus, or None if not attached.
+        """
         return self.__id
 
-    async def attach(self, session: JanusSession):
+    async def attach(self, session: JanusSession) -> None:
+        """Attach this plugin to a Janus session.
+
+        Args:
+            session: The JanusSession to attach this plugin to.
+
+        Raises:
+            Exception: If plugin is already attached to a session.
+        """
         if self.__id:
             raise Exception(f"Plugin already attached to session ({self.__session})")
 
         self.__session = session
         self.__id = await session.attach_plugin(self)
 
-    async def destroy(self):
-        """Destroy plugin handle"""
-
+    async def destroy(self) -> None:
+        """Destroy the plugin handle and clean up resources."""
         message_transaction = await self.send({"janus": "detach"})
         await message_transaction.get()
         await message_transaction.done()
@@ -67,31 +75,66 @@ async def send(
         self,
         message: dict,
     ) -> MessageTransaction:
-        """Send raw message to plugin
+        """Send a message to this plugin handle.
+
+        Automatically attaches the plugin handle ID to the message.
 
-        Will auto attach plugin ID to the message.
+        Args:
+            message: JSON serializable dictionary to send to the plugin.
 
-        :param message: JSON serializable dictionary to send
-        :return: Synchronous reply from server
+        Returns:
+            MessageTransaction for tracking the response.
+
+        Raises:
+            Exception: If plugin is not attached to a session.
         """
+        if self.__id is None:
+            raise Exception("Plugin not attached to session")
 
         self.__sanitize_message(message=message)
 
         return await self.__session.send(message, handle_id=self.__id)
 
     @abstractmethod
-    async def on_receive(self, response: dict):
-        """Handle asynchronous events from Janus"""
+    async def on_receive(self, response: dict) -> None:
+        """Handle asynchronous events from Janus.
+
+        This method must be implemented by subclasses to handle
+        plugin-specific messages and events.
+
+        Args:
+            response: The response message from Janus.
+        """
         pass
 
     async def create_jsep(self, pc: RTCPeerConnection, trickle: bool = False) -> dict:
+        """Create a JSEP object from a peer connection's local description.
+
+        Args:
+            pc: The RTCPeerConnection to extract the description from.
+            trickle: Whether to enable trickle ICE.
+
+        Returns:
+            A JSEP dictionary containing SDP, type, and trickle settings.
+        """
         return {
             "sdp": pc.localDescription.sdp,
             "trickle": trickle,
             "type": pc.localDescription.type,
         }
 
-    async def on_receive_jsep(self, jsep: dict):
+    async def on_receive_jsep(self, jsep: dict) -> None:
+        """Handle incoming JSEP (WebRTC signaling) messages.
+
+        Sets the remote description on the peer connection from the
+        received JSEP offer or answer.
+
+        Args:
+            jsep: The JSEP message containing SDP and type.
+
+        Raises:
+            Exception: If the peer connection is in closed state.
+        """
         if self._pc:
             if self._pc.signalingState == "closed":
                 raise Exception("Received JSEP when PeerConnection is closed")
@@ -100,13 +143,15 @@ async def on_receive_jsep(self, jsep: dict):
                 RTCSessionDescription(sdp=jsep["sdp"], type=jsep["type"])
             )
 
-    async def trickle(self, sdpMLineIndex, candidate):
-        """Send WebRTC candidates to Janus
+    async def trickle(
+        self, sdpMLineIndex: int, candidate: Optional[str] = None
+    ) -> None:
+        """Send WebRTC ICE candidates to Janus using trickle ICE.
 
-        :param sdpMLineIndex: (I don't know what is this)
-        :param candidate: Candidate payload. (I got it from WebRTC instance callback)
+        Args:
+            sdpMLineIndex: The SDP media line index for the candidate.
+            candidate: The ICE candidate string, or None to signal end of candidates.
         """
-
         candidate_payload = dict()
         if candidate:
             candidate_payload = {
@@ -119,6 +164,5 @@ async def trickle(self, sdpMLineIndex, candidate):
             # TODO: test it
             candidate_payload = None
 
-        # await self.send({"janus": "trickle", "candidate": candidate_payload})
         await self.send({"janus": "trickle", "candidate": candidate_payload})
         # TODO: Implement sending an array of candidates