lib/rockstar/auth.rb in rockstar-0.6.3 vs lib/rockstar/auth.rb in rockstar-0.6.4

@@ -1,18 +1,35 @@
 module Rockstar
-  
+
+  # = Authentification
+  #
+  # There are 2 ways to get an auth token :
+  #
+  # == Desktop-App
+  # 1. Get a new token to request authorisation:
+  #     token = Rockstar::Auth.new.token
+  # 2. Open a webbrowser with http://www.last.fm/api/auth/?api_key=xxxxxxxxxxx&token=xxxxxxxx
+  # 3. Wait for the User to confirm that he accepted your request.
+  # 4. Continue with "Get the session token"
+  #
+  # == Web-App
+  # 1. Redirect the user to http://www.last.fm/api/auth/?api_key={YOUR_API_KEY}&cb={YOUR_RETURN_URL}
+  # 2. If the user accepts, lastfm will redirect to YOUR_RETURN_URL?token=TOKEN
+  #     token = params[:token]
+  # 3. Continue with "Get the session token"
+  #
+  # == Get the session token
+  # 1. Use the previous token and call
+  #     session = Rockstar::Auth.new.session(token)
+  # 2. Store the session.key and session.username returned. The session.key will not
+  #    expire. It is save to store it into your database.
   class Auth < Base
-    # Returns the token for a session. You have to use
-    # TokenAuth first and then use this class with the token
-    # that is given by last.fm to create a session token
-    # This session token can be stored in your database, it is
-    # not expiring.
-    # See Rockstar::TokenAuth for a detailed example
+
     def session(token)
       doc = self.class.fetch_and_parse("auth.getSession", {:token => token}, true)
       Rockstar::Session.new_from_xml(doc)
     end
-    
+
     def token
       doc = self.class.fetch_and_parse("auth.getToken", {}, true)
       token = (doc).at(:token).inner_html if (doc).at(:token)
       token
     end