Add docstrings for protocol and server methods.

labrad · Dec 22, 2015 · 4ac16f5 · 4ac16f5
1 parent 697f258
commit 4ac16f5
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 5 deletions.
diff --git a/labrad/protocol.py b/labrad/protocol.py
@@ -301,7 +301,7 @@ def removeListener(self, listener, source=None, context=None, ID=None):
 
     @inlineCallbacks
     def authenticate(self, password):
-        """Implements the LabRAD login protocol."""
+        """Authenticate to the manager using the given password."""
         # send login packet
         resp = yield self.sendRequest(C.MANAGER_ID, [])
         challenge = resp[0][1] # get password challenge
@@ -321,11 +321,33 @@ def authenticate(self, password):
         self.loginMessage = resp[0][1] # get welcome message
 
     def loginClient(self, name):
-        """Log in as a client."""
+        """Log in as a client by sending our name to the manager.
+
+        Args:
+            name (str): The name of this labrad connection. Need not be unique.
+
+        Returns:
+            twisted.internet.defer.Deferred(None): A deferred that will fire
+            after we have logged in.
+        """
         return self._doLogin(name)
 
     def loginServer(self, name, descr, notes):
-        """Log in as a server."""
+        """Log in as a server by sending our name and metadata to the manager.
+
+        Args:
+            name (str): The name of this server. Must be unique; login will
+                fail if another server of the same name is already connected.
+            descr (str): A description of this server, which will be exposed
+                to other labrad clients.
+            notes (str): More descriptive information about the server. This
+                field is deprecated; instead we recommend just putting all info
+                into descr.
+
+        Returns:
+            twisted.internet.defer.Deferred(None): A deferred that will fire
+            after we have logged in.
+        """
         return self._doLogin(name, descr, notes)
 
     @inlineCallbacks
@@ -369,8 +391,7 @@ def connect(host=C.MANAGER_HOST, port=None, tls=C.MANAGER_TLS):
 
     Returns:
         twisted.internet.defer.Deferred(LabradProtocol): A deferred that will
-        fire with the protocol once the connection is established, or will
-        errback if the connection fails.
+        fire with the protocol once the connection is established.
     """
     tls = C.check_tls_mode(tls)
     if port is None:

diff --git a/labrad/server.py b/labrad/server.py
@@ -341,6 +341,22 @@ def removeSignal(self, signal, packet=None):
 
     @inlineCallbacks
     def startup(self, protocol):
+        """Start this server using the given protocol connection.
+
+        Identifies this server to the manager, creates an async wrapper for the
+        protocol connection, and then runs initialization callbacks for this
+        server.
+
+        Args:
+            protocol (labrad.protocol.LabradProtocol): A protocol connection
+                to the labrad manager, as returned by labrad.protocol.connect.
+                This protocol must have been authenticated prior to calling
+                startup.
+
+        Returns:
+            twisted.internet.defer.Deferred(None): A deferred that will fire
+            once startup is complete.
+        """
         try:
             name = getattr(self, 'instanceName', self.name)
             yield protocol.loginServer(name, self.description, self.notes)