Shutdown method, added documentation.

example.py

# example of:
#       non-trivial comments
#       object linking using reStructured text class syntax
#       self-documenting methods
@defer_to_detail
def shutdown(self, reason, comment, by_user):
    """ Shuts down the entire order.  After a successful shutdown, the
          shutdown reason, additional free form comments and the user are
          annotated onto the order.

        Special considerations:
            * We don't try to deactivate anything that's is already
            deactivated
            * Bulk order detail is updated with the status reason
            * API orders trigger async return callback

    :param reason:  :py:class:`~extra.Status`
    :param comment: :py:class:`~string` Free text field comment applied
    :param by_user: :py:class:`~django.contrib.auth.auth_user` object
        user who's calling the shutdown method
    :returns: True if order shutdown is successful, otherwise False
    """
    if reason == extra.Status.RETURN:
        if self._validate_vgc_state():  # complex pristine logic here
            self.refund()
    elif reason == self.Status.FRAUD:
        self.notifications.cancel_pending_messages()
    else:
        raise ValueError('Unknown shutdown reason "%s"' % reason)

    self._set_order_status(reason, comment, by_user, reason.context)
    self.activationcallback_set.new_callback(self)

    return True


# example of trivial comment
def _set_order_status(self, reason, comment, by_user, context):
    """ Encapsulates setting the order status. Special bulk considerations """
    if self.product.is_bulk:
        self.order_detail.update_status(reason)
    self.set_status(reason, comment, by_user, context)


# there's enough going on here that's non-trivial
def _validate_vgc_state(self):
    """ Look through each primary vgc (not promo) on the order, looking for
    non-pristine certificates.  This method shortcircut's on the first
    non-pristine egc found.

    :returns: False if any vgc is found as non-pristine, false otherwise.
    """
    deactivated_statuses = [extra.Status.RETURN,
                            extra.Status.DELETED,
                            extra.Status.FRAUD]

    for vgc in self.primary_vgcs.exclude(status__in=deactivated_statuses):
        if vgc.brand.brand_code not in settings.CASHOUT_ALLOWED:
            # --> do some stuff, clipped for brevity <--
            # return False if not pristine

    return True