refactor(ids-camera): add additional information to the docstrings

csaxs_bec/devices/ids_cameras/base_integration/camera.py

@@ -1,4 +1,16 @@
-"""This module provides a Camera class for handling IDS cameras using the pyueye  SDK library."""
+"""
+This module provides a Camera class for handling IDS cameras using the pyueye library,
+that links to the vendors C++ SDK. Details about the camera's C++ SDK API can be found
+in the IDS Software Suite 4.96.1 documentation:
+(https://www.1stvision.com/cameras/IDS/IDS-manuals/uEye_Manual/sdk_einleitung_schnellstart.html)
+
+Here, we follow a procedure to set up the camera, configure its basic parameters and
+allow automated capturing of images. The IDSCameraObject class is the low-level interface,
+and requires the pyueye library and appropriate DLL files on the system. The Camera class
+provides a high level interface which only creates the IDSCameraObject instance when the
+on_connect method is called. This allows for lazy initialization of the camera, and
+CI/CD pipelines can run without the pyueye library or the related DLLs installed on the system.
+"""
 
 from __future__ import annotations
 
@@ -20,7 +32,7 @@ except ImportError as exc:
 
 
 class IDSCameraObject:
-    """Base class for IDS Camera object.
+    """Low-level base class for IDS Camera object.
 
     Args:
         device_id (int): The ID of the camera device. # e.g. 201; check idscamera tool
@@ -137,7 +149,14 @@ class IDSCameraObject:
 
 
 class Camera:
-    """Camera base class for IDS cameras."""
+    """High level camera base class for IDS cameras.
+
+    Args:
+        camera_id (int): The ID of the camera device.
+        m_n_colormode (Literal[0, 1, 2, 3]): Color mode for the camera.
+        bits_per_pixel (Literal[8, 24]): Number of bits per pixel for the camera.
+        live_mode (bool): Whether to enable live mode for the camera.
+    """
 
     def __init__(
         self,