diff --git a/dom/media/MediaDecoderReader.h b/dom/media/MediaDecoderReader.h
index 05f62a54db73..c43cdb7c2fd1 100644
--- a/dom/media/MediaDecoderReader.h
+++ b/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.
+// callback. Never hold the decoder monitor when calling into this class.
 // Unless otherwise specified, methods and fields of this class can only
 // be accessed on the decode task queue.
 class MediaDecoderReader {
@@ -114,6 +114,10 @@ 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,
@@ -122,11 +126,15 @@ public:
   // Requests one audio sample from the reader.
   //
   // The decode should be performed asynchronously, and the promise should
-  // be resolved when it is complete.
+  // 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.
   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>
@@ -186,8 +194,6 @@ 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());
@@ -339,13 +345,22 @@ private:
     return false;
   }
 
-  // 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.
+  // 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.
   //
-  // 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.
+  // 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.
   media::TimeIntervals GetBuffered();
 
   // Promises used only for the base-class (sync->async adapter) implementation