From: Jeremy Stanley <fungi@yuggoth.org>
Date: Sun, 23 Feb 2014 14:36:51 +0000 (+0000)
Subject: Clean up docstrings
X-Git-Tag: 0.0.1~254
X-Git-Url: https://mudpy.org/gitweb?p=mudpy.git;a=commitdiff_plain;h=d339c9cd860a8381c4ae2770011c9a41bfd7b67b

Clean up docstrings
---

diff --git a/lib/mudpy/misc.py b/lib/mudpy/misc.py
index d78eac6..a8b0104 100644
--- a/lib/mudpy/misc.py
+++ b/lib/mudpy/misc.py
@@ -2588,8 +2588,7 @@ def setup():
 
 
 def finish():
-    """This contains functions to be performed when shutting down the
-        engine."""
+    """These are functions performed when shutting down the engine."""
 
     # the loop has terminated, so save persistent data
     universe.save()
diff --git a/lib/mudpy/password.py b/lib/mudpy/password.py
index f6c1abc..96a14d8 100644
--- a/lib/mudpy/password.py
+++ b/lib/mudpy/password.py
@@ -23,7 +23,8 @@ SHA512 = 5  # hashlib.sha512
 
 
 def _pack_bytes(numbers):
-    """
+    """Make a packed byte sequence:
+
     This is a wrapper around struct.pack, used to turn a list of integers
     between 0 and 255 into a packed sequence akin to a C-style string.
     """
@@ -36,7 +37,8 @@ def _pack_bytes(numbers):
 
 
 def _bytes_to_text(byte_sequence):
-    """
+    """Generate printable representation of 8-bit data:
+
     This is a wrapper around base64.b64encode with preferences
     appropriate for encoding Unix-style passwd hash strings.
     """
@@ -47,7 +49,8 @@ def _bytes_to_text(byte_sequence):
 
 
 def _generate_salt(salt_len=2):
-    """
+    """Generate salt for a password hash:
+
     This simply generates a sequence of pseudo-random characters (with
     6-bits of effective entropy per character). Since it relies on base64
     encoding (which operates on 6-bit chunks of data), we only generate
@@ -62,7 +65,8 @@ def _generate_salt(salt_len=2):
 
 
 def upgrade_legacy_hash(legacy_hash, salt, sep="$"):
-    """
+    """Upgrade an older password hash:
+
     This utility function is meant to provide a migration path for users
     of mudpy's legacy account-name-salted MD5 hexdigest password hashes.
     By passing the old passhash (as legacy_hash) and name (as salt)
@@ -95,7 +99,8 @@ def create(
     salt_len=2,
     sep="$"
 ):
-    """
+    """Generate a password hash:
+
     The meat of the module, this function takes a provided password and
     generates a Unix-like passwd hash suitable for storage in portable,
     text-based data files. The password is prepended with a salt (which
@@ -173,7 +178,8 @@ def create(
 
 
 def verify(password, encoded_hash):
-    """
+    """Verify a password:
+
     This simple function requires a text password and a mudpy-format
     password hash (as generated by the create function). It returns True
     if the password, hashed with the parameters from the encoded_hash,
diff --git a/lib/mudpy/telnet.py b/lib/mudpy/telnet.py
index 471f9fd..a4264ce 100644
--- a/lib/mudpy/telnet.py
+++ b/lib/mudpy/telnet.py
@@ -60,8 +60,7 @@ def send_command(user, *command):
 
 
 def is_enabled(user, telopt, party, state=YES):
-    """Returns True if the indicated Telnet option is enabled, False if
-        not."""
+    """Indicates whether a specified Telnet option is enabled."""
     if (telopt, party) in user.telopts and user.telopts[
        (telopt, party)
        ] is state:
@@ -88,8 +87,7 @@ def enable(user, telopt, party):
 
 
 def disable(user, telopt, party):
-    """Negotiates disabling a Telnet option for the indicated user's
-        socket."""
+    """Negotiates disabling a Telnet option for the user's socket."""
     if party is HIM:
         txneg = DONT
     else: