From 580bbddb906f16365c10766e04bafbadbba931ba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Alberto=20Cuesta=20Ca=C3=B1ada?= <mail@albertocuesta.es>
Date: Tue, 21 Jan 2020 09:36:51 +0000
Subject: [PATCH] Improved comments.

---
 contracts/mocks/EnumerableSetMock.sol |  2 +-
 contracts/utils/EnumerableSet.sol     | 18 +++++++++++++-----
 test/utils/EnumerableSet.test.js      |  6 +++---
 3 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/contracts/mocks/EnumerableSetMock.sol b/contracts/mocks/EnumerableSetMock.sol
index b4a1f3e79..dd95ed8a5 100644
--- a/contracts/mocks/EnumerableSetMock.sol
+++ b/contracts/mocks/EnumerableSetMock.sol
@@ -4,7 +4,7 @@ import "../utils/EnumerableSet.sol";
 
 /**
  * @title EnumerableSetMock
- * @dev Data structure
+ * @dev Data structure - https://en.wikipedia.org/wiki/Set_(abstract_data_type)
  * @author Alberto Cuesta Cañada
  */
 contract EnumerableSetMock{
diff --git a/contracts/utils/EnumerableSet.sol b/contracts/utils/EnumerableSet.sol
index 14051719c..2dee50a43 100644
--- a/contracts/utils/EnumerableSet.sol
+++ b/contracts/utils/EnumerableSet.sol
@@ -3,7 +3,15 @@ pragma solidity ^0.5.10;
 
 /**
  * @title EnumerableSet
- * @dev Data structure
+ * @dev Data structure - https://en.wikipedia.org/wiki/Set_(abstract_data_type)
+ *
+ * EnumerableSet is a data structure that can contain an arbitrary number of unique addresses.
+ * The contents of the set can be retrieved as an array, but two separate calls to `enumerate`
+ * are not guaranteed to return values in the same order.
+ *
+ * Initialization of a set must include an empty array:
+ * `EnumerableSet.Set set = EnumerableSet.Set({values: new address[](0)});`
+ *
  * @author Alberto Cuesta Cañada
  */
 library EnumerableSet {
@@ -19,7 +27,7 @@ library EnumerableSet {
     }
 
     /**
-     * @dev Add a value.
+     * @dev Add a value. O(1).
      */
     function add(Set storage set, address value)
         internal
@@ -31,7 +39,7 @@ library EnumerableSet {
     }
 
     /**
-     * @dev Remove a value.
+     * @dev Remove a value. O(1).
      */
     function remove(Set storage set, address value)
         internal
@@ -45,7 +53,7 @@ library EnumerableSet {
     }
 
     /**
-     * @dev Returns true if the value is in the set.
+     * @dev Returns true if the value is in the set. O(1).
      */
     function contains(Set storage set, address value)
         internal
@@ -56,7 +64,7 @@ library EnumerableSet {
     }
 
     /**
-     * @dev Return an array with all values in the set.
+     * @dev Return an array with all values in the set. O(N).
      */
     function enumerate(Set storage set)
         internal
diff --git a/test/utils/EnumerableSet.test.js b/test/utils/EnumerableSet.test.js
index 4e27218ff..148212a23 100644
--- a/test/utils/EnumerableSet.test.js
+++ b/test/utils/EnumerableSet.test.js
@@ -18,7 +18,7 @@ describe('EnumerableSet', function () {
     expect(await this.set.testContains(a)).to.equal(false);
   });
 
-  it('adds an value.', async function () {
+  it('adds a value.', async function () {
     await this.set.testAdd(a);
     expect(await this.set.testContains(a)).to.equal(true);
   });
@@ -37,11 +37,11 @@ describe('EnumerableSet', function () {
     expect(await this.set.testContains(a)).to.equal(false);
   });
 
-  it('Retrieve an empty array', async function () {
+  it('enumerates values as an empty array', async function () {
     expect(await this.set.testEnumerate()).to.eql([]);
   });
 
-  it('Retrieve an array of values', async function () {
+  it('enumerates an array of values', async function () {
     await this.set.testAdd(a);
     await this.set.testAdd(b);
     await this.set.testAdd(c);