Update the documentation

bgarret · Dec 20, 2011 · a3923a8 · a3923a8
1 parent 526d818
commit a3923a8
Show file tree

Hide file tree

Showing 8 changed files with 90 additions and 14 deletions.
diff --git a/.gitignore b/.gitignore
@@ -2,3 +2,4 @@
 .bundle
 Gemfile.lock
 pkg/*
+.yardoc
diff --git a/.yardopts b/.yardopts
@@ -0,0 +1 @@
+-m markdown --no-private --plugin rails
diff --git a/README.markdown b/README.markdown
@@ -1,7 +1,8 @@
-In config/environments/production.rb :
+In `config/environments/production.rb` :
 
+    # replace this with your tracker code
     GAR.tracker = "UA-xxxxxx-x"
 
-In your layout, between the `<head>` tag :
+In your layout, in the `<head>` tag :
 
 		<%= analytics_init %>
diff --git a/google-analytics-rails.gemspec b/google-analytics-rails.gemspec
@@ -4,7 +4,7 @@ require "google-analytics-rails/version"
 
 Gem::Specification.new do |s|
   s.name        = "google-analytics-rails"
-  s.version     = Google::Analytics::Rails::VERSION
+  s.version     = GoogleAnalytics::Rails::VERSION
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Benoit Garret"]
   s.email       = ["benoit.garret@gadz.org"]
@@ -15,6 +15,9 @@ Gem::Specification.new do |s|
   s.rubyforge_project = "google-analytics-rails"
 
   s.add_dependency "google_analytics_tools"
+  s.add_development_dependency "yard"
+  s.add_development_dependency "yard-rails"
+  s.add_development_dependency "redcarpet"
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

diff --git a/lib/google-analytics-rails.rb b/lib/google-analytics-rails.rb
@@ -1,16 +1,21 @@
 module GoogleAnalytics
   module Rails
+    # @private
     PLACEHOLDER_TRACKER = "UA-xxxxxx-x"
 
+    # The current tracker id (*UA-xxxxxx-x*).
     mattr_accessor :tracker
+    # @private
     @@tracker = PLACEHOLDER_TRACKER
 
+    # @return [Boolean]
     def self.valid_tracker?
       tracker.blank? || tracker == PLACEHOLDER_TRACKER ? false : true
     end
   end
 end
 
+# Alias for GoogleAnalytics::Rails
 GAR = GoogleAnalytics::Rails
 
 require 'google-analytics-rails/railtie' if defined?(Rails)
diff --git a/lib/google-analytics-rails/railtie.rb b/lib/google-analytics-rails/railtie.rb
@@ -1,7 +1,8 @@
 require 'google-analytics-rails/view_helpers'
 
 module GoogleAnalytics::Rails
-  class Railtie < Rails::Railtie
+  # @private
+  class Railtie < ::Rails::Railtie
     initializer "google-analytics-rails" do
       ActionView::Base.send :include, ViewHelpers
     end

diff --git a/lib/google-analytics-rails/version.rb b/lib/google-analytics-rails/version.rb
@@ -1,7 +1,6 @@
-module Google
-  module Analytics
-    module Rails
-      VERSION = "0.0.1"
-    end
+module GoogleAnalytics
+  module Rails
+    # Gem version
+    VERSION = "0.0.1"
   end
 end
diff --git a/lib/google-analytics-rails/view_helpers.rb b/lib/google-analytics-rails/view_helpers.rb
@@ -1,34 +1,99 @@
 require 'google_analytics_tools'
 
 module GoogleAnalytics::Rails
+  # @example Ecommerce example
+  #
+  #     # create a new transaction
+  #     analytics_add_transaction(
+  #       '1234',           # order ID - required
+  #       'Acme Clothing',  # affiliation or store name
+  #       '11.99',          # total - required
+  #       '1.29',           # tax
+  #       '5',              # shipping
+  #       'San Jose',       # city
+  #       'California',     # state or province
+  #       'USA'             # country
+  #     )
+  #
+  #     # add an item to the transaction
+  #     analytics_add_item(
+  #       '1234',           # order ID - required
+  #       'DD44',           # SKU/code - required
+  #       'T-Shirt',        # product name
+  #       'Green Medium',   # category or variation
+  #       '11.99',          # unit price - required
+  #       '1'               # quantity - required
+  #     )
+  #
+  #     # submit the transaction
+  #     analytics_track_transaction
+  #
   module ViewHelpers
-    def analytics_init(*additionalEvents)
+    # Initializes the Analytics javascript. Put it in the `<head>` tag.
+    #
+    # @param events [Array]
+    #   The page load times and page views are tracked by default, additional events can be added here.
+    # @param options [Hash]
+    # @option options [Boolean] :local (false) Sets the local development mode.
+    #   See http://www.google.com/support/forum/p/Google%20Analytics/thread?tid=741739888e14c07a&hl=en
+    #
+    # @example Set the local bit in development mode
+    #   analytics_init :local => Rails.env.development?
+    #
+    # @example Allow links across domains
+    #   analytics_init [GAQ::Events::SetAllowLinker.new(true)]
+    #
+    # @return [String] a `<script>` tag, containing the analytics initialization sequence.
+    #
+    def analytics_init(events = [], options = {})
       raise ArgumentError, "Tracker must be set! Did you set GAR.tracker ?" unless GAR.valid_tracker?
 
+      local = options.delete(:local) || false
+
       queue = GAQ.new
-      queue << GAQ::Events::SetAccount.new(GAR.tracker)
-      queue << GAQ::Events::TrackPageview.new
-      queue << GAQ::Events::TrackPageLoadTime.new
 
-      additionalEvents.each do |event|
+      # unshift => reverse order
+      events.unshift GAQ::Events::TrackPageLoadTime.new
+      events.unshift GAQ::Events::TrackPageview.new
+      events.unshift GAQ::Events::SetAccount.new(GAR.tracker)
+
+      if local
+        events.push GAQ::Events::SetDomainName.new('none')
+        events.push GAQ::Events::SetAllowLinker.new(true)
+      end
+
+      events.each do |event|
         queue << event
       end
 
       queue.to_s.html_safe
     end
 
+    # Track a custom event
+    # @see http://code.google.com/apis/analytics/docs/tracking/eventTrackerGuide.html
+    #
+    # @example
+    #
+    #     analytics_track_event "Videos", "Play", "Gone With the Wind"
+    #
     def analytics_track_event(category, action, label, value)
       analytics_render_event(GAQ::Events::TrackEvent.new(category, action, label, value))
     end
 
+    # Track an ecommerce transaction
+    # @see http://code.google.com/apis/analytics/docs/tracking/gaTrackingEcommerce.html
     def analytics_add_transaction(order_id, store_name, total, tax, shipping, city, state_or_province, country)
       analytics_render_event(GAQ::Events::ECommerce::AddTransaction.new(order_id, store_name, total, tax, shipping, city, state_or_province, country))
     end
 
+    # Add an item to the current transaction
+    # @see http://code.google.com/apis/analytics/docs/tracking/gaTrackingEcommerce.html
     def analytics_add_item(order_id, product_id, product_name, product_variation, unit_price, quantity)
       analytics_render_event(GAQ::Events::ECommerce::AddItem.new(order_id, product_id, product_name, product_variation, unit_price, quantity))
     end
 
+    # Flush the current transaction
+    # @see http://code.google.com/apis/analytics/docs/tracking/gaTrackingEcommerce.html
     def analytics_track_transaction
       analytics_render_event(GAQ::Events::ECommerce::TrackTransaction.new)
     end