*selection*.selection() returns itself

README.md

@@ -198,6 +198,10 @@ See [*selection*.data](#selection_data) for more.
 
 This method is not intended for concatenating arbitrary selections, however: if both this selection and the specified *other* selection have (non-null) elements at the same index, this selection’s element is returned in the merge and the *other* selection’s element is ignored.
 
+<a name="selection_selection" href="#selection_selection">#</a> <i>selection</i>.<b>selection</b>() [<>](https://github.com/d3/d3-selection/blob/master/src/selection/index.js "Source")
+
+Returns the selection (for symmetry with [<i>transition</i>.selection](https://github.com/d3/d3-transition/blob/master/README.md#transition_selection)).
+
 <a name="matcher" href="#matcher">#</a> d3.<b>matcher</b>(<i>selector</i>) [<>](https://github.com/d3/d3-selection/blob/master/src/matcher.js "Source")
 
 Given the specified *selector*, returns a function which returns true if `this` element [matches](https://developer.mozilla.org/en-US/docs/Web/API/Element/matches) the specified selector. This method is used internally by [*selection*.filter](#selection_filter). For example, this:
@@ -320,23 +324,23 @@ Use [*selection*.append](#selection_append) or [*selection*.insert](#selection_i
 
 If the specified *type* is a string, appends a new element of this type (tag name) as the last child of each selected element, or before the next following sibling in the update selection if this is an [enter selection](#selection_enter). The latter behavior for enter selections allows you to insert elements into the DOM in an order consistent with the new bound data; however, note that [*selection*.order](#selection_order) may still be required if updating elements change order (*i.e.*, if the order of new data is inconsistent with old data).
 
-If the specified *type* is a function, it is evaluated for each selected element, in order, being passed the current datum (*d*), the current index (*i*), and the current group (*nodes*), with *this* as the current DOM element (*nodes*[*i*]). This function should return an element to be appended. (The function typically creates a new element, but it may instead return an existing element.) For example, to append a DIV element to each paragraph:
+If the specified *type* is a function, it is evaluated for each selected element, in order, being passed the current datum (*d*), the current index (*i*), and the current group (*nodes*), with *this* as the current DOM element (*nodes*[*i*]). This function should return an element to be appended. (The function typically creates a new element, but it may instead return an existing element.) For example, to append a paragraph to each DIV element:
 
 ```js
-d3.selectAll("p").append("div");
+d3.selectAll("div").append("p");
 ```
 
 This is equivalent to:
 
 ```js
-d3.selectAll("p").append(() => document.createElement("div"));
+d3.selectAll("div").append(() => document.createElement("p"));
 ```
 
 Which is equivalent to:
 
 ```js
-d3.selectAll("p").select(function() {
-  return this.appendChild(document.createElement("div"));
+d3.selectAll("div").select(function() {
+  return this.appendChild(document.createElement("p"));
 });
 ```
 
@@ -348,23 +352,23 @@ The specified *name* may have a namespace prefix, such as `svg:text` to specify
 
 If the specified *type* is a string, inserts a new element of this type (tag name) before the first element matching the specified *before* selector for each selected element. For example, a *before* selector `:first-child` will prepend nodes before the first child. If *before* is not specified, it defaults to null. (To append elements in an order consistent with [bound data](#joining-data), use [*selection*.append](#selection_append).)
 
-Both *type* and *before* may instead be specified as functions which are evaluated for each selected element, in order, being passed the current datum (*d*), the current index (*i*), and the current group (*nodes*), with *this* as the current DOM element (*nodes*[*i*]). The *type* function should return an element to be inserted; the *before* function should return the child element before which the element should be inserted. For example, to append a DIV element to each paragraph:
+Both *type* and *before* may instead be specified as functions which are evaluated for each selected element, in order, being passed the current datum (*d*), the current index (*i*), and the current group (*nodes*), with *this* as the current DOM element (*nodes*[*i*]). The *type* function should return an element to be inserted; the *before* function should return the child element before which the element should be inserted. For example, to append a paragraph to each DIV element:
 
 ```js
-d3.selectAll("p").insert("div");
+d3.selectAll("div").insert("p");
 ```
 
 This is equivalent to:
 
 ```js
-d3.selectAll("p").insert(() => document.createElement("div"));
+d3.selectAll("div").insert(() => document.createElement("p"));
 ```
 
 Which is equivalent to:
 
 ```js
-d3.selectAll("p").select(function() {
-  return this.insertBefore(document.createElement("div"), null);
+d3.selectAll("div").select(function() {
+  return this.insertBefore(document.createElement("p"), null);
 });
 ```
 

src/selection/index.js

@@ -41,6 +41,10 @@ function selection() {
   return new Selection([[document.documentElement]], root);
 }
 
+function selection_selection() {
+  return this;
+}
+
 Selection.prototype = selection.prototype = {
   constructor: Selection,
   select: selection_select,
@@ -51,6 +55,7 @@ Selection.prototype = selection.prototype = {
   exit: selection_exit,
   join: selection_join,
   merge: selection_merge,
+  selection: selection_selection,
   order: selection_order,
   sort: selection_sort,
   call: selection_call,

test/selection/select-test.js

@@ -106,3 +106,11 @@ tape("selection.select(…) skips missing originating elements when the originat
   test.deepEqual(d3.selectAll([one, two]).selectAll("child").select(function(d, i) { return i & 1 ? this : null; }).select("span"), {_groups: [[, three], [, four]], _parents: [one, two]});
   test.end();
 });
+
+tape("selection.selection() returns itself", function(test) {
+  var document = jsdom("<h1>hello</h1>");
+  var sel = d3.select(document).select("h1");
+  test.ok(sel === sel.selection());
+  test.ok(sel === sel.selection().selection());
+  test.end();
+});