Add some documentation

README.rdoc

@@ -13,11 +13,23 @@ The github repository: http://github.com/hanklords/flickraw/tree/master
 Type this in a console (you might need to be superuser)
  gem install flickraw
 
-You can recreate this documentation by typing this in the source directory:
+This will recreate the documentation by fetching the methods descriptions from flickr and then virtually plugging them in standard rdoc documentation.
  rake rdoc
 
+= Features
+
+* Small single file: flickraw.rb is less than 300 lines
+* Complete support of flickr API. This doesn't require an update of the library
+* Ruby syntax similar to the flickr api
+* Flickr authentication
+* Photo upload
+* Proxy support
+* Delayed library loading (for rails users)
+
 = Usage
 
+== Simple
+
  require 'flickraw'
 
  list   = flickr.photos.getRecent
@@ -35,6 +47,70 @@ You can recreate this documentation by typing this in the source directory:
  original = sizes.find {|s| s.label == 'Original' }
  original.width       # => "800"
 
+== Authentication
+
+  require 'flickraw'
+
+  FlickRaw.api_key="... Your API key ..."
+  FlickRaw.shared_secret="... Your shared secret ..."
+
+  frob = flickr.auth.getFrob
+  auth_url = FlickRaw.auth_url :frob => frob, :perms => 'read'
+
+  puts "Open this url in your process to complete the authication process : #{auth_url}"
+  puts "Press Enter when you are finished."
+  STDIN.getc
+
+  begin
+    flickr.auth.getToken :frob => frob
+    login = flickr.test.login
+    puts "You are now authenticated as #{login.username}"
+  rescue FlickRaw::FailedResponse => e
+    puts "Authentication failed : #{e.msg}"
+  end
+
+You don't need to do that each time, you can reuse your token:
+
+  require 'flickraw'
+
+  FlickRaw.api_key="... Your API key ..."
+  FlickRaw.shared_secret="... Your shared secret ..."
+
+  auth = flickr.auth.checkToken :auth_token => "... Your saved token ..."
+
+  # From here you are logged:
+  puts auth.user.username
+
+== Upload
+
+  require 'flickraw'
+
+  FlickRaw.api_key="... Your API key ..."
+  FlickRaw.shared_secret="... Your shared secret ..."
+
+  PHOTO_PATH='photo.jpg'
+
+  # You need to be authentified to do that, see the previous examples.
+  flickr.upload_photo PHOTO_PATH, :title => "Title", :description => "This is the description"
+
+== Flickraw Options
+
+You can pass some options to modify flickraw behavior:
+
+  FlickrawOptions = {
+    :lazyload => true,     # This delay the loading of the library until the first call
+
+    # Proxy support. alternatively, you can use the http_proxy environment variable
+    :proxy_host => "proxy_host",
+    :proxy_port => "proxy_port",
+    :proxy_user => "proxy_user",
+    :proxy_password => "proxy_password",
+
+    :timeout => 5          # Set the request timeout
+  }
+  require 'flickraw'
+
+
 See the _examples_ directory to find more examples.
 
 = Notes

lib/flickraw.rb

@@ -25,7 +25,7 @@
 require 'json'
 require 'cgi'
 
-FlickrawOptions = {} if not Object.const_defined? :FlickrawOptions
+FlickrawOptions = {} if not Object.const_defined? :FlickrawOptions # :nodoc:
 if ENV['http_proxy'] and not FlickrawOptions[:proxy_host]
   proxy = URI.parse ENV['http_proxy']
   FlickrawOptions.update(:proxy_host => proxy.host, :proxy_port => proxy.port, :proxy_user => proxy.user, :proxy_password => proxy.password)