lib/recurly/invoice.rb in recurly-2.10.1 vs lib/recurly/invoice.rb in recurly-2.10.2

@@ -1,10 +1,12 @@
 module Recurly
   # Invoices are created through account objects.
   #
+  # Recurly Documentation: https://dev.recurly.com/docs/list-invoices
+  #
   # @example
-  #   account = Account.find account_code
+  #   account = Account.find(account_code)
   #   account.invoice!
   class Invoice < Resource
     # @macro [attach] scope
     #   @scope class
     #   @return [Pager<Invoice>] A pager that yields +$1+ invoices.
@@ -13,29 +15,37 @@
     scope :failed,    :state => :failed
     scope :past_due,  :state => :past_due
 
     # @return [Account]
     belongs_to :account
+
     # @return [Subscription]
     belongs_to :subscription
+
     # @return [Invoice]
     belongs_to :original_invoice, class_name: :Invoice
 
     # This will only be present if the invoice has > 500 line items
-    # @return [Adjustment]
+    # @return [Pager<Adjustment>, []]
     has_many :all_line_items, class_name: :Adjustment
 
-    # @return [Redemption]
+    # @return [Pager<Redemption>, []]
     has_many :redemptions
 
-    # return [ShippingAddress]
+    # @return [Pager<ShippingAddress>, [ShippingAddress], []]
     has_one :shipping_address, resource_class: :ShippingAddress, readonly: true
 
+    # Returns the first redemption in the Invoice's redemptions.
+    # This was placed here for backwards compatibility when we went from
+    # having a single redemption per invoice to multiple redemptions per invoice.
+    #
+    # @deprecated Use {#redemptions} and find the redemption you want.
     def redemption
       redemptions.first
     end
 
+    # @return [String] The invoice number with the prefix (if there is one)
     def invoice_number_with_prefix
       "#{invoice_number_prefix}#{invoice_number}"
     end
 
     define_attribute_methods %w(
@@ -105,17 +115,22 @@
       return false unless link? :force_collect
       reload follow_link :force_collect
       true
     end
 
+    # Posts an offline payment on this invoice
+    #
+    # @return [Transaction]
+    # @raise [Error] If the transaction fails.
     def enter_offline_payment(attrs={})
       Transaction.from_response API.post("#{uri}/transactions", attrs.empty? ? nil : Transaction.to_xml(attrs))
     rescue Recurly::API::UnprocessableEntity => e
       raise Invalid, e.message
     end
 
+    # Fetches the pdf for this invoice
     def pdf
-      self.class.find to_param, :format => 'pdf'
+      self.class.find(to_param, format: 'pdf')
     end
 
     # Refunds specific line items on the invoice.
     #
     # @return [Invoice, false] A new refund invoice, false if the invoice isn't