Updated the region docs #3210

Added documentation to clarify that region hiding won't remove HTML outside of views.

docs/marionette.region.md

@@ -256,6 +256,9 @@ mainRegion.show(new OtherView());
 mainRegion.hasView() // true
 ```
 
+If you show a view in a region with an existing view, Marionette will
+[remove the existing View](#emptying-a-region) before showing the new one.
+
 ## Emptying a Region
 
 You can remove a view from a region (effectively "unshowing" it) with
@@ -272,6 +275,10 @@ mainRegion.empty();
 This will destroy the view, clean up any event handlers and remove it from
 the DOM. When a region is emptied [empty events are triggered](./viewlifecycle.md#empty-region-events).
 
+**Note**: If the region does _not_ currently contain a View it will detach
+any HTML inside the region when emptying. If the region _does_ contain a
+View [any HTML that doesn't belong to the View will remain](./upgrade.md#changes-to-regionshow).
+
 ### Preserving Existing Views
 
 **_DEPRECATED: `preventDestroy` is deprecated. See
@@ -356,19 +363,6 @@ Mn.Region.prototype.attachHtml = function(view){
 }
 ```
 
-This replaces the contents of the region with the view's
-`el` / content. You can override `attachHtml` for transition effects and more.
-
-```javascript
-var Mn = require('backbone.marionette');
-
-Mn.Region.prototype.attachHtml = function(view){
-  this.$el.hide();
-  this.$el.html(view.el);
-  this.$el.slideDown("fast");
-}
-```
-
 It is also possible to define a custom attach method for a single region by
 extending from the Region class and including a custom `attachHtml` method.
 

docs/upgrade.md

@@ -111,6 +111,63 @@ Replace all instances of `show` and `before:show` with `render` and
 `before:render`. If you want the view to be visible in the DOM, then listen to
 the `dom:refresh` event.
 
+### Changes to `region.show()`
+
+The `region.show()` method (that also backs `showChildView()`) was changed to
+not remove HTML outside the `$el` of the displayed view. In Marionette 2,
+the `region.show()` method would call `region.$el.empty()` before showing the
+new HTML.
+
+In Marionette 3, this was changed to unhook `region.currentView` from the DOM,
+remove all event handlers, then delete it. Any HTML added to the region that
+isn't contained in the DOM of the View won't be removed.
+
+For example:
+
+```javascript
+var _ = require('underscore');
+var Mn = require('backbone.marionette');
+
+var app = require('./app');
+
+var MyView = Mn.View.extend({
+  template: _.template('View contents')
+});
+
+var ParentView = Mn.View.extend({
+  template: _.template('<div class="view-hook"></div>'),
+  regions: {
+    child: '.view-hook'
+  }
+});
+
+var parent = new ParentView();
+app.showView(parent);
+
+var child = new MyView();
+
+parent.showChildView('child', child);
+parent.getRegion('child').$el.append('<p>Not removed</p>');
+parent.showChildView('child', new MyView());
+```
+
+In Marionette 2, the HTML output will be:
+
+```html
+<div class="view-hook">
+  <div>View contents</div>
+</div>
+```
+
+In Marionette 3, the HTML will be:
+
+```html
+<div class="view-hook">
+  <p>Not Removed</p>
+  <div>View contents</div>
+</div>
+```
+
 ## Templates
 
 The biggest change to templates is renaming `templateHelpers` to