More documentation for ModelSearch

shared/views/autocomplete.py

@@ -9,8 +9,23 @@ M = TypeVar("M", bound=Model)
 class ModelSearch(Generic[M]):
     """Basic search engine for models based on filtering.
 
-    Subclasses should override the ``model`` class attribute and specify the list of
-    search fields to be searched in.
+    As the type hints indicate, the class is generic with respect to the model. This
+    means that the ``search`` method only returns instances of the model specified as
+    the ``model`` class attribute in subclasses.
+
+    The ``search_fields`` attributes indicates which fields to search in during the
+    search.
+
+    Example:
+
+    >>> from django.contrib.auth.models import User
+    >>>
+    >>> class UserSearch(ModelSearch):
+    ...     model = User
+    ...     search_fields = ["username", "first_name", "last_name"]
+    >>>
+    >>> user_search = UserSearch()  # has type ModelSearch[User]
+    >>> user_search.search(["toto", "foo"])  # returns a queryset of Users
     """
 
     model: Type[M]