docs: state the option layer rules in capture docstrings

Author: eli-r-ph

posthog/__init__.py

@@ -387,7 +387,9 @@ def get_context_options() -> Dict[str, Any]:
         an event's own properties override them.
     super_options: Capture options for every captured event, such as
         ``{"cookieless_mode": True}``. Context options and an event's own
-        ``options`` override them.
+        ``options`` override them. They also win over an event's legacy
+        property for the same key, such as ``$cookieless_mode``, so pass
+        per-event overrides of that key as ``options``.
     metrics: Config dict for the ``client.metrics`` API (``service_name``,
         ``service_version``, ``environment``, ``flush_interval``, ...). Applied
         when ``setup()`` builds the global client, or on a later ``setup()``

posthog/client.py

@@ -803,7 +803,9 @@ def __init__(
                 tags and an event's own properties override them.
             super_options: Capture options for every captured event, such as
                 ``{"cookieless_mode": True}``. Context options and an event's
-                own ``options`` override them.
+                own ``options`` override them. They also win over an event's
+                legacy property for the same key, such as ``$cookieless_mode``,
+                so pass per-event overrides of that key as ``options``.
             enable_exception_autocapture: Automatically capture uncaught
                 exceptions.
             log_captured_exceptions: Also log exceptions captured by error
@@ -1326,6 +1328,9 @@ def set_context_option(self, key: str, value: Any) -> None:
         """
         Set a capture option for every event captured within the current context.
 
+        Context options override ``super_options``. An event's own ``options``
+        override context options.
+
         Args:
             key: The option name, such as ``"process_person_profile"``.
             value: The option value, sent as given.
@@ -1667,8 +1672,10 @@ def capture(
             disable_geoip: Whether to disable GeoIP for this event.
             options: Capture options for this event, such as
                 ``{"process_person_profile": False}``. Sent as given, for
-                PostHog to validate. An option wins over its legacy ``$``
-                property, such as ``$process_person_profile``.
+                PostHog to validate. They override context options and
+                ``super_options``. An option set at any layer wins over its
+                legacy ``$`` property, such as ``$process_person_profile``,
+                set at any layer. A ``None`` option counts as unset.
 
         Examples:
             ```python