From 39833f70b916d5b615f999c0e6304c90462dbb39 Mon Sep 17 00:00:00 2001
From: Stein Magnus Jodal <stein.magnus@jodal.no>
Date: Thu, 16 Nov 2023 02:56:38 +0100
Subject: [PATCH] Improve API docs

---
 docs/api.rst                          | 15 +++++++++------
 src/brreg/enhetsregisteret/_client.py | 24 ++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 464f786..d3ce78d 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -24,24 +24,27 @@ Enhetsregisteret
 
 .. autoclass:: brreg.enhetsregisteret.Client
    :members:
-   :undoc-members:
 
 .. autoclass:: brreg.enhetsregisteret.Enhet
    :members:
-   :undoc-members:
+   :exclude-members: model_config, model_fields
+
+.. autoclass:: brreg.enhetsregisteret.Underenhet
+   :members:
+   :exclude-members: model_config, model_fields
 
 .. autoclass:: brreg.enhetsregisteret.Adresse
    :members:
-   :undoc-members:
+   :exclude-members: model_config, model_fields
 
 .. autoclass:: brreg.enhetsregisteret.InstitusjonellSektorkode
    :members:
-   :undoc-members:
+   :exclude-members: model_config, model_fields
 
 .. autoclass:: brreg.enhetsregisteret.Naeringskode
    :members:
-   :undoc-members:
+   :exclude-members: model_config, model_fields
 
 .. autoclass:: brreg.enhetsregisteret.Organisasjonsform
    :members:
-   :undoc-members:
+   :exclude-members: model_config, model_fields
diff --git a/src/brreg/enhetsregisteret/_client.py b/src/brreg/enhetsregisteret/_client.py
index e084dcb..bae1b79 100644
--- a/src/brreg/enhetsregisteret/_client.py
+++ b/src/brreg/enhetsregisteret/_client.py
@@ -29,6 +29,22 @@ def error_handler() -> Generator[None, Any, None]:
 
 
 class Client:
+    """Client for the Enhetregisteret API.
+
+    Ensures that HTTP connections are reused across requests.
+
+    It can be used as a context manager::
+
+        with Client() as client:
+            enhet = client.get_enhet("915501680")
+
+    Or by manually opening and closing the client::
+
+        client = Client()
+        enhet = client.get_enhet("915501680")
+        client.close()
+    """
+
     _client: httpx.Client
 
     def __init__(self) -> None:
@@ -46,11 +62,19 @@ def __exit__(
         self.close()
 
     def open(self) -> None:
+        """Prepare the client for use.
+
+        This is called automatically when the client is created.
+        """
         self._client = httpx.Client(
             base_url="https://data.brreg.no/enhetsregisteret/api",
         )
 
     def close(self) -> None:
+        """Close the client and any open HTTP connections.
+
+        This is called automatically if the client is used as a context manager.
+        """
         self._client.close()
 
     def get_enhet(self, organisasjonsnummer: str) -> Optional[Enhet]: