[mypyc] Document behavior of allow_interpreted_subclasses (#22064)

Document possible surprises arising when using
`@mypyc_attr(allow_interpreted_subclasses=True)`:
- Setting value of an inherited attribute at class level does not update
the native attribute
- Overriding a `@final` method has no effect in native code

Author: p-sawicki

mypyc/doc/native_classes.rst

@@ -83,6 +83,60 @@ a *non-native* subclass (or a subclass defined in another compilation
 unit) will be slower, since it needs to use the normal Python
 attribute access mechanism.
 
+Note that setting the value of an attribute inherited from a native class
+in the body of the interpreted subclass *does not* update the value of
+the native attribute. This leads to native and interpreted code observing
+different values of the attribute::
+
+    # native module
+    from mypy_extensions import mypyc_attr
+
+    @mypyc_attr(allow_interpreted_subclasses=True)
+    class Base:
+        value = 1
+
+        def read_value(self) -> int:
+            return self.value
+
+    # interpreted module
+    from native import Base
+
+    class Child(Base):
+        value = 98
+
+    obj = Child()
+    print(obj.value)         # 98
+    print(obj.read_value())  # 1
+
+When methods are marked `@final` in a native class that allows interpreted
+subclasses, mypyc assumes that no overrides are possible and optimizes calls
+to these methods. This means that if a subclass overrides a final method,
+calls through the compiled base class will still resolve to the base method::
+
+    # native module
+    from typing import final
+    from mypy_extensions import mypyc_attr
+
+    @mypyc_attr(allow_interpreted_subclasses=True)
+    class Base:
+        @final
+        def name(self) -> str:
+            return "base"
+
+        def call_name(self) -> str:
+            return self.name()
+
+    # interpreted module
+    from final_native import Base
+
+    class Child(Base):
+        def name(self) -> str:
+            return "child"
+
+    obj = Child()
+    print(obj.name())       # child
+    print(obj.call_name())  # base
+
 You need to install ``mypy-extensions`` to use ``@mypyc_attr``:
 
 .. code-block:: text