Bug 1298243 part 1. Add some more documentation to DataTransferItemList. r=mystor

dom/events/DataTransferItemList.h

@@ -111,7 +111,18 @@ private:
   RefPtr<FileList> mFiles;
   // The principal for which mFiles is cached
   nsCOMPtr<nsIPrincipal> mFilesPrincipal;
+  // mItems is the list of items that corresponds to the spec concept of a
+  // DataTransferItemList.  That is, this is the thing the spec's indexed getter
+  // operates on.  The items in here are a subset of the items present in the
+  // arrays that live in mIndexedItems.
   nsTArray<RefPtr<DataTransferItem>> mItems;
+  // mIndexedItems represents all our items.  For any given index, all items at
+  // that index have different types in the GetType() sense.  That means that
+  // representing multiple items with the same type (e.g. multiple files)
+  // requires using multiple indices.
+  //
+  // There is always a (possibly empty) list of items at index 0, so
+  // mIndexedItems.Length() >= 1 at all times.
   nsTArray<nsTArray<RefPtr<DataTransferItem>>> mIndexedItems;
 };