From 54755542215fddf04b60402db405a19dd1b2789e Mon Sep 17 00:00:00 2001
From: Charlie Denton <charlie@meshy.co.uk>
Date: Tue, 13 Feb 2024 10:08:04 +0000
Subject: [PATCH] Expand docstrings with details of their API

These functions now go into details about the arguments they take, the
errors they may raise, and the data they return.
---
 src/django_integrity/constraints.py | 39 +++++++++++++++++++++++++++++
 src/django_integrity/conversion.py  | 16 ++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/src/django_integrity/constraints.py b/src/django_integrity/constraints.py
index c8c9320..622ac5a 100644
--- a/src/django_integrity/constraints.py
+++ b/src/django_integrity/constraints.py
@@ -54,6 +54,13 @@ def immediate(names: Sequence[str], *, using: str) -> Iterator[None]:
     create and close (or roll back) a savepoint, and set and unset the constraint state.
 
     # See Note [Deferrable constraints]
+
+    Args:
+        names: The names of the constraints to change.
+        using: The name of the database connection to use.
+
+    Raises:
+        NotInTransaction: When we try to change constraints outside of a transaction.
     """
     set_immediate(names, using=using)
     try:
@@ -68,6 +75,12 @@ def set_all_immediate(*, using: str) -> None:
     Set all constraints to IMMEDIATE for the remainder of the transaction.
 
     # See Note [Deferrable constraints]
+
+    Args:
+        using: The name of the database connection to use.
+
+    Raises:
+        NotInTransaction: When we try to change constraints outside of a transaction.
     """
     if django_db.transaction.get_autocommit(using):
         raise NotInTransaction
@@ -81,6 +94,13 @@ def set_immediate(names: Sequence[str], *, using: str) -> None:
     Set particular constraints to IMMEDIATE for the remainder of the transaction.
 
     # See Note [Deferrable constraints]
+
+    Args:
+        names: The names of the constraints to set to IMMEDIATE.
+        using: The name of the database connection to use.
+
+    Raises:
+        NotInTransaction: When we try to change constraints outside of a transaction.
     """
     if django_db.transaction.get_autocommit(using):
         raise NotInTransaction
@@ -101,6 +121,13 @@ def set_deferred(names: Sequence[str], *, using: str) -> None:
     Set particular constraints to DEFERRED for the remainder of the transaction.
 
     # See Note [Deferrable constraints]
+
+    Args:
+        names: The names of the constraints to set to DEFERRED.
+        using: The name of the database connection to use.
+
+    Raises:
+        NotInTransaction: When we try to change constraints outside of a transaction.
     """
     if django_db.transaction.get_autocommit(using):
         raise NotInTransaction
@@ -140,6 +167,18 @@ def foreign_key_constraint_name(
     This means that the constraint name is not deterministic based on the model and field alone.
 
     Django surely ought to have a public method for this, but it doesn't!
+
+    Args:
+        model: The model that contains the field.
+        field_name: The name of the field.
+        using: The name of the database connection to use.
+
+    Raises:
+        django.core.exceptions.FieldDoesNotExist: When the field is not on the model.
+        NotAForeignKey: When the field is not a foreign key.
+
+    Returns:
+        The name of the foreign key constraint.
     """
     field = model._meta.get_field(field_name)
 
diff --git a/src/django_integrity/conversion.py b/src/django_integrity/conversion.py
index 89193e7..ae44434 100644
--- a/src/django_integrity/conversion.py
+++ b/src/django_integrity/conversion.py
@@ -16,6 +16,13 @@ def refine_integrity_error(rules: Mapping[_Rule, Exception]) -> Iterator[None]:
     Convert a generic IntegrityError into a more specific exception.
 
     The conversion is based on a mapping of rules to exceptions.
+
+    Args:
+        rules: A mapping of rules to the exceptions we'll raise if they match.
+
+    Raises:
+        An error from the rules mapping if an IntegrityError matches a rule.
+        Otherwise, the original IntegrityError.
     """
     try:
         yield
@@ -29,6 +36,15 @@ def refine_integrity_error(rules: Mapping[_Rule, Exception]) -> Iterator[None]:
 class _Rule(abc.ABC):
     @abc.abstractmethod
     def is_match(self, error: django_db.IntegrityError) -> bool:
+        """
+        Determine if the rule matches the given IntegrityError.
+
+        Args:
+            error: The IntegrityError to check.
+
+        Returns:
+            True if the rule matches the error, False otherwise.
+        """
         ...