document IP trunk product block

gso/products/product_blocks/iptrunk.py

+"""IP trunk product block that has all parameters of a subscription throughout its lifecycle."""
+
 import ipaddress
 from typing import Optional
 
@@ -9,13 +11,15 @@ from gso.products.product_blocks.device import DeviceBlock, DeviceBlockInactive,
 
 
 class IptrunkType(strEnum):
-    Dark_fiber = "Dark_fiber"
-    Leased = "Leased"
+    DARK_FIBER = "Dark_fiber"
+    LEASED = "Leased"
 
 
 class IptrunkBlockInactive(
     ProductBlockModel, lifecycle=[SubscriptionLifecycle.INITIAL], product_block_name="IptrunkBlock"
 ):
+    """A trunk that's currently inactive, see {class}`IptrunkBlock`."""
+
     geant_s_sid: Optional[str] = None
     iptrunk_description: Optional[str] = None
     iptrunk_type: Optional[IptrunkType] = None
@@ -39,6 +43,8 @@ class IptrunkBlockInactive(
 
 
 class IptrunkBlockProvisioning(IptrunkBlockInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
+    """A trunk that's currently being provisioned, see {class}`IptrunkBlock`."""
+
     geant_s_sid: Optional[str] = None
     iptrunk_description: Optional[str] = None
     iptrunk_type: Optional[IptrunkType] = None
@@ -62,22 +68,39 @@ class IptrunkBlockProvisioning(IptrunkBlockInactive, lifecycle=[SubscriptionLife
 
 
 class IptrunkBlock(IptrunkBlockProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE]):
+    """A trunk that's currently deployed in the network."""
+
     geant_s_sid: str
+    """GÉANT service ID associated with this trunk. """
     iptrunk_description: str
+    """A human-readable description of this trunk."""
     iptrunk_type: IptrunkType
-    iptrunk_speed: str
+    """The type of trunk, can be either dark fibre or leased capacity."""
+    iptrunk_speed: str  # FIXME: should be of PhyPortCapacity type
+    """The speed of the trunk, measured per interface associated with it."""
     iptrunk_minimum_links: int
+    """The minimum amount of links the trunk should consist of."""
     iptrunk_isis_metric: int
+    """The {term}`IS-IS` metric of this link"""
     iptrunk_ipv4_network: ipaddress.IPv4Network
+    """The IPv4 network used for this trunk."""
     iptrunk_ipv6_network: ipaddress.IPv6Network
+    """The IPv6 network used for this trunk."""
     #
     iptrunk_sideA_node: DeviceBlock
+    """The router that hosts the A side of the trunk."""
     iptrunk_sideA_ae_iface: str
+    """The name of the interface on which the trunk connects."""
     iptrunk_sideA_ae_geant_a_sid: str
+    """The service ID of the interface."""
     iptrunk_sideA_ae_members: list[str] = Field(default_factory=list)
+    """A list of interface members that make up the aggregated Ethernet interface."""
     iptrunk_sideA_ae_members_description: list[str] = Field(default_factory=list)
+    """The list of descriptions that describe the list of interface members."""
     #
     iptrunk_sideB_node: DeviceBlock
+    """The router that hosts the B side of the trunk. It possesses the same attributes as the A-side, including the
+    interfaces and its descriptions."""
     iptrunk_sideB_ae_iface: str
     iptrunk_sideB_ae_geant_a_sid: str
     iptrunk_sideB_ae_members: list[str] = Field(default_factory=list)