created all RDoc and fix some method

README.rdoc

@@ -1,16 +1,47 @@
-== THIS GEM IS UNDER DEVELOPMENT
-
-= campaigning
+= Campaigning
 
 This RubyGem provides access to the CampaignMonitor API(www.campaignmonitor.com/api) using SOAP.
 
-== Dependencies
-This gem requires the following gems
+
+== Pre-requisites
+An account with Campaign Monitor and the API Key (www.campaignmonitor.com).
+
+
+== Resources
+
+=== Dependencies
+
+This gem requires the following gems:
 
  Soap4r (1.5.8)
 
  Jeweler (http://technicalpickles.com/posts/craft-the-perfect-gem-with-jeweler)
 
+=== Installing
+
+  sudo gem install gnumarcelo-campaigning -s http://gems.github.com
+
+
+== How to play
+
+Just set a constant named *CAMPAIGN_MONITOR_API_KEY* with your Campaign monitor API key and start to play like the examples below:
+
+Sample use of the Client class:
+
+  #Here is how to get a list of all clients...
+  clients = Campaigning::Client.get_all_clients
+
+
+  #Here is how to create a brand new subscriber list for an Client
+  client = Campaigning::Client.find_by_name("Client One Company")
+  list = Campaigning::List.create(
+    :client_id => client.clientID,
+    :title => "List of people from Brazil",
+    :comfirm_opt_in => false
+  )
+
+For further examples please check at the *sample* directory.
+
 
 == Copyright
 

Rakefile

@@ -53,5 +53,7 @@ Rake::RDocTask.new do |rdoc|
   rdoc.title = "campaigning #{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.exclude('lib/campaigning/soap/generated/*.rb')
+  rdoc.options << "--inline-source"
 end
 

campaigning.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{campaigning}
-  s.version = "0.6.0"
+  s.version = "0.7.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Marcelo Menezes"]
-  s.date = %q{2009-05-07}
+  s.date = %q{2009-05-15}
   s.email = %q{gnumarcelo@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE",

lib/campaigning/campaigning.rb

@@ -7,37 +7,29 @@
 require File.expand_path(File.dirname(__FILE__)) + '/helpers/helpers.rb'
 
 module Campaigning
-class Base
   include Helpers
-  attr_reader :api_key 
 
-  def initialize(options = {})
-    options = {
-      :api_key => CAMPAIGN_MONITOR_API_KEY,
-      :debug => false
-    }.merge(options)
-    @api_key = options[:api_key]
-    @soap = Campaigning::SOAPDriver.instance.get_driver
-    setup_debug_mode options[:debug]
+  #Gets the server system time for your time zone.
+  #This is handy for when you are syncing your {Campaign Monitor}[http://www.campaignmonitor.com] lists with some other in-house list,
+  #allowing you accurately determine the time on our server when you carry out the synchronization.
+  def self.system_date
+    response = Campaigning::SOAPDriver.instance.get_driver.getSystemDate(:apiKey => CAMPAIGN_MONITOR_API_KEY)
+    dateTime = Helpers.handle_request response.user_GetSystemDateResult
   end
-
-  def clients
-    response = @soap.getClients(:apiKey => @api_key)
-    clients = handle_request response.user_GetClientsResult
-    clients.collect {|client| Client.new(client.clientID, client.name)}
-  end
-
-  def system_date
-    handle_request @soap.getSystemDate(:apiKey => @api_key).user_GetSystemDateResult
+
+  #This method returns an Array of Strings representing all the available timezones.
+  def self.time_zones
+    Helpers.handle_request Campaigning::SOAPDriver.instance.get_driver.getTimezones(:apiKey => CAMPAIGN_MONITOR_API_KEY).user_GetTimezonesResult
   end
 
-  def time_zones
-    handle_request @soap.getTimezones(:apiKey => @api_key).user_GetTimezonesResult
+  #This method returns an Array of Strings representing all the available countries.
+  def self.countries
+    response = Campaigning::SOAPDriver.instance.get_driver.getCountries(:apiKey => CAMPAIGN_MONITOR_API_KEY)
+    dateTime = Helpers.handle_request response.user_GetCountriesResult
   end
 
-  def setup_debug_mode(dev)
+  #This method turns on and off the API debug mode, which will display at the console all SOAP requests made to the API server.
+  def self.setup_debug_mode(dev)
     Campaigning::SOAPDriver.instance.setup_debug_mode dev
-  end
-
-end
+  end    
 end

lib/campaigning/helpers/helpers.rb

@@ -1,14 +1,19 @@
-  module Helpers
-
-    def handle_request(response)
-      Helpers.handle_request response
+module Campaigning
+module Helpers
+  #Method responsable to handle all response from the API server and raising an exception when
+  #the API returns an error code (different from 0 (zero) ).
+  def handle_request(response)
+    Helpers.handle_request response
+  end
+
+  #Method responsable to handle all response from the API server and raising an exception when
+  #the API returns an error code (different from 0 (zero) ).
+  def Helpers.handle_request(response)
+    if (response.class == Campaigning::Result && response.code != 0)
+       raise response.code.to_s + " - " + response.message
     end
-
-    def Helpers.handle_request(response)
-      if (response.class == Campaigning::Result && response.code != 0)
-         raise response.code.to_s + " - " + response.message
-      end
-      response
-    end
-
-  end
+    response
+  end
+
+end
+end

lib/campaigning/soap/soap_driver.rb

@@ -2,14 +2,20 @@
 require 'singleton'
 
 module Campaigning
+  #A SOAPDriver is a singleton object responsable to supply a way to interact with the SOAP::RPC::Driver object.
   class SOAPDriver #It could be a module
     include Singleton
     DefaultEndpointUrl = "http://api.createsend.com/api/api.asmx"
 
+    #Return a unique Campaigning::SOAP::ApiSoap instance for the whole API client, which provides access to
+    #all the Campaign Monitor API methods.
     def get_driver
       @driver ||= Campaigning::ApiSoap.new(DefaultEndpointUrl)
     end
 
+    #This method turns the API debug mode to _on_ and _off_.
+    #When method called with _true_ argument, it will switch to _on_ mode, the API will display at the console all
+    #SOAP requests made to the API server.
     def setup_debug_mode(dev)
       dev = STDERR if dev == true
       @driver.wiredump_dev = dev

lib/campaigning/types/campaign.rb

@@ -20,6 +20,29 @@ def initialize(campaignID = nil, subject = nil, sentDate = nil, totalRecipients
       @soap = Campaigning::SOAPDriver.instance.get_driver
     end
 
+    #Creates a campaign for an existing client. This campaign will be imported and ready to send to the subscribers in
+    #the specified lists and segments.
+    #The campaign must have both HTML and plain text content, imported from the internet. Styling for the HTML content
+    #will be automatically brought inline.
+    #
+    #Available _params_ argument are:
+    #   * :clientID - The ID of the Client you want to create a campaign
+    #   * :campaignName - The name of the new campaign. This must be unique across all draft campaigns for the client.
+    #   * :campaignSubject - The subject of the new campaign.
+    #   * :fromName - The name to appear in the From field in the recipients email client when they receive the new campaign.
+    #   * :fromEmail - The email address that the new campaign will come from.
+    #   * :replyTo - The email address that any replies to the new campaign will be sent to.
+    #   * :htmlUrl - The URL of the HTML content for the new campaign. If no unsubscribe link is found then one will be added automatically. Styling in
+    #                the campaign will be automatically brought inline. If your URL has querystring values, you will need to encode them.
+    #   * :textUrl - The URL of the Text content for the new campaign. If no unsubscribe link is found then one will be added automatically.
+    #   * :subscriberListIDs - An array of lists to send the campaign to. See http://www.campaignmonitor.com/api/required/#listid for more details.
+    #   * :listSegments - An array of Segment Names and their appropriate List ID s to send the campaign to.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Campaign object which was recently created.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.    
     def self.create(params)  
         response = Campaigning::SOAPDriver.instance.get_driver.createCampaign(
            :apiKey => CAMPAIGN_MONITOR_API_KEY,
@@ -39,36 +62,118 @@ def self.create(params)
         Campaign.new campaign_id
     end
 
+    #Gets a list of all subscribers who bounced for a given campaign, and the type of bounce (H=Hard Bounce, S=Soft Bounce).
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a collection of <code>SubscriberBounce</code> objects, each of
+    #which consists of the subscribers <code>:emailAddress</code>, the <code>listID</code> they belong to, and the <code>bounceType</code>
+    #of bounce they experienced, whether hard or soft.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
     def bounces
       response = @soap.getCampaignBounces(:apiKey => CAMPAIGN_MONITOR_API_KEY, :campaignID => @campaignID )
       handle_request response.campaign_GetBouncesResult
     end
 
+    #Returns an array of Campaigning::List objects that a given campaign was sent to.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a collection of Campaigning::List object.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
     def lists
       response = @soap.getCampaignLists(:apiKey => CAMPAIGN_MONITOR_API_KEY, :campaignID => @campaignID )
-      handle_request response.campaign_GetListsResult
+      lists = handle_request response.campaign_GetListsResult
+      puts "LISTAS!!!!!!!!!!" + lists.inspect
+      lists.collect do |list|  
+        List.new(list.listID, list.name)
+      end
     end
 
+    #Gets a list of all subscribers who opened a given campaign, and the number of times they opened the campaign.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a collection of <code>SubscriberOpen</code> objects, each of
+    #which consists of the subscribers <code>:emailAddress</code>, the <code>listID</code> they belong to, and the <code>numberOfOpens</code>
+    #representing the number of times they opened the given campaign.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
     def opens
       response = @soap.getCampaignOpens(:apiKey => CAMPAIGN_MONITOR_API_KEY, :campaignID => @campaignID )
       handle_request response.campaign_GetOpensResult
     end
 
+    #Gets a list of all subscribers who clicked a link for a given campaign, the ID of the list they belong to,
+    #the links they clicked, and the number of times they clicked the link.
+    #
+    #Example of usage:
+    #
+    # campaign_obj.subscriber_clicks.each do |subscriber|
+    #   puts "Subscriber: #{subscriber.emailAddress}"
+    #   subscriber.clickedLinks.each do |clicked| 
+    #     puts "Clicked link: #{clicked.link} - Number of clicks: #{clicked.clicks}"
+    #   end
+    # end
+    #
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a collection of <code>SubscriberClick</code> objects, each of which consists of
+    #the subscribers <code>emailAddress</code>, the <code>listID</code> representing list they belong to, and the <code>clickedLinks</code>array 
+    #representing the links they have clicked and the number of times they clicked each link.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
     def subscriber_clicks
       response = @soap.getSubscriberClicks(:apiKey => CAMPAIGN_MONITOR_API_KEY, :campaignID => @campaignID )
       handle_request response.campaign_GetSubscriberClicksResult
     end
 
+    #Gets a statistical summary, including number of recipients and open count, for a given campaign.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return summary statistical values about this particular campaign
+    #including the number of recipients, the number of total opens, the number of link clicks, the number of recipients
+    #who unsubscribed and the number who bounced.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
     def summary
       response = @soap.getCampaignSummary(:apiKey => CAMPAIGN_MONITOR_API_KEY, :campaignID => @campaignID )
       handle_request response.campaign_GetSummaryResult
     end
 
+    #Gets a list of all subscribers who unsubscribed for a given campaign.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a collection of SubscriberUnsubscribe objects, each of which consists
+    #of the <code>emailAddress</code> representing subscribers email address and the <code>listID</code> representing the list they belong to.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
     def unsubscribes
       response = @soap.getCampaignUnsubscribes(:apiKey => CAMPAIGN_MONITOR_API_KEY, :campaignID => @campaignID )
       handle_request response.campaign_GetUnsubscribesResult
     end
 
+    #Schedules an existing campaign for sending.
+    #
+    #The campaign must be imported with defined recipients. For campaigns with more than 5 recipients the user must have
+    #sufficient credits or their credit card details saved within the application for the campaign to be sent via the API.
+    #For campaigns with 5 recipients or less the user must have enough test campaigns remaining in their API account.
+    #For further information about credits for campaigns please check at: http://www.campaignmonitor.com/api/method/campaign-send/
+    #
+    #Available _params_ argument are:
+    #   * :confirmation_email - The email address that the confirmation email that the campaign has been sent will go to.
+    #   * :send_date - The date the campaign should be scheduled to be sent. To send a campaign immediately pass in "Immediately".
+    #                  This date should be in the users timezone and formatted as YYYY-MM-DD HH:MM:SS.
+    #
+    #*Return*:
+    #Upon a successful call, this method will return a Result object with the newly create Campaign's ID as the Code.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
     def send(params)
       response = @soap.sendCampaign(
         :apiKey => CAMPAIGN_MONITOR_API_KEY,