+__END__
+
+=pod
+
+=encoding utf8
+
+=head1 NAME
+
+SL::DB::PeriodicInvoicesConfig - DB model for the configuration for periodic invoices
+
+=head1 FUNCTIONS
+
+=over 4
+
+=item C<calculate_invoice_dates %params>
+
+Calculates dates for which invoices will have to be created. Returns a
+list of L<DateTime> objects.
+
+This function looks at the configuration settings and at the list of
+invoices that have already been created for this configuration. The
+date range for which dates are created are controlled by several
+values:
+
+=over 2
+
+=item * The properties C<first_billing_date> and C<start_date>
+determine the start date.
+
+=item * The properties C<end_date> and C<terminated> determine the end
+date.
+
+=item * The optional parameter C<past_dates> determines whether or not
+dates for which invoices have already been created will be included in
+the list. The default is not to include them.
+
+=item * The optional parameters C<start_date> and C<end_date> override
+the start and end dates from the configuration.
+
+=item * If no end date is set or implied via the configuration and no
+C<end_date> parameter is given then the function will use 100 years
+in the future as the end date.
+
+=back
+
+=item C<get_billing_period_length>
+
+Returns the number of months corresponding to the billing
+periodicity. This means that a new invoice has to be created every x
+months starting with the value in C<first_billing_date> (or
+C<start_date> if C<first_billing_date> is unset).
+
+=item C<get_order_value_period_length>
+
+Returns the number of months the order's value refers to. This looks
+at the C<order_value_periodicity>.
+
+Each invoice's value is calculated as C<order value *
+billing_period_length / order_value_period_length>.
+
+=item C<get_previous_billed_period_start_date>
+
+Returns the highest date (as an instance of L<DateTime>) for which an
+invoice has been created from this configuration.
+
+=item C<handle_automatic_extension>
+
+Configurations which haven't been terminated and which have an end
+date set may be eligible for automatic extension by a certain number
+of months. This what the function implements.
+
+If the configuration is not eligible or if the C<end_date> hasn't been
+reached yet then nothing is done and C<undef> is returned. Otherwise
+its behavior is determined by the C<extend_automatically_by> property.
+
+If the property C<extend_automatically_by> is not 0 then the
+C<end_date> will be extended by C<extend_automatically_by> months, and
+the configuration will be saved. In this case the new end date will be
+returned.
+
+Otherwise (if C<extend_automatically_by> is 0) the property C<active>
+will be set to 1, and the configuration will be saved. In this case
+C<undef> will be returned.
+
+=item C<is_last_billing_date_in_order_value_cycle %params>
+
+Determines whether or not the mandatory parameter C<date>, an instance
+of L<DateTime>, is the last billing date within the cycle given by the
+order value periodicity. Returns a truish value if this is the case
+and a falsish value otherwise.
+
+This check is always true if the billing periodicity is longer than or
+equal to the order value periodicity. For example, if you have an
+order whose value is given for three months and you bill every six
+months and you have twice the order value on each invoice, meaning
+each invoice is itself the last invoice for not only one but two order
+value cycles.
+
+Otherwise (if the order value periodicity is longer than the billing
+periodicity) this function iterates over all eligible dates starting
+with C<first_billing_date> (or C<start_date> if C<first_billing_date>
+is unset) and adding the order value length with each step. If the
+date given by the C<date> parameter plus the billing period length
+equals one of those dates then the given date is indeed the date of
+the last invoice in that particular order value cycle.
+
+=item C<sub disable_one_time_config>
+
+Sets the state of the periodic_invoices_configs to inactive
+(active => false) if the periodicity is <Co> (one time).
+Returns undef if the periodicity is not 'one time' otherwise the
+order number of the deactivated periodic order.
+
+=back
+
+=head1 BUGS
+
+Nothing here yet.
+
+=head1 AUTHOR
+
+Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
+
+=cut