Bug 1319992: P2. Update MediaDecoderReader documentation. r=jwwang

Remove all no longer relevant information.

MozReview-Commit-ID: 89HB0Pk1XoI

--HG--
extra : rebase_source : ca1676a82ea3ed6df7f22c20d6cb5f36a9682897

dom/media/MediaDecoderReader.h

@@ -54,7 +54,7 @@ private:
 // Encapsulates the decoding and reading of media data. Reading can either
 // synchronous and done on the calling "decode" thread, or asynchronous and
 // performed on a background thread, with the result being returned by
-// callback. Never hold the decoder monitor when calling into this class.
+// callback.
 // Unless otherwise specified, methods and fields of this class can only
 // be accessed on the decode task queue.
 class MediaDecoderReader {
@@ -114,10 +114,6 @@ public:
   //
   // Normally this call preceedes a Seek() call, or shutdown.
   //
-  // The first samples of every stream produced after a ResetDecode() call
-  // *must* be marked as "discontinuities". If it's not, seeking work won't
-  // properly!
-  //
   // aParam is a set of TrackInfo::TrackType enums specifying which
   // queues need to be reset, defaulting to both audio and video tracks.
   virtual nsresult ResetDecode(TrackSet aTracks = TrackSet(TrackInfo::kAudioTrack,
@@ -126,15 +122,11 @@ public:
   // Requests one audio sample from the reader.
   //
   // The decode should be performed asynchronously, and the promise should
-  // be resolved when it is complete. Don't hold the decoder
-  // monitor while calling this, as the implementation may try to wait
-  // on something that needs the monitor and deadlock.
+  // be resolved when it is complete.
   virtual RefPtr<MediaDataPromise> RequestAudioData();
 
   // Requests one video sample from the reader.
   //
-  // Don't hold the decoder monitor while calling this, as the implementation
-  // may try to wait on something that needs the monitor and deadlock.
   // If aSkipToKeyframe is true, the decode should skip ahead to the
   // the next keyframe at or after aTimeThreshold microseconds.
   virtual RefPtr<MediaDataPromise>
@@ -194,6 +186,8 @@ public:
   virtual size_t SizeOfVideoQueueInFrames();
   virtual size_t SizeOfAudioQueueInFrames();
 
+  // Called once new data has been cached by the MediaResource.
+  // mBuffered should be recalculated and updated accordingly.
   virtual void NotifyDataArrived()
   {
     MOZ_ASSERT(OnTaskQueue());
@@ -345,22 +339,13 @@ private:
     return false;
   }
 
-  // Populates aBuffered with the time ranges which are buffered. This may only
-  // be called on the decode task queue, and should only be used internally by
-  // UpdateBuffered - mBuffered (or mirrors of it) should be used for everything
-  // else.
+  // GetBuffered estimates the time ranges buffered by interpolating the cached
+  // byte ranges with the duration of the media. Reader subclasses should
+  // override this method if they can quickly calculate the buffered ranges more
+  // accurately.
   //
-  // This base implementation in MediaDecoderReader estimates the time ranges
-  // buffered by interpolating the cached byte ranges with the duration
-  // of the media. Reader subclasses should override this method if they
-  // can quickly calculate the buffered ranges more accurately.
-  //
-  // The primary advantage of this implementation in the reader base class
-  // is that it's a fast approximation, which does not perform any I/O.
-  //
-  // The OggReader relies on this base implementation not performing I/O,
-  // since in FirefoxOS we can't do I/O on the main thread, where this is
-  // called.
+  // The primary advantage of this implementation in the reader base class is
+  // that it's a fast approximation, which does not perform any I/O.
   media::TimeIntervals GetBuffered();
 
   // Promises used only for the base-class (sync->async adapter) implementation