readable_ifc_duration - add doc-string and note

src/ifcopenshell-python/ifcopenshell/util/date.py

@@ -70,7 +70,18 @@ def ifc2datetime(element: Union[str, int, ifcopenshell.entity_instance]):
         )
 
 
-def readable_ifc_duration(duration):
+def readable_ifc_duration(duration: str) -> str:
+    """Convert ISO duration to more readable string format.
+
+    Examples:
+    - "P2Y3M1W4DT5H45M30S" -> "2 Y 3 M 1 W 4 D 5 h 45 m 30 s"
+    - "P2Y3MT30S" -> "2 Y 3 M 30 s"
+    - "PT2500H" -> "2500 h" (hours are not converted to days)
+    """
+    # NOTE: we don't use isodate.parseduration as it's going to
+    # represent "PT2500H" as "12w 6d 4h", though user may want
+    # intentionally to use just hours.
+
     if "T" in duration:
         period_duration, time_duration = duration.split("T")
         period_duration = period_duration[1:]
@@ -78,7 +89,7 @@ def readable_ifc_duration(duration):
         period_duration = duration[1:]
         time_duration = ""
 
-    result = []
+    result: list[str] = []
     for designator in ("Y", "M", "W", "D"):
         if designator in period_duration:
             value, period_duration = period_duration.split(designator)