From d78bad06b71f03ecab1aeb5e320d1336eaca79ba Mon Sep 17 00:00:00 2001
From: Jan Dittberner <jan@dittberner.info>
Date: Mon, 19 Jan 2015 23:00:01 +0100
Subject: [PATCH] add docstrings to managemails.models

---
 gnuviechadmin/managemails/models.py | 32 +++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/gnuviechadmin/managemails/models.py b/gnuviechadmin/managemails/models.py
index 512bea7..0ffddde 100644
--- a/gnuviechadmin/managemails/models.py
+++ b/gnuviechadmin/managemails/models.py
@@ -37,6 +37,16 @@ class MailboxManager(models.Manager):
     """
 
     def get_next_mailbox_name(self, osuser):
+        """
+        Get the next available mailbox name for the given operating system
+        user.
+
+        :param osuser: a :py:class:`operating system user <osuser.models.User>`
+            instance
+        :return: name of the mailbox
+        :rtype: str
+
+        """
         count = 1
         mailboxformat = "{0}p{1:02d}"
         mailboxname = mailboxformat.format(osuser.username, count)
@@ -54,6 +64,10 @@ class MailboxManager(models.Manager):
 
 @python_2_unicode_compatible
 class Mailbox(ActivateAbleMixin, TimeStampedModel, models.Model):
+    """
+    This is the model class for a mailbox.
+
+    """
     osuser = models.ForeignKey(OsUser)
     username = models.CharField(max_length=128, unique=True)
     password = models.CharField(max_length=255)
@@ -66,6 +80,12 @@ class Mailbox(ActivateAbleMixin, TimeStampedModel, models.Model):
         verbose_name_plural = _('Mailboxes')
 
     def set_password(self, password):
+        """
+        Set the hashed password for the mailbox.
+
+        :param str password: the clear text password
+
+        """
         self.password = sha512_crypt.encrypt(password)
 
     def save(self, *args, **kwargs):
@@ -82,6 +102,10 @@ class Mailbox(ActivateAbleMixin, TimeStampedModel, models.Model):
 
 @python_2_unicode_compatible
 class MailAddress(ActivateAbleMixin, TimeStampedModel, models.Model):
+    """
+    This is the model class for a mail address.
+
+    """
     localpart = models.CharField(max_length=128)
     domain = models.ForeignKey(MailDomain)
 
@@ -97,6 +121,10 @@ class MailAddress(ActivateAbleMixin, TimeStampedModel, models.Model):
 
 @python_2_unicode_compatible
 class MailAddressMailbox(TimeStampedModel, models.Model):
+    """
+    This is the model class to assign a mail address to a mailbox.
+
+    """
     mailaddress = models.OneToOneField(MailAddress, primary_key=True)
     mailbox = models.ForeignKey(Mailbox)
 
@@ -108,6 +136,10 @@ class MailAddressMailbox(TimeStampedModel, models.Model):
 
 
 class MailAddressForward(TimeStampedModel, models.Model):
+    """
+    This is a model class to map mail addresses to forwarding addresses.
+
+    """
     mailaddress = models.ForeignKey(MailAddress)
     target = models.EmailField(max_length=254)