More docs for data adapters

Author: kevin-brown

docs/_includes/options/data/array.html

@@ -4,9 +4,21 @@ <h2 id="data">
   </h2>
 
   <p>
-    Yes, but only when you are initially creating it.
+    While Select2 is designed to be used with a <code>&lt;select&gt;</code> tag, the data that is used to search through and display the results can be loaded from a JavaScript array using the <code>data</code> option. This option should be passed in during the initialization of Select2.
   </p>
 
+<pre class="prettyprint linenums">
+$('select').select2({
+  data: [
+    {
+      id: 'value',
+      text: 'Text to display'
+    },
+    // ... more data objects ...
+  ]
+});
+</pre>
+
   <h3>
     What properties are required on the objects passed in to the array?
   </h3>
@@ -19,12 +31,29 @@ <h3>
     How should nested results be formatted?
   </h3>
 
+  <p>
+    Nested results should be specified using the <code>children</code> property on the data objects that are passed in. This <code>children</code> property should be an array of data objects that are grouped under this option, and the label for the group should be specified as the <code>text</code> property on the root data object.
+  </p>
+
+<pre class="prettyprint linenums">
+{
+  text: 'Group label',
+  children: [
+    {
+      id: 'nested-1',
+      text: 'First nested option'
+    },
+    // ... more data objects ...
+  ]
+}
+</pre>
+
   <h3>
     How many levels of nesting are allowed?
   </h3>
 
   <p>
-    Because Select2 falls back to an <code>&lt;optgroup&gt;</code> when creating nested options, only a single level of nesting can be supported.
+    Because Select2 falls back to an <code>&lt;optgroup&gt;</code> when creating nested options, only <a href="#how-many-levels-of-nesting-can-there-be">a single level of nesting</a> is supported. Any additional levels of nesting is not guarenteed to be displayed properly across all browsers and devices.
   </p>
 
   <h3>
@@ -35,6 +64,8 @@ <h3>
     The <code>data</code> option is a shortcut that Select2 provides which allows you to load options into your <code>select</code> from a data array.
   </p>
 
+  {% include options/not-written.html %}
+
   <h3>
     My objects don&apos;t use <code>id</code> for their unique identifiers, what can I do?
   </h3>
@@ -43,11 +74,15 @@ <h3>
     You can re-map your identifier before passing it to Select2.
   </p>
 
+  {% include options/not-written.html %}
+
   <h3>
     My objects use a property other than <code>text</code> for the text that needs to be displayed
   </h3>
 
   <p>
     These can also be re-mapped.
   </p>
+
+  {% include options/not-written.html %}
 </section>

docs/_includes/options/data/select.html

@@ -3,28 +3,40 @@ <h2 id="data-adapters-select-tag">
     Can Select2 be used with a <code>&lt;select&gt;</code> tag?
   </h2>
 
+  <p>
+    Select2 was designed to be a replacement for the standard <code>&lt;select&gt;</code> boxes that are displayed by the browser, so by default it supports all options and operations that are available in a standard select box, but with added flexibility. There is no special configuration required to make Select2 work with a <code>&lt;select&gt;</code> tag.
+  </p>
+
   <h3>
     Does Select2 support nesting options?
   </h3>
 
   <p>
-    Yes, just like in a standard <code>select</code>.
+    A standard <code>&lt;select&gt;</code> box can display nested options by wrapping them with in an <code>&lt;optgroup&gt;</code> tag.
   </p>
 
+<pre class="prettyprint">
+&lt;select&gt;
+  &lt;optgroup label="Group Name"&gt;
+    &lt;option&gt;Nested option&lt;/option&gt;
+  &lt;/optgroup&gt;
+&lt;/select&gt;
+</pre>
+
   <h3>
     How many levels of nesting can there be?
   </h3>
 
   <p>
-    Only a single level of nesting is allowed per the HTML specification.
+    Only a single level of nesting is allowed per the HTML specification. If you nest an <code>&lt;optgroup&gt;</code> within another <code>&lt;optgroup&gt;</code>, Select2 will not be able to detect the extra level of nesting and errors may be triggered as a result.
   </p>
 
   <h3>
     Can <code>&lt;optgroup&gt;</code> tags be made selectable?
   </h3>
 
   <p>
-    No. This is a limitation of the HTML specification and is not a limitation that Select2 can overcome.
+    No. This is a limitation of the HTML specification and is not a limitation that Select2 can overcome. You can emulate grouping by using an <code>&lt;option&gt;</code> instead of an <code>&lt;optgroup&gt;</code> and <a href="http://stackoverflow.com/q/30820215/359284#30948247">changing the style by using CSS</a>, but this is not recommended as it is not fully accessible.
   </p>
 
   <h3>