docs: add two warning about no-types mode

Fixes #1161

Author: hynek

docs/examples.md

@@ -43,6 +43,26 @@ False
 
 As shown, the generated `__init__` method allows for both positional and keyword arguments.
 
+---
+
+Unlike Data Classes, *attrs* doesn't force you to use type annotations.
+So, the previous example could also have been written as:
+
+```{doctest}
+>>> @define
+... class Coordinates:
+...     x = field()
+...     y = field()
+>>> Coordinates(1, 2)
+Coordinates(x=1, y=2)
+```
+
+:::{caution}
+If a class body contains a field that is defined using {func}`attrs.field` (or {func}`attr.ib`), but **lacks a type annotation**, *attrs* switches to a no-typing mode and ignores fields that have type annotations but are not defined using {func}`attrs.field` (or {func}`attr.ib`).
+:::
+
+---
+
 For private attributes, *attrs* will strip the leading underscores for keyword arguments:
 
 ```{doctest}

docs/types.md

@@ -19,7 +19,18 @@ SomeClass(a_number=1, list_of_numbers=[1, 2, 3])
 
 You can choose freely between the approaches, but please remember that if you choose to use type annotations, you **must** annotate **all** attributes!
 
----
+:::{caution}
+If you define a class with a {func}`attrs.field` that **lacks** a type annotation, *attrs* will **ignore** other fields that have a type annotation, but are not defined using {func}`attrs.field`:
+
+```{doctest}
+>>> @define
+... class SomeClass:
+...     a_number = field(default=42)
+...     another_number: int = 23
+>>> SomeClass()
+SomeClass(a_number=42)
+```
+:::
 
 Even when going all-in on type annotations, you will need {func}`attrs.field` for some advanced features though.