Update GitHub API URLs and add docstrings

- Update 51 deprecated GitHub API URLs from developer.github.com to
  docs.github.com with event-specific anchors
- Add docstrings to decorators.py public API (@hook, handle_webhook)
- Add docstrings to all event classes with descriptions
- Add docstrings to key model classes and helper functions
- Follow Google-style docstring format without Attributes sections

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: doodla

octohook/decorators.py

@@ -13,6 +13,12 @@
 
 
 class _WebhookDecorator:
+    """Internal class managing webhook handler registration and dispatch.
+
+    Maintains a three-level handler registry: event -> action -> repository.
+    Handles debug mode where only debug handlers fire for an event.
+    """
+
     def __init__(self):
         self.handlers = defaultdict(  # event_name
             lambda: defaultdict(lambda: defaultdict(set))  # action  # repo  # handlers
@@ -25,6 +31,20 @@ def webhook(
         repositories: List[str] = None,
         debug=False,
     ):
+        """Decorator to register a function as a webhook handler.
+
+        Args:
+            event: The webhook event type to handle.
+            actions: Optional list of actions to filter on. If None, handles all actions.
+            repositories: Optional list of repository full names (owner/repo) to filter on.
+            debug: If True, only this handler runs for the event (other handlers are skipped).
+
+        Example:
+            @hook(WebhookEvent.PULL_REQUEST, actions=[WebhookEventAction.OPENED])
+            def on_pr_opened(event: PullRequestEvent):
+                print(f"PR opened: {event.pull_request.title}")
+        """
+
         def real_decorator(fn):
             @wraps(fn)
             def wrapper(*, event_name, payload):
@@ -58,6 +78,18 @@ def wrapper(*, event_name, payload):
         return real_decorator
 
     def handle_webhook(self, event_name: str, payload: dict):
+        """Dispatch a webhook payload to registered handlers.
+
+        Finds all matching handlers for the event/action/repository combination
+        and executes them sequentially. Exceptions are logged but don't stop execution.
+
+        Args:
+            event_name: The GitHub event name (e.g., "pull_request", "issues").
+            payload: The raw webhook payload dictionary from GitHub.
+
+        Example:
+            handle_webhook("pull_request", request.json)
+        """
         action_handlers = self.handlers[WebhookEvent(event_name)]
 
         # These handlers are invoked all the time.