From 0a61fef7a6eba0b1d24ee7ed66775d2f8335c415 Mon Sep 17 00:00:00 2001
From: Kali Kaneko <kali@leap.se>
Date: Mon, 21 Sep 2015 16:37:25 -0400
Subject: [doc] document return values

---
 mail/src/leap/mail/incoming/service.py | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/mail/src/leap/mail/incoming/service.py b/mail/src/leap/mail/incoming/service.py
index c98e639..ec85eed 100644
--- a/mail/src/leap/mail/incoming/service.py
+++ b/mail/src/leap/mail/incoming/service.py
@@ -32,6 +32,7 @@ from urlparse import urlparse
 
 from twisted.application.service import Service
 from twisted.python import log
+from twisted.python.failure import Failure
 from twisted.internet import defer, reactor
 from twisted.internet.task import LoopingCall
 from twisted.internet.task import deferLater
@@ -183,13 +184,21 @@ class IncomingMail(Service):
     def startService(self):
         """
         Starts a loop to fetch mail.
+
+        :returns: A Deferred whose callback will be invoked with
+                  the LoopingCall instance when loop.stop is called, or
+                  whose errback will be invoked when the function raises an
+                  exception or returned a deferred that has its errback
+                  invoked.
         """
         Service.startService(self)
         if self._loop is None:
             self._loop = LoopingCall(self.fetch)
-            return self._loop.start(self._check_period)
+            stop_deferred = self._loop.start(self._check_period)
+            return stop_deferred
         else:
             logger.warning("Tried to start an already running fetching loop.")
+            return defer.fail(Failure('Already running loop.'))
 
     def stopService(self):
         """
-- 
cgit v1.2.3