Bug 1298243 part 1. Add some more documentation to DataTransferItemList. r=mystor
authorBoris Zbarsky <bzbarsky@mit.edu>
Mon, 10 Oct 2016 21:07:47 -0400
changeset 423588 6147b5ffb4a0e001f8f3b7aa7db14cbdaad395a9
parent 423587 3d42c7605d818d6e277d570a8fc4309cf5019ee1
child 423589 9a4c0703e8251bd951f97919d8370de2926e2f07
push id31945
push users.kaspari@gmail.com
push dateTue, 11 Oct 2016 12:27:19 +0000
reviewersmystor
bugs1298243
milestone52.0a1
Bug 1298243 part 1. Add some more documentation to DataTransferItemList. r=mystor
dom/events/DataTransferItemList.h
--- a/dom/events/DataTransferItemList.h
+++ b/dom/events/DataTransferItemList.h
@@ -106,16 +106,27 @@ private:
 
   ~DataTransferItemList() {}
 
   RefPtr<DataTransfer> mDataTransfer;
   bool mIsExternal;
   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;
 };
 
 } // namespace dom
 } // namespace mozilla
 
 #endif // mozilla_dom_DataTransferItemList_h