Updated models and signals documentation

src/pretix/base/models/invoices.py

@@ -17,6 +17,22 @@ def invoice_filename(instance, filename: str) -> str:
 
 
 class Invoice(models.Model):
+    """
+    Represents an invoice that is issued because of an order. Because invoices are legally required
+    not to change, this object duplicates a log of data (e.g. the invoice address).
+
+    :param order: The associated order
+    :param event: The event this belongs to (for convenience)
+    :param invoice_no: The human-readable, event-unique invoice number
+    :param is_cancellation: Whether or not this is a cancellation instead of an invoice
+    :param refers: A link to another invoice this invoice referse to, e.g. the cancelled invoice in an cancellation
+    :param invoice_from: The sender address
+    :param invoice_to: The receiver address
+    :param date: The invoice date
+    :param locale: The locale in which the invoice should be printed
+    :param additional_text: Additional text for the invoice
+    :param file: The filename of the rendered invoice
+    """
     order = models.ForeignKey('Order', related_name='invoices', db_index=True)
     event = models.ForeignKey('Event', related_name='invoices', db_index=True)
     invoice_no = models.PositiveIntegerField(db_index=True)
@@ -48,6 +64,9 @@ class Invoice(models.Model):
 
     @property
     def number(self):
+        """
+        Returns the invoice number in a human-readable way with the event slug prepended.
+        """
         return '%s-%05d' % (self.event.slug.upper(), self.invoice_no)
 
     class Meta:
@@ -55,6 +74,15 @@ class Invoice(models.Model):
 
 
 class InvoiceLine(models.Model):
+    """
+    One position listed on an invoice.
+
+    :param invoice: The invoice this belongs to
+    :param description: The item description
+    :param gross_value: The gross value
+    :param tax_value: The included tax (as an absolute value)
+    :param tax_rate: The applied tax rate in percent
+    """
     invoice = models.ForeignKey('Invoice', related_name='lines')
     description = models.TextField()
     gross_value = models.DecimalField(max_digits=10, decimal_places=2)

src/pretix/base/models/log.py

@@ -9,6 +9,7 @@ class LogEntry(models.Model):
     in the database. This uses django.contrib.contenttypes to allow a
     relation to an arbitrary database object.
 
+    :param datatime: The timestamp of the logged action
     :param user: The user that performed the action
     :type user: User
     :param action_type: The type of action that has been performed. This is

src/pretix/base/models/orders.py

@@ -52,6 +52,8 @@ class Order(LoggedModel):
     :type email: str
     :param locale: The locale of this order
     :type locale: str
+    :param secret: A secret string that is required to modify the order
+    :type secret: str
     :param datetime: The datetime of the order placement
     :type datetime: datetime
     :param expires: The date until this order has to be paid to guarantee the
@@ -62,6 +64,10 @@ class Order(LoggedModel):
     :type payment_provider: str
     :param payment_fee: The payment fee calculated at checkout time
     :type payment_fee: decimal.Decimal
+    :param payment_fee_tax_value: The absolute amound of tax included in the payment fee
+    :type payment_fee_tax_value: decimal.Decimal
+    :param payment_fee_tax_rate: The tax rate applied to the payment fee (in percent)
+    :type payment_fee_tax_rate: decimal.Decimal
     :param payment_info: Arbitrary information stored by the payment provider
     :type payment_info: str
     :param total: The total amount of the order, including the payment fee
@@ -170,6 +176,10 @@ class Order(LoggedModel):
         super().save(*args, **kwargs)
 
     def _calculate_tax(self):
+        """
+        Calculates the taxes on the payment fees and sets the parameters payment_fee_tax_rate
+        and payment_fee_tax_value accordingly.
+        """
         self.payment_fee_tax_rate = self.event.settings.get('tax_rate_default')
         if self.payment_fee_tax_rate:
             self.payment_fee_tax_value = round_decimal(

src/pretix/base/models/vouchers.py

@@ -20,6 +20,25 @@ def generate_code():
 
 
 class Voucher(LoggedModel):
+    """
+    Represents a voucher. A voucher can reserve ticket quota or allow special prices.
+
+    :param event: The event this voucher is valid for
+    :param code: The secret voucher code
+    :param redeemed: Whether or not this voucher has already been redeemed
+    :param valid_until: The expiration date of this voucher (optional)
+    :param block_quota: If set to true, this voucher will reserve quota for its holder
+    :param allow_ignore_quota: If set to true, this voucher can be redeemed even if the event is sold out
+    :param price: If set, the voucher will allow the sale of associated items for this price
+    :param item: If set, the item to sell
+    :param variation: If set, the variation to sell
+    :param quota: If set, the quota to choose an item from
+
+    Various constraints apply:
+
+    * You can either select a quota or an item and you need to select one of those
+    * If you select an item that as variations but not select a variation, you cannot set block_quota
+    """
     event = models.ForeignKey(
         Event,
         on_delete=models.CASCADE,
@@ -116,11 +135,17 @@ class Voucher(LoggedModel):
         self.event.get_cache().delete('vouchers_exist')
 
     def is_ordered(self) -> int:
+        """
+        Returns whether an order position exists that uses this voucher.
+        """
         return OrderPosition.objects.filter(
             voucher=self
         ).exists()
 
     def is_in_cart(self) -> int:
+        """
+        Returns whether a cart position exists that uses this voucher.
+        """
         return CartPosition.objects.filter(
             voucher=self
         ).count()