Document the structure of the Media controls DOM

Source/core/html/shadow/MediaControls.cpp

 /*
  * Copyright (C) 2011, 2012 Apple Inc. All rights reserved.
  * Copyright (C) 2011, 2012 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:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  * 2. Redistributions in binary form must reproduce the above copyright
@@ skipping 63 matching lines @@
 PassRefPtrWillBeRawPtr<MediaControls> MediaControls::create(HTMLMediaElement& mediaElement)
 {
     RefPtrWillBeRawPtr<MediaControls> controls = adoptRefWillBeNoop(new MediaControls(mediaElement));
 
     if (controls->initializeControls())
         return controls.release();
 
     return nullptr;
 }
 
+// The media controls DOM structure looks like:
+//
+// MediaControls                                       (-webkit-media-controls)
+// +-MediaControlOverlayEnclosureElement               (-webkit-media-controls-overlay-enclosure)
+// | +-MediaControlTextTrackContainerElement           (-webkit-media-text-track-container)
+// | | {when text tracks are enabled}
+// | +-MediaControlOverlayPlayButtonElement            (-webkit-media-controls-overlay-play-button)
+// | | {if mediaControlsOverlayPlayButtonEnabled}
+// | \-MediaControlCastButtonElement                   (-internal-media-controls-overlay-cast-button)
+// \-MediaControlPanelEnclosureElement                 (-webkit-media-controls-enclosure)
+//   \-MediaControlPanelElement                        (-webkit-media-controls-panel)
+//     +-MediaControlPlayButtonElement                 (-webkit-media-controls-play-button)
+//     +-MediaControlTimelineElement                   (-webkit-media-controls-timeline)
+//     +-MediaControlCurrentTimeDisplayElement         (-webkit-media-controls-current-time-display)
+//     +-MediaControlTimeRemainingDisplayElement       (-webkit-media-controls-time-remaining-display)
+//     +-MediaControlMuteButtonElement                 (-webkit-media-controls-mute-button)
+//     +-MediaControlVolumeSliderElement               (-webkit-media-controls-volume-slider)
+//     +-MediaControlToggleClosedCaptionsButtonElement (-webkit-media-controls-toggle-closed-captions-button)
+//     +-MediaControlCastButtonElement                 (-internal-media-controls-cast-button)
+//     \-MediaControlFullscreenButtonElement           (-webkit-media-controls-fullscreen-button)
+//
+// Most of the structure is built by MediaControls::initializeControls() - the
+// exception being MediaControlTextTrackContainerElement which is added
+// on-demand by MediaControls::createTextTrackDisplay().
 bool MediaControls::initializeControls()
 {
     TrackExceptionState exceptionState;
 
     RefPtrWillBeRawPtr<MediaControlOverlayEnclosureElement> overlayEnclosure = MediaControlOverlayEnclosureElement::create(*this);
 
     if (document().settings() && document().settings()->mediaControlsOverlayPlayButtonEnabled()) {
         RefPtrWillBeRawPtr<MediaControlOverlayPlayButtonElement> overlayPlayButton = MediaControlOverlayPlayButtonElement::create(*this);
         m_overlayPlayButton = overlayPlayButton.get();
         overlayEnclosure->appendChild(overlayPlayButton.release(), exceptionState);
@@ skipping 490 matching lines @@
     visitor->trace(m_toggleClosedCaptionsButton);
     visitor->trace(m_fullScreenButton);
     visitor->trace(m_durationDisplay);
     visitor->trace(m_enclosure);
     visitor->trace(m_castButton);
     visitor->trace(m_overlayCastButton);
     HTMLDivElement::trace(visitor);
 }
 
 }