modify docstrings

Author: Molly Xu

src/torchcodec/_core/_metadata.py

@@ -40,10 +40,18 @@ class StreamMetadata:
 
     # Computed fields (computed in C++ with fallback logic)
     duration_seconds: Optional[float]
-    """Duration of the stream in seconds. Tries to calculate from content
-    if :term:`scan` was performed, otherwise falls back to header values."""
+    """Duration of the stream in seconds. We try to calculate the duration
+    from the actual frames if a :term:`scan` was performed. Otherwise we
+    fall back to ``duration_seconds_from_header``. If that value is also None,
+    we instead calculate the duration from ``num_frames_from_header`` and
+    ``average_fps_from_header``.
+    """
     begin_stream_seconds: Optional[float]
-    """Beginning of the stream, in seconds."""
+    """Beginning of the stream, in seconds (float). Conceptually, this
+    corresponds to the first frame's :term:`pts`. If a :term:`scan` was performed
+    and ``begin_stream_seconds_from_content`` is not None, then it is returned.
+    Otherwise, this value is 0.
+    """
 
     def __repr__(self):
         s = self.__class__.__name__ + ":\n"
@@ -97,15 +105,21 @@ class VideoStreamMetadata(StreamMetadata):
     # Computed fields (computed in C++ with fallback logic)
     end_stream_seconds: Optional[float]
     """End of the stream, in seconds (float or None).
-    Conceptually, this corresponds to last_frame.pts + last_frame.duration."""
+    Conceptually, this corresponds to last_frame.pts + last_frame.duration.
+    If :term:`scan` was performed and``end_stream_seconds_from_content`` is not None, then that value is
+    returned. Otherwise, returns ``duration_seconds``.
+    """
     num_frames: Optional[int]
     """Number of frames in the stream (int or None).
-    Uses content if :term:`scan` was performed,
-    otherwise falls back to header values or calculates from duration and fps."""
+    This corresponds to ``num_frames_from_content`` if a :term:`scan` was made,
+    otherwise it corresponds to ``num_frames_from_header``. If that value is also
+    None, the number of frames is calculated from the duration and the average fps.
+    """
     average_fps: Optional[float]
-    """Average fps of the stream (float or None).
-    if :term:`scan` was performed, computes from
-    num_frames and duration, otherwise uses header value."""
+    """Average fps of the stream. If a :term:`scan` was perfomed, this is
+    computed from the number of frames and the duration of the stream.
+    Otherwise we fall back to ``average_fps_from_header``.
+    """
 
     def __repr__(self):
         return super().__repr__()