reflow comments in modules/[mediasource,plugins]

third_party/WebKit/Source/modules/mediasource/MediaSource.cpp

 /*
  * Copyright (C) 2013 Google Inc. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
  * met:
  *
  *     * Redistributions of source code must retain the above copyright
  * notice, this list of conditions and the following disclaimer.
  *     * Redistributions in binary form must reproduce the above
@@ skipping 132 matching lines @@
 void MediaSource::logAndThrowTypeError(ExceptionState& exceptionState,
                                        const String& message) {
   BLINK_MSLOG << __func__ << " (message=" << message << ")";
   exceptionState.throwTypeError(message);
 }
 
 SourceBuffer* MediaSource::addSourceBuffer(const String& type,
                                            ExceptionState& exceptionState) {
   BLINK_MSLOG << __func__ << " this=" << this << " type=" << type;
 
-  // 2.2 https://www.w3.org/TR/media-source/#widl-MediaSource-addSourceBuffer-SourceBuffer-DOMString-type/
+  // 2.2
+  // https://www.w3.org/TR/media-source/#widl-MediaSource-addSourceBuffer-SourceBuffer-DOMString-type/

[dcheng, 2016/10/04 21:45:52]

This formatting is unfortunate (maybe put the section number after the URL? I
don't have a great idea here). I'm not sure if it would help to say "Section 2.2
of"

   // 1. If type is an empty string then throw a TypeError exception
-  // and abort these steps.
+  //    and abort these steps.
   if (type.isEmpty()) {
     logAndThrowTypeError(exceptionState, "The type provided is empty");
     return 0;
   }
 
   // 2. If type contains a MIME type that is not supported ..., then throw a
   // NotSupportedError exception and abort these steps.
   if (!isTypeSupported(type)) {
     logAndThrowDOMException(
         exceptionState, NotSupportedError,
@@ skipping 11 matching lines @@
 
   // 5. Create a new SourceBuffer object and associated resources.
   ContentType contentType(type);
   String codecs = contentType.parameter("codecs");
   std::unique_ptr<WebSourceBuffer> webSourceBuffer =
       createWebSourceBuffer(contentType.type(), codecs, exceptionState);
 
   if (!webSourceBuffer) {
     DCHECK(exceptionState.code() == NotSupportedError ||
            exceptionState.code() == QuotaExceededError);
-    // 2. If type contains a MIME type that is not supported ..., then throw a NotSupportedError exception and abort these steps.
-    // 3. If the user agent can't handle any more SourceBuffer objects then throw a QuotaExceededError exception and abort these steps
+    // 2. If type contains a MIME type that is not supported ..., then throw a
+    //    NotSupportedError exception and abort these steps.
+    // 3. If the user agent can't handle any more SourceBuffer objects then
+    //    throw a QuotaExceededError exception and abort these steps
     return 0;
   }
 
   SourceBuffer* buffer = SourceBuffer::create(std::move(webSourceBuffer), this,
                                               m_asyncEventQueue.get());
-  // 6. Add the new object to sourceBuffers and fire a addsourcebuffer on that object.
+  // 6. Add the new object to sourceBuffers and fire a addsourcebuffer on that
+  //    object.
   m_sourceBuffers->add(buffer);
 
   // 7. Return the new object to the caller.
   BLINK_MSLOG << __func__ << " this=" << this << " type=" << type << " -> "
               << buffer;
   return buffer;
 }
 
 void MediaSource::removeSourceBuffer(SourceBuffer* buffer,
                                      ExceptionState& exceptionState) {
   BLINK_MSLOG << __func__ << " this=" << this << " buffer=" << buffer;
 
-  // 2.2 https://dvcs.w3.org/hg/html-media/raw-file/default/media-source/media-source.html#widl-MediaSource-removeSourceBuffer-void-SourceBuffer-sourceBuffer
+  // 2.2

[dcheng, 2016/10/04 21:45:52]

Similarly here and elsewhere.

+  // https://dvcs.w3.org/hg/html-media/raw-file/default/media-source/media-source.html#widl-MediaSource-removeSourceBuffer-void-SourceBuffer-sourceBuffer
 
   // 1. If sourceBuffer specifies an object that is not in sourceBuffers then
-  // throw a NotFoundError exception and abort these steps.
+  //    throw a NotFoundError exception and abort these steps.
   if (!m_sourceBuffers->length() || !m_sourceBuffers->contains(buffer)) {
     logAndThrowDOMException(
         exceptionState, NotFoundError,
         "The SourceBuffer provided is not contained in this MediaSource.");
     return;
   }
 
   // Steps 2-8 are implemented by SourceBuffer::removedFromMediaSource.
   buffer->removedFromMediaSource();
 
-  // 9. If sourceBuffer is in activeSourceBuffers, then remove sourceBuffer from activeSourceBuffers ...
+  // 9. If sourceBuffer is in activeSourceBuffers, then remove sourceBuffer from
+  //    activeSourceBuffers ...
   m_activeSourceBuffers->remove(buffer);
 
-  // 10. Remove sourceBuffer from sourceBuffers and fire a removesourcebuffer event
-  // on that object.
+  // 10. Remove sourceBuffer from sourceBuffers and fire a removesourcebuffer
+  //     event on that object.
   m_sourceBuffers->remove(buffer);
 
   // 11. Destroy all resources for sourceBuffer.
-  // This should have been done already by SourceBuffer::removedFromMediaSource (steps 2-8) above.
+  //     This should have been done already by
+  //     SourceBuffer::removedFromMediaSource (steps 2-8) above.
 }
 
 void MediaSource::onReadyStateChange(const AtomicString& oldState,
                                      const AtomicString& newState) {
   if (isOpen()) {
     scheduleEvent(EventTypeNames::sourceopen);
     return;
   }
 
   if (oldState == openKeyword() && newState == endedKeyword()) {
@@ skipping 36 matching lines @@
 
   ContentType contentType(type);
   String codecs = contentType.parameter("codecs");
 
   // 2. If type does not contain a valid MIME type string, then return false.
   if (contentType.type().isEmpty()) {
     BLINK_MSLOG << __func__ << "(" << type << ") -> false (invalid mime type)";
     return false;
   }
 
-  // Note: MediaSource.isTypeSupported() returning true implies that HTMLMediaElement.canPlayType() will return "maybe" or "probably"
-  // since it does not make sense for a MediaSource to support a type the HTMLMediaElement knows it cannot play.
+  // Note: MediaSource.isTypeSupported() returning true implies that
+  // HTMLMediaElement.canPlayType() will return "maybe" or "probably" since it
+  // does not make sense for a MediaSource to support a type the
+  // HTMLMediaElement knows it cannot play.
   if (HTMLMediaElement::supportsType(contentType) ==
       WebMimeRegistry::IsNotSupported) {
     BLINK_MSLOG << __func__ << "(" << type
                 << ") -> false (not supported by HTMLMediaElement)";
     return false;
   }
 
-  // 3. If type contains a media type or media subtype that the MediaSource does not support, then return false.
-  // 4. If type contains at a codec that the MediaSource does not support, then return false.
-  // 5. If the MediaSource does not support the specified combination of media type, media subtype, and codecs then return false.
+  // 3. If type contains a media type or media subtype that the MediaSource does
+  //    not support, then return false.
+  // 4. If type contains at a codec that the MediaSource does not support, then
+  //    return false.
+  // 5. If the MediaSource does not support the specified combination of media
+  //    type, media subtype, and codecs then return false.
   // 6. Return true.
   bool result = MIMETypeRegistry::isSupportedMediaSourceMIMEType(
       contentType.type(), codecs);
   BLINK_MSLOG << __func__ << "(" << type << ") -> "
               << (result ? "true" : "false");
   return result;
 }
 
 const AtomicString& MediaSource::interfaceName() const {
   return EventTargetNames::MediaSource;
@@ skipping 39 matching lines @@
                     : m_webMediaSource->duration();
 }
 
 TimeRanges* MediaSource::buffered() const {
   // Implements MediaSource algorithm for HTMLMediaElement.buffered.
   // https://dvcs.w3.org/hg/html-media/raw-file/default/media-source/media-source.html#htmlmediaelement-extensions
   HeapVector<Member<TimeRanges>> ranges(m_activeSourceBuffers->length());
   for (size_t i = 0; i < m_activeSourceBuffers->length(); ++i)
     ranges[i] = m_activeSourceBuffers->item(i)->buffered(ASSERT_NO_EXCEPTION);
 
-  // 1. If activeSourceBuffers.length equals 0 then return an empty TimeRanges object and abort these steps.
+  // 1. If activeSourceBuffers.length equals 0 then return an empty TimeRanges
+  //    object and abort these steps.
   if (ranges.isEmpty())
     return TimeRanges::create();
 
-  // 2. Let active ranges be the ranges returned by buffered for each SourceBuffer object in activeSourceBuffers.
+  // 2. Let active ranges be the ranges returned by buffered for each
+  //    SourceBuffer object in activeSourceBuffers.
   // 3. Let highest end time be the largest range end time in the active ranges.
   double highestEndTime = -1;
   for (size_t i = 0; i < ranges.size(); ++i) {
     unsigned length = ranges[i]->length();
     if (length)
       highestEndTime = std::max(
           highestEndTime, ranges[i]->end(length - 1, ASSERT_NO_EXCEPTION));
   }
 
   // Return an empty range if all ranges are empty.
   if (highestEndTime < 0)
     return TimeRanges::create();
 
-  // 4. Let intersection ranges equal a TimeRange object containing a single range from 0 to highest end time.
+  // 4. Let intersection ranges equal a TimeRange object containing a single
+  //    range from 0 to highest end time.
   TimeRanges* intersectionRanges = TimeRanges::create(0, highestEndTime);
 
-  // 5. For each SourceBuffer object in activeSourceBuffers run the following steps:
+  // 5. For each SourceBuffer object in activeSourceBuffers run the following
+  //    steps:
   bool ended = readyState() == endedKeyword();
   for (size_t i = 0; i < ranges.size(); ++i) {
-    // 5.1 Let source ranges equal the ranges returned by the buffered attribute on the current SourceBuffer.
+    // 5.1 Let source ranges equal the ranges returned by the buffered attribute
+    //     on the current SourceBuffer.
     TimeRanges* sourceRanges = ranges[i].get();
 
-    // 5.2 If readyState is "ended", then set the end time on the last range in source ranges to highest end time.
+    // 5.2 If readyState is "ended", then set the end time on the last range in
+    //     source ranges to highest end time.
     if (ended && sourceRanges->length())
       sourceRanges->add(
           sourceRanges->start(sourceRanges->length() - 1, ASSERT_NO_EXCEPTION),
           highestEndTime);
 
-    // 5.3 Let new intersection ranges equal the the intersection between the intersection ranges and the source ranges.
-    // 5.4 Replace the ranges in intersection ranges with the new intersection ranges.
+    // 5.3 Let new intersection ranges equal the the intersection between the
+    //     intersection ranges and the source ranges.
+    // 5.4 Replace the ranges in intersection ranges with the new intersection
+    //     ranges.
     intersectionRanges->intersectWith(sourceRanges);
   }
 
   return intersectionRanges;
 }
 
 TimeRanges* MediaSource::seekable() const {
   // Implements MediaSource algorithm for HTMLMediaElement.seekable.
   // http://w3c.github.io/media-source/#htmlmediaelement-extensions
 
@@ skipping 18 matching lines @@
             m_liveSeekableRange->start(0, ASSERT_NO_EXCEPTION),
             m_liveSeekableRange->end(0, ASSERT_NO_EXCEPTION));
       }
 
       return TimeRanges::create(
           std::min(m_liveSeekableRange->start(0, ASSERT_NO_EXCEPTION),
                    buffered->start(0, ASSERT_NO_EXCEPTION)),
           std::max(m_liveSeekableRange->end(0, ASSERT_NO_EXCEPTION),
                    buffered->end(buffered->length() - 1, ASSERT_NO_EXCEPTION)));
     }
-    // 2. If the HTMLMediaElement.buffered attribute returns an empty TimeRanges object, then
-    //    return an empty TimeRanges object and abort these steps.
+    // 2. If the HTMLMediaElement.buffered attribute returns an empty TimeRanges
+    //    object, then return an empty TimeRanges object and abort these steps.
     if (buffered->length() == 0)
       return TimeRanges::create();
 
-    // 3. Return a single range with a start time of 0 and an end time equal to the highest end
-    //    time reported by the HTMLMediaElement.buffered attribute.
+    // 3. Return a single range with a start time of 0 and an end time equal to
+    //    the highest end time reported by the HTMLMediaElement.buffered
+    //    attribute.
     return TimeRanges::create(
         0, buffered->end(buffered->length() - 1, ASSERT_NO_EXCEPTION));
   }
 
-  // 3. Otherwise: Return a single range with a start time of 0 and an end time equal to duration.
+  // 3. Otherwise: Return a single range with a start time of 0 and an end time
+  //    equal to duration.
   return TimeRanges::create(0, sourceDuration);
 }
 
 void MediaSource::onTrackChanged(TrackBase* track) {
   DCHECK(RuntimeEnabledFeatures::audioVideoTracksEnabled());
   SourceBuffer* sourceBuffer =
       SourceBufferTrackBaseSupplement::sourceBuffer(*track);
   if (!sourceBuffer)
     return;
 
@@ skipping 20 matching lines @@
                                              duration, "duration"));
     return;
   }
   if (duration < 0.0) {
     logAndThrowTypeError(
         exceptionState,
         ExceptionMessages::indexExceedsMinimumBound("duration", duration, 0.0));
     return;
   }
 
-  // 2. If the readyState attribute is not "open" then throw an InvalidStateError
-  // exception and abort these steps.
-  // 3. If the updating attribute equals true on any SourceBuffer in sourceBuffers,
-  // then throw an InvalidStateError exception and abort these steps.
+  // 2. If the readyState attribute is not "open" then throw an
+  //    InvalidStateError exception and abort these steps.
+  // 3. If the updating attribute equals true on any SourceBuffer in
+  //    sourceBuffers, then throw an InvalidStateError exception and abort these
+  //    steps.
   if (throwExceptionIfClosedOrUpdating(isOpen(), isUpdating(), exceptionState))
     return;
 
-  // 4. Run the duration change algorithm with new duration set to the value being
-  // assigned to this attribute.
+  // 4. Run the duration change algorithm with new duration set to the value
+  //    being assigned to this attribute.
   durationChangeAlgorithm(duration, exceptionState);
 }
 
 void MediaSource::durationChangeAlgorithm(double newDuration,
                                           ExceptionState& exceptionState) {
   // http://w3c.github.io/media-source/#duration-change-algorithm
   // 1. If the current value of duration is equal to new duration, then return.
   if (newDuration == duration())
     return;
 
@@ skipping 39 matching lines @@
   if (!RuntimeEnabledFeatures::mediaSourceNewAbortAndDurationEnabled() &&
       newDuration < oldDuration) {
     // Deprecated behavior: if the new duration is less than old duration,
     // then call remove(new duration, old duration) on all all objects in
     // sourceBuffers.
     for (size_t i = 0; i < m_sourceBuffers->length(); ++i)
       m_sourceBuffers->item(i)->remove(newDuration, oldDuration,
                                        ASSERT_NO_EXCEPTION);
   }
 
-  // 5. If a user agent is unable to partially render audio frames or text cues that start before and end after the duration, then run the following steps:
-  // NOTE: Currently we assume that the media engine is able to render partial frames/cues. If a media
-  // engine gets added that doesn't support this, then we'll need to add logic to handle the substeps.
+  // 5. If a user agent is unable to partially render audio frames or text cues
+  //    that start before and end after the duration, then run the following steps:
+  //    NOTE: Currently we assume that the media engine is able to render
+  //    partial frames/cues. If a media engine gets added that doesn't support
+  //    this, then we'll need to add logic to handle the substeps.
 
-  // 6. Update the media controller duration to new duration and run the HTMLMediaElement duration change algorithm.
+  // 6. Update the media controller duration to new duration and run the
+  //    HTMLMediaElement duration change algorithm.
   m_attachedElement->durationChanged(newDuration, requestSeek);
 }
 
 void MediaSource::setReadyState(const AtomicString& state) {
   DCHECK(state == openKeyword() || state == closedKeyword() ||
          state == endedKeyword());
 
   AtomicString oldState = readyState();
   BLINK_MSLOG << __func__ << " this=" << this << " : " << oldState << " -> "
               << state;
@@ skipping 75 matching lines @@
 
   // 3. If live seekable range contains a range, then set live seekable range
   //    to be a new empty TimeRanges object.
   if (m_liveSeekableRange->length() != 0)
     m_liveSeekableRange = TimeRanges::create();
 }
 
 void MediaSource::endOfStreamInternal(
     const WebMediaSource::EndOfStreamStatus eosStatus,
     ExceptionState& exceptionState) {
-  // 2.2 http://www.w3.org/TR/media-source/#widl-MediaSource-endOfStream-void-EndOfStreamError-error
+  // 2.2
+  // http://www.w3.org/TR/media-source/#widl-MediaSource-endOfStream-void-EndOfStreamError-error
   // 1. If the readyState attribute is not in the "open" state then throw an
-  // InvalidStateError exception and abort these steps.
-  // 2. If the updating attribute equals true on any SourceBuffer in sourceBuffers, then throw an
-  // InvalidStateError exception and abort these steps.
+  //    InvalidStateError exception and abort these steps.
+  // 2. If the updating attribute equals true on any SourceBuffer in
+  //    sourceBuffers, then throw an InvalidStateError exception and abort these
+  //    steps.
   if (throwExceptionIfClosedOrUpdating(isOpen(), isUpdating(), exceptionState))
     return;
 
   // 3. Run the end of stream algorithm with the error parameter set to error.
   //   1. Change the readyState attribute value to "ended".
-  //   2. Queue a task to fire a simple event named sourceended at the MediaSource.
+  //   2. Queue a task to fire a simple event named sourceended at the
+  //      MediaSource.
   setReadyState(endedKeyword());
 
   //   3. Do various steps based on |eosStatus|.
   m_webMediaSource->markEndOfStream(eosStatus);
 }
 
 bool MediaSource::isOpen() const {
   return readyState() == openKeyword();
 }
 
@@ skipping 74 matching lines @@
     const String& type,
     const String& codecs,
     ExceptionState& exceptionState) {
   WebSourceBuffer* webSourceBuffer = 0;
 
   switch (m_webMediaSource->addSourceBuffer(type, codecs, &webSourceBuffer)) {
     case WebMediaSource::AddStatusOk:
       return wrapUnique(webSourceBuffer);
     case WebMediaSource::AddStatusNotSupported:
       DCHECK(!webSourceBuffer);
-      // 2.2 https://dvcs.w3.org/hg/html-media/raw-file/default/media-source/media-source.html#widl-MediaSource-addSourceBuffer-SourceBuffer-DOMString-type
-      // Step 2: If type contains a MIME type ... that is not supported with the types
-      // specified for the other SourceBuffer objects in sourceBuffers, then throw
-      // a NotSupportedError exception and abort these steps.
+      // 2.2
+      // https://dvcs.w3.org/hg/html-media/raw-file/default/media-source/media-source.html#widl-MediaSource-addSourceBuffer-SourceBuffer-DOMString-type
+      // Step 2: If type contains a MIME type ... that is not supported with the
+      // types specified for the other SourceBuffer objects in sourceBuffers,
+      // then throw a NotSupportedError exception and abort these steps.
       logAndThrowDOMException(
           exceptionState, NotSupportedError,
           "The type provided ('" + type + "') is not supported.");
       return nullptr;
     case WebMediaSource::AddStatusReachedIdLimit:
       DCHECK(!webSourceBuffer);
-      // 2.2 https://dvcs.w3.org/hg/html-media/raw-file/default/media-source/media-source.html#widl-MediaSource-addSourceBuffer-SourceBuffer-DOMString-type
-      // Step 3: If the user agent can't handle any more SourceBuffer objects then throw
-      // a QuotaExceededError exception and abort these steps.
+      // 2.2
+      // https://dvcs.w3.org/hg/html-media/raw-file/default/media-source/media-source.html#widl-MediaSource-addSourceBuffer-SourceBuffer-DOMString-type
+      // Step 3: If the user agent can't handle any more SourceBuffer objects
+      // then throw a QuotaExceededError exception and abort these steps.
       logAndThrowDOMException(exceptionState, QuotaExceededError,
                               "This MediaSource has reached the limit of "
                               "SourceBuffer objects it can handle. No "
                               "additional SourceBuffer objects may be added.");
       return nullptr;
   }
 
   NOTREACHED();
   return nullptr;
 }
 
 void MediaSource::scheduleEvent(const AtomicString& eventName) {
   DCHECK(m_asyncEventQueue);
 
   Event* event = Event::create(eventName);
   event->setTarget(this);
 
   m_asyncEventQueue->enqueueEvent(event);
 }
 
 URLRegistry& MediaSource::registry() const {
   return MediaSourceRegistry::registry();
 }
 
 }  // namespace blink