Add doc block clarification (fixes #368)

src/media-sink.ts

@@ -1821,6 +1821,9 @@ export class VideoSampleSink extends BaseMediaSampleSink<VideoSample> {
 	 * once, and is therefore more efficient than manually getting the sample for every timestamp. The iterator may
 	 * yield null if no frame is available for a given timestamp.
 	 *
+	 * This method is good for sparse access of media data. If you want primarily sequential media access, prefer
+	 * {@link VideoSampleSink.samples} instead.
+	 *
 	 * @param timestamps - An iterable or async iterable of timestamps in seconds.
 	 * @param options - Options used for the underlying packet retrieval.
 	 */
@@ -2120,6 +2123,9 @@ export class CanvasSink {
 	 * therefore more efficient than manually getting the canvas for every timestamp. The iterator may yield null if
 	 * no frame is available for a given timestamp.
 	 *
+	 * This method is good for sparse access of media data. If you want primarily sequential media access, prefer
+	 * {@link CanvasSink.samples} instead.
+	 *
 	 * @param timestamps - An iterable or async iterable of timestamps in seconds.
 	 * @param options - Options used for the underlying packet retrieval.
 	 */
@@ -2523,6 +2529,9 @@ export class AudioSampleSink extends BaseMediaSampleSink<AudioSample> {
 	 * once, and is therefore more efficient than manually getting the sample for every timestamp. The iterator may
 	 * yield null if no sample is available for a given timestamp.
 	 *
+	 * This method is good for sparse access of media data. If you want primarily sequential media access, prefer
+	 * {@link AudioSampleSink.samples} instead.
+	 *
 	 * @param timestamps - An iterable or async iterable of timestamps in seconds.
 	 * @param options - Options used for the underlying packet retrieval.
 	 */