docs: document public SDK APIs

[marandaneto]

💡 Motivation and Context

Public SDK APIs should be discoverable from source docstrings as well as the published docs. Several customer-facing methods and configuration options were undocumented or only partially documented in code.

This updates docstrings for public SDK methods/configuration that are documented in the official Python SDK docs or exposed as customer-facing APIs, while leaving internal/private helpers alone.

💚 How did you test it?

• python3 -m compileall -q posthog

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran sampo add to generate a changeset file

[marandaneto]

1st of many PRs documenting all public APIs and configurations so your favorite agent will have a better hint before using outdated docs or making wrong assumptions, well if your agent was heavily depending on that ofc.

[greptile-apps]

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
posthog/ai/otel/exporter.py:74-80
The `force_flush` docstring is missing a `Returns:` section, making it inconsistent with the `export` method directly above it which documents its return value. The method signature declares `-> bool`, so the return value should be described.

```suggestion
    def force_flush(self, timeout_millis: Optional[int] = None) -> bool:
        """
        Flush pending spans from the underlying OTLP exporter.

        Args:
            timeout_millis: Optional flush timeout in milliseconds.

        Returns:
            True if the flush succeeded within the timeout, False otherwise.
        """
```

### Issue 2 of 2
posthog/ai/otel/processor.py:79-85
Same missing `Returns:` section as in `exporter.py` — the `force_flush` method returns `bool` but the docstring does not document the return value.

```suggestion
    def force_flush(self, timeout_millis: Optional[int] = None) -> bool:
        """
        Flush pending spans from the underlying batch span processor.

        Args:
            timeout_millis: Optional flush timeout in milliseconds.

        Returns:
            True if the flush succeeded within the timeout, False otherwise.
        """
```

_{Reviews (1): Last reviewed commit: "docs: document public SDK APIs" | Re-trigger Greptile}

[dustinbyrne]

nice nice nice