add some documentation

lib/gnucash.rb

@@ -5,7 +5,12 @@ require "gnucash/transaction"
 require "gnucash/value"
 require "gnucash/version"
 
+# Namespace module for gnucash gem functionality
 module Gnucash
+  # Open a GnuCash book from file.
+  # The file can be either a plain-text XML file or a gzipped XML file.
+  # === Arguments
+  # +fname+ _String_:: Name of the file to open.
   def self.open(fname)
     Book.new(fname)
   end

lib/gnucash/account.rb

@@ -1,10 +1,23 @@
 module Gnucash
+  # Represent a GnuCash account object
   class Account
+    # _String_: The name of the account (unqualified)
     attr_accessor :name
+
+    # _String_: The account type (such as "EXPENSE")
     attr_accessor :type
+
+    # _String_: The GUID of the account
     attr_accessor :id
+
+    # _Array_: List of _AccountTransaction_ transactions associated with this
+    # account.
     attr_accessor :transactions
 
+    # Create an Account object.
+    # === Arguments
+    # +book+ _Book_:: The Gnucash::Book containing the account
+    # +node+ _Nokogiri::XML::Node_:: Nokogiri XML node
     def initialize(book, node)
       @book = book
       @node = node
@@ -17,6 +30,7 @@ module Gnucash
       @balances = []
     end
 
+    # Return the fully qualified account name
     def full_name
       prefix = ""
       if @parent_id
@@ -28,10 +42,13 @@ module Gnucash
       prefix + name
     end
 
+    # Internal method used to associate a transaction with the account
     def add_transaction(act_txn)
       @transactions << act_txn
     end
 
+    # Internal method used to complete initialization of the Account after
+    # all transactions have been associated with it.
     def finalize
       @transactions.sort! { |a, b| a.date <=> b.date }
       balance = Value.new(0)
@@ -44,11 +61,15 @@ module Gnucash
       end
     end
 
+    # Return the final balance of the account as a _Gnucash::Value_
     def final_balance
       return Value.new(0) unless @balances.size > 0
       @balances.last[:value]
     end
 
+    # Return the balance of the account as of the date given as a
+    # _Gnucash::Value_. Transactions that occur on the given date are included
+    # in the returned balance.
     def balance_on(date)
       return Value.new(0) unless @balances.size > 0
       return Value.new(0) if @balances.first[:date] > date

lib/gnucash/account_transaction.rb

@@ -1,12 +1,21 @@
 module Gnucash
+  # Class to link a transaction object to an Account.
   class AccountTransaction
+    # _Gnucash::Value_: The transaction value for the linked account
     attr_accessor :value
 
+    # Construct an AccountTransaction object.
+    # This method is used internally when building a Transaction object.
+    # === Arguments
+    # +real_txn+ _Gnucash::Transaction_:: The linked Transaction object
+    # +value+ _Gnucash::Value_::
+    #   The value of the Transaction split for this account
     def initialize(real_txn, value)
       @real_txn = real_txn
       @value = value
     end
 
+    # Pass through any missing method calls to the linked Transaction object
     def method_missing(*args)
       @real_txn.send(*args)
     end

lib/gnucash/book.rb

@@ -2,12 +2,24 @@ require "zlib"
 require "nokogiri"
 
 module Gnucash
+  # Represent a GnuCash Book
   class Book
+    # _Array_ of _Gnucash::Account_ objects in the book
     attr_accessor :accounts
+
+    # _Array_ of _Gnucash::Transaction_ objects in the book
     attr_accessor :transactions
+
+    # _String_ in "YYYY-MM-DD" format of the first transaction in the book
     attr_accessor :start_date
+
+    # _String_ in "YYYY-MM-DD" format of the last transaction in the book
     attr_accessor :end_date
 
+    # Construct a Book object.
+    # Normally called internally by Gnucash.open()
+    # === Arguments
+    # +fname+ _String_:: The file name of the GnuCash file to open.
     def initialize(fname)
       begin
         @ng = Nokogiri.XML(Zlib::GzipReader.open(fname).read)
@@ -24,10 +36,22 @@ module Gnucash
       finalize
     end
 
+    # Return a handle to the Account object that has the given GUID.
+    # === Arguments
+    # +id+ _String_:: GUID
+    # === Return
+    # _Gnucash::Account_ or +nil+
     def find_account_by_id(id)
       @accounts.find { |a| a.id == id }
     end
 
+    # Return a handle to the Account object that has the given fully-qualified
+    # name.
+    # === Arguments
+    # +full_name+ _String_::
+    #   Fully-qualified account name (ex: "Expenses::Auto::Gas")
+    # === Return
+    # _Gnucash::Account_ or +nil+
     def find_account_by_full_name(full_name)
       @accounts.find { |a| a.full_name == full_name }
     end

lib/gnucash/transaction.rb

@@ -1,10 +1,22 @@
 module Gnucash
+  # Represent a GnuCash transaction.
+  # Transactions have multiple splits with individual values.
+  # Splits are created as AccountTransaction objects which are associated
+  # with an individual account.
   class Transaction
+    # _String_: The date of the transaction, in ISO format ("YYYY-MM-DD")
     attr_accessor :date
-    attr_accessor :value
+
+    # _String_: The GUID of the transaction
     attr_accessor :id
+
+    # _String_: The description of the transaction
     attr_accessor :description
 
+    # Create a new Transaction object
+    # === Arguments
+    # +book+ _Book_:: The Gnucash::Book containing the transaction
+    # +node+ _Nokogiri::XML::Node_:: Nokogiri XML node
     def initialize(book, node)
       @book = book
       @node = node

lib/gnucash/value.rb

@@ -1,13 +1,24 @@
 module Gnucash
+  # Represent a currency value as an integer so that integer math can be used
+  # for accuracy in computations.
   class Value
     include Comparable
 
+    # _Fixnum_:: The raw, undivided integer value
     attr_accessor :val
 
+    # Create a new Value object with value 0
     def self.zero
       Value.new(0)
     end
 
+    # Construct a Value object
+    # === Arguments
+    # +val+ _String_ or _Fixnum_::
+    #   Either a _String_ in the form "1234/100" or an integer containing the
+    #   raw value
+    # +div+ _Fixnum_::
+    #   The divisor value to use (when +val+ is given as a _Fixnum_)
     def initialize(val, div = 100)
       if val.is_a?(String)
         if val =~ /^(-?\d+)\/(\d+)$/
@@ -24,22 +35,27 @@ module Gnucash
       end
     end
 
+    # Add two Value objects
     def +(other)
       Value.new(@val + other.val)
     end
 
+    # Subtract two Value objects
     def -(other)
       Value.new(@val - other.val)
     end
 
+    # Represent the Value as a string (two decimal places)
     def to_s
       sprintf("%.02f", to_f)
     end
 
+    # Convert the Value to a Float
     def to_f
       @val / @div.to_f
     end
 
+    # Compare two Value objects
     def <=>(other)
       @val <=> other.val
     end

lib/gnucash/version.rb

@@ -1,3 +1,4 @@
 module Gnucash
+  # gem version
   VERSION = "0.0.1"
 end