docs: add glossary entries for field & attribute

hynek · hynek · commit b78abadbbff8 · 2024-08-01T06:43:24.000+02:00
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -10,12 +10,14 @@ dunder methods
 
   Its first documented use is a [mailing list posting](https://mail.python.org/pipermail/python-list/2002-September/155836.html) by Mark Jackson from 2002.
 
+
 dict classes
   A regular class whose attributes are stored in the {attr}`object.__dict__` attribute of every single instance.
   This is quite wasteful especially for objects with very few data attributes and the space consumption can become significant when creating large numbers of instances.
 
   This is the type of class you get by default both with and without *attrs* (except with the next APIs {func}`attrs.define()`, [`attrs.mutable()`](attrs.mutable), and [`attrs.frozen()`](attrs.frozen)).
 
+
 slotted classes
   A class whose instances have no {attr}`object.__dict__` attribute and [define](https://docs.python.org/3/reference/datamodel.html#slots) their attributes in a `object.__slots__` attribute instead.
   In *attrs*, they are created by passing `slots=True` to `@attr.s` (and are on by default in {func}`attrs.define()`, [`attrs.mutable()`](attrs.mutable), and [`attrs.frozen()`](attrs.frozen)).
@@ -101,6 +103,22 @@ slotted classes
   - Pickling of slotted classes will fail if you define a class with missing attributes.
 
     This situation can occur if you define an `attrs.field(init=False)` and don't set the attribute by hand before pickling.
+
+
+field
+  As the project name suggests, *attrs* is all about attributes.
+  We especially tried to emphasize that we only care about attributes and not about the classes themselves -- because we believe the class belongs to the user.
+
+  This explains why the traditional API uses an {func}`attr.ib` (or ``attrib``) function to define attributes and we still use the term throughout the documentation.
+
+  However, with the emergence of {mod}`dataclasses`, [Pydantic](https://docs.pydantic.dev/latest/concepts/fields/), and other libraries, the term "field" has become a common term for a predefined attribute on a class in the Python ecosystem.
+
+  So with out new APIs, we've embraced it too by calling the function to create them {func}`attrs.field`, and use the term "field" throughout the documentation interchangeably.
+
+  See also {doc}`names`.
+
+attribute
+  See {term}`field`.
 :::
 
 [^pypy]: On PyPy, there is no memory advantage in using slotted classes.
diff --git a/src/attr/_funcs.py b/src/attr/_funcs.py
@@ -454,9 +454,9 @@ def resolve_types(
     """
     Resolve any strings and forward annotations in type annotations.
 
-    This is only required if you need concrete types in `Attribute`'s *type*
-    field. In other words, you don't need to resolve your types if you only use
-    them for static type checking.
+    This is only required if you need concrete types in :class:`Attribute`'s
+    *type* field. In other words, you don't need to resolve your types if you
+    only use them for static type checking.
 
     With no arguments, names will be looked up in the module in which the class
     was created. If this is not what you want, for example, if the name only
diff --git a/src/attr/_make.py b/src/attr/_make.py
@@ -2784,7 +2784,7 @@ def evolve(self, **changes):
         Copy *self* and apply *changes*.
 
         This works similarly to `attrs.evolve` but that function does not work
-        with `Attribute`.
+        with {class}`Attribute`.
 
         It is mainly meant to be used for `transform-fields`.
 
@@ -3078,8 +3078,8 @@ class Converter:
             as a positional argument. (default: `False`)
 
         takes_field (bool):
-            Pass the field definition (an `Attribute`) into the converter as a
-            positional argument. (default: `False`)
+            Pass the field definition (an :class:`Attribute`) into the
+            converter as a positional argument. (default: `False`)
 
     .. versionadded:: 24.1.0
     """
