add comments from rdooley, add comment around stop behavior

AUTHORS.rst

@@ -16,3 +16,4 @@ Patches and Suggestions
 - J Derek Wilson
 - Alex Kuang
 - Simon Dollé
+- Rees Dooley

retrying.py

@@ -69,9 +69,12 @@ else:
 # sys.maxint / 2, since Python 3.2 doesn't have a sys.maxint...
 MAX_WAIT = 1073741823
 
+
 def retry(*dargs, **dkw):
     """
-    TODO comment
+    Decorator function that instantiates the Retrying object
+    @param *dargs: positional arguments passed to Retrying object
+    @param **dkw: keyword arguments passed to the Retrying object
     """
     # support both @retry and @retry() as valid syntax
     if len(dargs) == 1 and callable(dargs[0]):
@@ -238,6 +241,7 @@ class Retrying(object):
             delay_since_first_attempt_ms = int(round(time.time() * 1000)) - start_time
             if self.stop(attempt_number, delay_since_first_attempt_ms):
                 if not self._wrap_exception and attempt.has_exception:
+                    # get() on an attempt with an exception should cause it to be raised, but raise just in case
                     raise attempt.get()
                 else:
                     raise RetryError(attempt)
@@ -247,6 +251,7 @@ class Retrying(object):
 
             attempt_number += 1
 
+
 class Attempt(object):
     """
     An Attempt encapsulates a call to a target function that may end as a
@@ -279,6 +284,7 @@ class Attempt(object):
         else:
             return "Attempts: {0}, Value: {1}".format(self.attempt_number, self.value)
 
+
 class RetryError(Exception):
     """
     A RetryError encapsulates the last Attempt instance right before giving up.