From 31576e6c0c1f3e23af554a0f810082671d303b6b Mon Sep 17 00:00:00 2001
From: Daryl Koopersmith <dkoopersmith@gmail.com>
Date: Mon, 19 Nov 2012 10:40:49 +0000
Subject: [PATCH] Media: Add documentation to media.Views. see #21390.

git-svn-id: http://core.svn.wordpress.org/trunk@22681 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/js/media-views.js | 70 +++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/wp-includes/js/media-views.js b/wp-includes/js/media-views.js
index 021ec1f709..da69d64222 100644
--- a/wp-includes/js/media-views.js
+++ b/wp-includes/js/media-views.js
@@ -574,15 +574,40 @@
 	media.Views.extend = Backbone.Model.extend;
 
 	_.extend( media.Views.prototype, {
+		// ### Fetch all of the subviews
+		//
+		// Returns an array of all subviews.
 		all: function() {
 			return _.flatten( this._views );
 		},
 
+		// ### Get a selector's subviews
+		//
+		// Fetches all subviews that match a given `selector`.
+		//
+		// If no `selector` is provided, it will grab all subviews attached
+		// to the view's root.
 		get: function( selector ) {
 			selector = selector || '';
 			return this._views[ selector ];
 		},
 
+		// ### Register subview(s)
+		//
+		// Registers any number of `views` to a `selector`.
+		//
+		// When no `selector` is provided, the root selector (the empty string)
+		// is used. `views` accepts a `Backbone.View` instance or an array of
+		// `Backbone.View` instances.
+		//
+		// Use `Views.add()` as a shortcut for setting `options.add` to `true`.
+		//
+		// Accepts an `options` object, which has a significant effect on the
+		// resulting behavior. By default, the provided `views` will replace
+		// any existing views associated with the selector. If `options.add`
+		// is set to `true`, the provided `views` will be added to the existing
+		// views. When adding, the `views` will added to the end of the array
+		// by default. To insert `views` at a specific index, use `options.at`.
 		set: function( selector, views, options ) {
 			var $selector, els, existing, add, method;
 
@@ -638,10 +663,30 @@
 			return this;
 		},
 
+		// ### Add subview(s) to existing subviews
+		//
+		// An alias to `Views.set()`, which defaults `options.add` to true.
+		//
+		// Adds any number of `views` to a `selector`.
+		//
+		// When no `selector` is provided, the root selector (the empty string)
+		// is used. `views` accepts a `Backbone.View` instance or an array of
+		// `Backbone.View` instances.
+		//
+		// Use `Views.set()` when setting `options.add` to `false`.
+		//
+		// Accepts an `options` object. By default, provided `views` will be
+		// inserted at the end of the array of existing views. To insert
+		// `views` at a specific index, use `options.at`. For more information
+		// on the `options` object, see `Views.set()`.
 		add: function( selector, views, options ) {
 			return this.set( selector, views, _.extend({ add: true }, options ) );
 		},
 
+		// ### Stop tracking subviews
+		//
+		// Stops tracking `views` registered to a `selector`. If no `views` are
+		// set, then all of the `selector`'s subviews will be unregistered.
 		unset: function( selector, views ) {
 			var existing;
 
@@ -658,11 +703,20 @@
 			return this;
 		},
 
+		// ### Detach all subviews
+		//
+		// Detaches all subviews from the DOM.
+		//
+		// Helps to preserve all subview events when re-rendering the master
+		// view. Used in conjunction with `Views.render()`.
 		detach: function() {
 			$( _.pluck( this.all(), 'el' ) ).detach();
 			return this;
 		},
 
+		// ### Render all subviews
+		//
+		// Renders all subviews. Used in conjunction with `Views.detach()`.
 		render: function() {
 			var root = this._views[''];
 
@@ -677,6 +731,10 @@
 			return this;
 		},
 
+		// ### Dispose all subviews
+		//
+		// Triggers the `dispose()` method on all subviews. Resets the
+		// internals of the views manager.
 		dispose: function() {
 			delete this.parent;
 			delete this.selector;
@@ -686,11 +744,23 @@
 			return this;
 		},
 
+		// ### Replace a selector's subviews
+		//
+		// By default, sets the `$target` selector's html to the subview `els`.
+		//
+		// Can be overridden in subclasses.
 		replace: function( $target, els ) {
 			$target.html( els );
 			return this;
 		},
 
+		// ### Insert subviews into a selector
+		//
+		// By default, appends the subview `els` to the end of the `$target`
+		// selector. If `options.at` is set, inserts the subview `els` at the
+		// provided index.
+		//
+		// Can be overridden in subclasses.
 		insert: function( $target, els, options ) {
 			var at = options && options.at,
 				$children;