docs: add Duration dtype docstring example (#1516)

* docs: add Duration dtype docstring example

* fix: address review comments from PR #1516

narwhals/dtypes.py

@@ -421,6 +421,24 @@ class Duration(TemporalType):
 
     Notes:
         Adapted from [Polars implementation](https://github.com/pola-rs/polars/blob/py-1.7.1/py-polars/polars/datatypes/classes.py#L460-L502)
+
+    Examples:
+        >>> import pandas as pd
+        >>> import polars as pl
+        >>> import pyarrow as pa
+        >>> import narwhals as nw
+        >>> from datetime import timedelta
+        >>> data = [timedelta(seconds=d) for d in range(1, 4)]
+        >>> ser_pd = pd.Series(data).astype("timedelta64[ms]")
+        >>> ser_pl = pl.Series(data).cast(pl.Duration("ms"))
+        >>> ser_pa = pa.chunked_array([data], type=pa.duration("ms"))
+
+        >>> nw.from_native(ser_pd, series_only=True).dtype
+        Duration(time_unit='ms')
+        >>> nw.from_native(ser_pl, series_only=True).dtype
+        Duration(time_unit='ms')
+        >>> nw.from_native(ser_pa, series_only=True).dtype
+        Duration(time_unit='ms')
     """
 
     def __init__(

narwhals/stable/v1/_dtypes.py

@@ -51,6 +51,24 @@ class Duration(NwDuration):
 
     Notes:
         Adapted from [Polars implementation](https://github.com/pola-rs/polars/blob/py-1.7.1/py-polars/polars/datatypes/classes.py#L460-L502)
+
+    Examples:
+        >>> import pandas as pd
+        >>> import polars as pl
+        >>> import pyarrow as pa
+        >>> import narwhals as nw
+        >>> from datetime import timedelta
+        >>> data = [timedelta(seconds=d) for d in range(1, 4)]
+        >>> ser_pd = pd.Series(data).astype("timedelta64[ms]")
+        >>> ser_pl = pl.Series(data).cast(pl.Duration("ms"))
+        >>> ser_pa = pa.chunked_array([data], type=pa.duration("ms"))
+
+        >>> nw.from_native(ser_pd, series_only=True).dtype
+        Duration(time_unit='ms')
+        >>> nw.from_native(ser_pl, series_only=True).dtype
+        Duration(time_unit='ms')
+        >>> nw.from_native(ser_pa, series_only=True).dtype
+        Duration(time_unit='ms')
     """
 
     def __hash__(self) -> int: