From 59f16bfddaa2b7c3c8f7d7113108eaea202d1c9b Mon Sep 17 00:00:00 2001
From: Pablo Fernandez <fernandezpablo85@gmail.com>
Date: Sun, 24 Oct 2010 11:48:21 -0300
Subject: [PATCH] Added bunch of javadocs and restricted some visibility.

No functional changes
---
 .../org/scribe/builder/ServiceBuilder.java    |  3 +
 src/main/java/org/scribe/builder/api/Api.java | 11 ----
 .../org/scribe/builder/api/DefaultApi10a.java | 66 ++++++++++++++-----
 .../org/scribe/builder/api/FoursquareApi.java |  4 +-
 .../org/scribe/builder/api/GoogleApi.java     |  4 +-
 .../org/scribe/builder/api/LinkedInApi.java   |  6 +-
 .../org/scribe/builder/api/TwitterApi.java    |  4 +-
 .../java/org/scribe/builder/api/VimeoApi.java |  4 +-
 .../java/org/scribe/builder/api/YahooApi.java |  4 +-
 .../org/scribe/exceptions/OAuthException.java | 17 ++++-
 .../OAuthParametersMissingException.java      | 10 +++
 .../exceptions/OAuthSignatureException.java   | 11 ++++
 .../LinkedInBaseStringExtractorImpl.java      |  8 +++
 .../extractors/AccessTokenExtractor.java      | 11 ++++
 .../extractors/BaseStringExtractor.java       | 13 ++++
 .../extractors/BaseStringExtractorImpl.java   |  9 +++
 .../scribe/extractors/HeaderExtractor.java    | 11 ++++
 .../extractors/HeaderExtractorImpl.java       |  9 +++
 .../extractors/RequestTokenExtractor.java     | 12 +++-
 .../scribe/extractors/TokenExtractorImpl.java | 11 +++-
 .../java/org/scribe/model/OAuthConfig.java    |  5 ++
 .../java/org/scribe/model/OAuthConstants.java |  1 -
 src/main/java/org/scribe/model/Request.java   |  1 -
 src/main/java/org/scribe/model/Response.java  |  6 --
 src/main/java/org/scribe/model/Token.java     | 12 +++-
 src/main/java/org/scribe/model/Verifier.java  | 11 +++-
 .../java/org/scribe/oauth/OAuthService.java   | 35 ++++++++++
 .../services/HMACSha1SignatureService.java    | 13 +++-
 .../org/scribe/services/SignatureService.java | 20 ++++++
 .../org/scribe/services/TimestampService.java | 18 ++++-
 .../scribe/services/TimestampServiceImpl.java | 24 ++++++-
 src/main/java/org/scribe/utils/MapUtils.java  | 12 +++-
 .../java/org/scribe/utils/Preconditions.java  | 35 +++++++++-
 .../java/org/scribe/utils/StreamUtils.java    | 12 +++-
 src/main/java/org/scribe/utils/URLUtils.java  | 24 ++++++-
 35 files changed, 393 insertions(+), 64 deletions(-)

diff --git a/src/main/java/org/scribe/builder/ServiceBuilder.java b/src/main/java/org/scribe/builder/ServiceBuilder.java
index 18f365e..59368d4 100644
--- a/src/main/java/org/scribe/builder/ServiceBuilder.java
+++ b/src/main/java/org/scribe/builder/ServiceBuilder.java
@@ -22,6 +22,9 @@ public class ServiceBuilder
   private Api api;
   private String scope;
   
+  /**
+   * Default constructor
+   */
   public ServiceBuilder()
   {
     this.callback = OAuthConstants.OUT_OF_BAND;
diff --git a/src/main/java/org/scribe/builder/api/Api.java b/src/main/java/org/scribe/builder/api/Api.java
index 9a568a9..0202098 100644
--- a/src/main/java/org/scribe/builder/api/Api.java
+++ b/src/main/java/org/scribe/builder/api/Api.java
@@ -10,17 +10,6 @@ import org.scribe.oauth.*;
  */
 public interface Api
 {  
-  /**
-   * Creates an {@link OAuthService}
-   * 
-   * @param apiKey your application api key
-   * @param apiSecret your application api secret
-   * @param callback the callback url (or 'oob' for out of band OAuth)
-   * 
-   * @return fully configured {@link OAuthService}
-   */
-  OAuthService createService(String apiKey, String apiSecret, String callback);
-  
   /**
    * Creates an {@link OAuthService}
    * 
diff --git a/src/main/java/org/scribe/builder/api/DefaultApi10a.java b/src/main/java/org/scribe/builder/api/DefaultApi10a.java
index c5d0a54..b2a39e2 100644
--- a/src/main/java/org/scribe/builder/api/DefaultApi10a.java
+++ b/src/main/java/org/scribe/builder/api/DefaultApi10a.java
@@ -5,52 +5,89 @@ import org.scribe.model.*;
 import org.scribe.oauth.*;
 import org.scribe.services.*;
 
+/**
+ * Default implementation of the OAuth protocol, version 1.0a
+ * 
+ * This class is meant to be extended by concrete implementations of the API.
+ * If your Api adheres to the 1.0a protocol correctly, you just need to extend 
+ * this class and define the getters for your endpoints.
+ * 
+ * @author Pablo Fernandez
+ *
+ */
 public abstract class DefaultApi10a implements Api
 {
-  public AccessTokenExtractor getAccessTokenExtractor()
+  
+  protected AccessTokenExtractor getAccessTokenExtractor()
   {
     return new TokenExtractorImpl();
   }
 
-  public BaseStringExtractor getBaseStringExtractor()
+  protected BaseStringExtractor getBaseStringExtractor()
   {
     return new BaseStringExtractorImpl();
   }
 
-  public HeaderExtractor getHeaderExtractor()
+  protected HeaderExtractor getHeaderExtractor()
   {
     return new HeaderExtractorImpl();
   }
 
-  public RequestTokenExtractor getRequestTokenExtractor()
+  protected RequestTokenExtractor getRequestTokenExtractor()
   {
     return new TokenExtractorImpl();
   }
 
-  public SignatureService getSignatureService()
+  protected SignatureService getSignatureService()
   {
     return new HMACSha1SignatureService(); 
   }
 
-  public TimestampService getTimestampService()
+  protected TimestampService getTimestampService()
   {
     return new TimestampServiceImpl();
   }
   
-  public Verb getAccessTokenVerb()
+  protected Verb getAccessTokenVerb()
   {
     return Verb.POST;
   }
   
-  public Verb getRequestTokenVerb()
+  protected Verb getRequestTokenVerb()
   {
     return Verb.POST;
   }
   
-  public abstract String getRequestTokenEndpoint();
-  public abstract String getAccessTokenEndpoint();
+  /**
+   * Returns the URL that receives the request token requests.
+   * 
+   * @return request token URL
+   */
+  protected abstract String getRequestTokenEndpoint();
   
-  public OAuthService createService(String apiKey, String apiSecret, String callback)
+  /**
+   * Returns the URL that receives the access token requests.
+   * 
+   * @return access token URL
+   */
+  protected abstract String getAccessTokenEndpoint();
+  
+  /**
+   * Returns the {@link OAuthService} for this Api
+   * 
+   * @param apiKey Key
+   * @param apiSecret Api Secret
+   * @param callback OAuth callback (either URL or 'oob')
+   * @param scope OAuth scope (optional) 
+   */
+  public OAuthService createService(String apiKey, String apiSecret, String callback, String scope)
+  {
+    OAuthService service = createService(apiKey, apiSecret, callback);
+    service.addScope(scope);
+    return service;
+  }
+  
+  private OAuthService createService(String apiKey, String apiSecret, String callback)
   {
     return new OAuth10aServiceImpl( getSignatureService(), 
                                     getTimestampService(), 
@@ -61,13 +98,6 @@ public abstract class DefaultApi10a implements Api
                                     createConfig(apiKey, apiSecret, callback));
   }
   
-  public OAuthService createService(String apiKey, String apiSecret, String callback, String scope)
-  {
-    OAuthService service = createService(apiKey, apiSecret, callback);
-    service.addScope(scope);
-    return service;
-  }
-
   private OAuthConfig createConfig(String apiKey, String apiSecret, String callback)
   {
     OAuthConfig config = new OAuthConfig();
diff --git a/src/main/java/org/scribe/builder/api/FoursquareApi.java b/src/main/java/org/scribe/builder/api/FoursquareApi.java
index 2d5b5a8..1a30808 100644
--- a/src/main/java/org/scribe/builder/api/FoursquareApi.java
+++ b/src/main/java/org/scribe/builder/api/FoursquareApi.java
@@ -3,13 +3,13 @@ package org.scribe.builder.api;
 public class FoursquareApi extends DefaultApi10a
 {
   @Override
-  public String getAccessTokenEndpoint()
+  protected String getAccessTokenEndpoint()
   {
     return "http://foursquare.com/oauth/access_token";
   }
 
   @Override
-  public String getRequestTokenEndpoint()
+  protected String getRequestTokenEndpoint()
   {
     return "http://foursquare.com/oauth/request_token";
   }
diff --git a/src/main/java/org/scribe/builder/api/GoogleApi.java b/src/main/java/org/scribe/builder/api/GoogleApi.java
index 1d9c886..30980b8 100644
--- a/src/main/java/org/scribe/builder/api/GoogleApi.java
+++ b/src/main/java/org/scribe/builder/api/GoogleApi.java
@@ -3,13 +3,13 @@ package org.scribe.builder.api;
 public class GoogleApi extends DefaultApi10a
 {
   @Override
-  public String getAccessTokenEndpoint()
+  protected String getAccessTokenEndpoint()
   {
     return "https://www.google.com/accounts/OAuthGetAccessToken"; 
   }
 
   @Override
-  public String getRequestTokenEndpoint()
+  protected String getRequestTokenEndpoint()
   {
     return "https://www.google.com/accounts/OAuthGetRequestToken";
   }
diff --git a/src/main/java/org/scribe/builder/api/LinkedInApi.java b/src/main/java/org/scribe/builder/api/LinkedInApi.java
index bf31010..b02a31e 100644
--- a/src/main/java/org/scribe/builder/api/LinkedInApi.java
+++ b/src/main/java/org/scribe/builder/api/LinkedInApi.java
@@ -7,19 +7,19 @@ public class LinkedInApi extends DefaultApi10a
 {
 
   @Override
-  public String getAccessTokenEndpoint()
+  protected String getAccessTokenEndpoint()
   {
     return "https://api.linkedin.com/uas/oauth/accessToken";
   }
 
   @Override
-  public String getRequestTokenEndpoint()
+  protected String getRequestTokenEndpoint()
   {
     return "https://api.linkedin.com/uas/oauth/requestToken";
   }
   
   @Override
-  public BaseStringExtractor getBaseStringExtractor()
+  protected BaseStringExtractor getBaseStringExtractor()
   {
     return new LinkedInBaseStringExtractorImpl();
   }
diff --git a/src/main/java/org/scribe/builder/api/TwitterApi.java b/src/main/java/org/scribe/builder/api/TwitterApi.java
index e8b65ca..652cf3f 100644
--- a/src/main/java/org/scribe/builder/api/TwitterApi.java
+++ b/src/main/java/org/scribe/builder/api/TwitterApi.java
@@ -3,13 +3,13 @@ package org.scribe.builder.api;
 public class TwitterApi extends DefaultApi10a
 {
   @Override
-  public String getAccessTokenEndpoint()
+  protected String getAccessTokenEndpoint()
   {
     return "http://twitter.com/oauth/access_token";
   }
 
   @Override
-  public String getRequestTokenEndpoint()
+  protected String getRequestTokenEndpoint()
   {
     return "http://twitter.com/oauth/request_token";
   }
diff --git a/src/main/java/org/scribe/builder/api/VimeoApi.java b/src/main/java/org/scribe/builder/api/VimeoApi.java
index 2fa1701..e5140b7 100644
--- a/src/main/java/org/scribe/builder/api/VimeoApi.java
+++ b/src/main/java/org/scribe/builder/api/VimeoApi.java
@@ -3,13 +3,13 @@ package org.scribe.builder.api;
 public class VimeoApi extends DefaultApi10a
 {
   @Override
-  public String getAccessTokenEndpoint()
+  protected String getAccessTokenEndpoint()
   {
     return "http://vimeo.com/oauth/access_token";
   }
 
   @Override
-  public String getRequestTokenEndpoint()
+  protected String getRequestTokenEndpoint()
   {
     return "http://vimeo.com/oauth/request_token";
   }
diff --git a/src/main/java/org/scribe/builder/api/YahooApi.java b/src/main/java/org/scribe/builder/api/YahooApi.java
index 5767905..ea6cba9 100644
--- a/src/main/java/org/scribe/builder/api/YahooApi.java
+++ b/src/main/java/org/scribe/builder/api/YahooApi.java
@@ -3,13 +3,13 @@ package org.scribe.builder.api;
 public class YahooApi extends DefaultApi10a
 {
   @Override
-  public String getAccessTokenEndpoint()
+  protected String getAccessTokenEndpoint()
   {
     return "https://api.login.yahoo.com/oauth/v2/get_token";
   }
 
   @Override
-  public String getRequestTokenEndpoint()
+  protected String getRequestTokenEndpoint()
   {
     return "https://api.login.yahoo.com/oauth/v2/get_request_token";
   }
diff --git a/src/main/java/org/scribe/exceptions/OAuthException.java b/src/main/java/org/scribe/exceptions/OAuthException.java
index 78e41a4..85f49d9 100644
--- a/src/main/java/org/scribe/exceptions/OAuthException.java
+++ b/src/main/java/org/scribe/exceptions/OAuthException.java
@@ -1,18 +1,33 @@
 package org.scribe.exceptions;
 
+/**
+ * Default scribe exception. 
+ * Represents a problem in the OAuth signing process
+ * 
+ * @author Pablo Fernandez
+ */
 public class OAuthException extends RuntimeException
 {
 
+  /**
+   * Default constructor 
+   * @param message message explaining what went wrong
+   * @param e original exception
+   */
   public OAuthException(String message, Exception e)
   {
     super(message, e);
   }
 
+  /**
+   * No-exception constructor. Used when there is no original exception
+   *  
+   * @param message message explaining what went wrong
+   */
   public OAuthException(String message)
   {
     super(message, null);
   }
 
   private static final long serialVersionUID = 1L;
-
 }
diff --git a/src/main/java/org/scribe/exceptions/OAuthParametersMissingException.java b/src/main/java/org/scribe/exceptions/OAuthParametersMissingException.java
index 8eb3f14..8407ce4 100644
--- a/src/main/java/org/scribe/exceptions/OAuthParametersMissingException.java
+++ b/src/main/java/org/scribe/exceptions/OAuthParametersMissingException.java
@@ -2,6 +2,11 @@ package org.scribe.exceptions;
 
 import org.scribe.model.*;
 
+/**
+ * Specialized exception that represents a missing OAuth parameter. 
+ * 
+ * @author Pablo Fernandez
+ */
 public class OAuthParametersMissingException extends OAuthException
 {
 
@@ -9,6 +14,11 @@ public class OAuthParametersMissingException extends OAuthException
   private static final String MSG = "Could not find oauth parameters in request: %s. "
       + "OAuth parameters must be specified with the addOAuthParameter() method";
 
+  /**
+   * Default constructor.
+   * 
+   * @param request OAuthRequest that caused the error
+   */
   public OAuthParametersMissingException(OAuthRequest request)
   {
     super(String.format(MSG, request));
diff --git a/src/main/java/org/scribe/exceptions/OAuthSignatureException.java b/src/main/java/org/scribe/exceptions/OAuthSignatureException.java
index 765c10a..50143b5 100644
--- a/src/main/java/org/scribe/exceptions/OAuthSignatureException.java
+++ b/src/main/java/org/scribe/exceptions/OAuthSignatureException.java
@@ -1,9 +1,20 @@
 package org.scribe.exceptions;
 
+/**
+ * Specialized exception that represents a problem in the signature
+ * 
+ * @author Pablo Fernandez
+ */
 public class OAuthSignatureException extends OAuthException
 {
   private static final long serialVersionUID = 1L;
   
+  /**
+   * Default constructor
+   * 
+   * @param stringToSign plain string that gets signed (HMAC-SHA, etc)
+   * @param e original exception
+   */
   public OAuthSignatureException(String stringToSign, Exception e)
   {
     super("Error while signing string: " + stringToSign, e);
diff --git a/src/main/java/org/scribe/extensions/linkedin/LinkedInBaseStringExtractorImpl.java b/src/main/java/org/scribe/extensions/linkedin/LinkedInBaseStringExtractorImpl.java
index 29572bc..0413a42 100644
--- a/src/main/java/org/scribe/extensions/linkedin/LinkedInBaseStringExtractorImpl.java
+++ b/src/main/java/org/scribe/extensions/linkedin/LinkedInBaseStringExtractorImpl.java
@@ -3,9 +3,17 @@ package org.scribe.extensions.linkedin;
 import org.scribe.extractors.*;
 import org.scribe.model.*;
 
+/**
+ * LinkedIn's specific extractor that does not encode the tilde character.
+ * 
+ * @author Pablo Fernandez
+ */
 public class LinkedInBaseStringExtractorImpl extends BaseStringExtractorImpl
 {
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public String extract(OAuthRequest request)
   {
diff --git a/src/main/java/org/scribe/extractors/AccessTokenExtractor.java b/src/main/java/org/scribe/extractors/AccessTokenExtractor.java
index 1754851..3c0dd34 100644
--- a/src/main/java/org/scribe/extractors/AccessTokenExtractor.java
+++ b/src/main/java/org/scribe/extractors/AccessTokenExtractor.java
@@ -2,7 +2,18 @@ package org.scribe.extractors;
 
 import org.scribe.model.*;
 
+/**
+ * Simple command object that extracts a {@link Token} from a String
+ * 
+ * @author Pablo Fernandez
+ */
 public interface AccessTokenExtractor
 {
+  /**
+   * Extracts the access token from the contents of an Http Response
+   *  
+   * @param response the contents of the response
+   * @return OAuth access token
+   */
   public Token extract(String response);
 }
diff --git a/src/main/java/org/scribe/extractors/BaseStringExtractor.java b/src/main/java/org/scribe/extractors/BaseStringExtractor.java
index 3ea180c..83ddd10 100644
--- a/src/main/java/org/scribe/extractors/BaseStringExtractor.java
+++ b/src/main/java/org/scribe/extractors/BaseStringExtractor.java
@@ -2,7 +2,20 @@ package org.scribe.extractors;
 
 import org.scribe.model.*;
 
+/**
+ * Simple command object that extracts a base string from a {@link OAuthRequest}
+ * 
+ * @author Pablo Fernandez
+ */
 public interface BaseStringExtractor
 {
+  /**
+   * Extracts an url-encoded base string from the {@link OAuthRequest}.
+   * 
+   * See <a href="http://oauth.net/core/1.0/#anchor14">the oauth spec</a> for more info on this.
+   * 
+   * @param request the OAuthRequest
+   * @return the url-encoded base string
+   */
   String extract(OAuthRequest request);
 }
diff --git a/src/main/java/org/scribe/extractors/BaseStringExtractorImpl.java b/src/main/java/org/scribe/extractors/BaseStringExtractorImpl.java
index 4bbf20f..f18c62c 100644
--- a/src/main/java/org/scribe/extractors/BaseStringExtractorImpl.java
+++ b/src/main/java/org/scribe/extractors/BaseStringExtractorImpl.java
@@ -6,11 +6,20 @@ import org.scribe.exceptions.*;
 import org.scribe.model.*;
 import org.scribe.utils.*;
 
+/**
+ * Default implementation of {@link BaseStringExtractor}. Conforms to OAuth 1.0a
+ * 
+ * @author Pablo Fernandez
+ *
+ */
 public class BaseStringExtractorImpl implements BaseStringExtractor
 {
 
   private static final String AMPERSAND_SEPARATED_STRING = "%s&%s&%s";
 
+  /**
+   * {@inheritDoc}
+   */
   public String extract(OAuthRequest request)
   {
     checkPreconditions(request);
diff --git a/src/main/java/org/scribe/extractors/HeaderExtractor.java b/src/main/java/org/scribe/extractors/HeaderExtractor.java
index 8169422..2bc1f8b 100644
--- a/src/main/java/org/scribe/extractors/HeaderExtractor.java
+++ b/src/main/java/org/scribe/extractors/HeaderExtractor.java
@@ -2,7 +2,18 @@ package org.scribe.extractors;
 
 import org.scribe.model.*;
 
+/**
+ * Simple command object that generates an OAuth Authorization header to include in the request.
+ * 
+ * @author Pablo Fernandez
+ */
 public interface HeaderExtractor
 {
+  /**
+   * Generates an OAuth 'Authorization' Http header to include in requests as the signature.
+   * 
+   * @param request the OAuthRequest to inspect and generate the header
+   * @return the Http header value
+   */
   String extract(OAuthRequest request);
 }
diff --git a/src/main/java/org/scribe/extractors/HeaderExtractorImpl.java b/src/main/java/org/scribe/extractors/HeaderExtractorImpl.java
index 4449f2f..6cc1981 100644
--- a/src/main/java/org/scribe/extractors/HeaderExtractorImpl.java
+++ b/src/main/java/org/scribe/extractors/HeaderExtractorImpl.java
@@ -6,11 +6,20 @@ import org.scribe.exceptions.*;
 import org.scribe.model.*;
 import org.scribe.utils.*;
 
+/**
+ * Default implementation of {@link HeaderExtractor}. Conforms to OAuth 1.0a
+ * 
+ * @author Pablo Fernandez
+ *
+ */
 public class HeaderExtractorImpl implements HeaderExtractor
 {
   private static final String PARAM_SEPARATOR = ", ";
   private static final String PREAMBLE = "OAuth ";
 
+  /**
+   * {@inheritDoc}
+   */
   public String extract(OAuthRequest request)
   {
     checkPreconditions(request);
diff --git a/src/main/java/org/scribe/extractors/RequestTokenExtractor.java b/src/main/java/org/scribe/extractors/RequestTokenExtractor.java
index 696c389..1830212 100644
--- a/src/main/java/org/scribe/extractors/RequestTokenExtractor.java
+++ b/src/main/java/org/scribe/extractors/RequestTokenExtractor.java
@@ -2,8 +2,18 @@ package org.scribe.extractors;
 
 import org.scribe.model.*;
 
+/**
+ * Simple command object that extracts a {@link Token} from a String
+ * 
+ * @author Pablo Fernandez
+ */
 public interface RequestTokenExtractor
 {
-
+  /**
+   * Extracts the request token from the contents of an Http Response
+   *  
+   * @param response the contents of the response
+   * @return OAuth access token
+   */
   public Token extract(String response);
 }
diff --git a/src/main/java/org/scribe/extractors/TokenExtractorImpl.java b/src/main/java/org/scribe/extractors/TokenExtractorImpl.java
index 0147957..501c018 100644
--- a/src/main/java/org/scribe/extractors/TokenExtractorImpl.java
+++ b/src/main/java/org/scribe/extractors/TokenExtractorImpl.java
@@ -6,11 +6,20 @@ import org.scribe.exceptions.*;
 import org.scribe.model.*;
 import org.scribe.utils.*;
 
+/**
+ * Default implementation of {@RequestTokenExtractor} and {@AccessTokenExtractor}. Conforms to OAuth 1.0a
+ *
+ * The process for extracting access and request tokens is similar so this class can do both things.
+ * 
+ * @author Pablo Fernandez
+ */
 public class TokenExtractorImpl implements RequestTokenExtractor, AccessTokenExtractor
 {
-
   private static final String TOKEN_REGEX = "oauth_token=(\\S*)&oauth_token_secret=(\\S*?)(&(.*))?";
 
+  /**
+   * {@inheritDoc} 
+   */
   public Token extract(String response)
   {
     Preconditions.checkEmptyString(response, "Cant extract a token from null object or an empty string.");
diff --git a/src/main/java/org/scribe/model/OAuthConfig.java b/src/main/java/org/scribe/model/OAuthConfig.java
index f2634f1..2521d57 100644
--- a/src/main/java/org/scribe/model/OAuthConfig.java
+++ b/src/main/java/org/scribe/model/OAuthConfig.java
@@ -1,5 +1,10 @@
 package org.scribe.model;
 
+/**
+ * Parameter object that groups OAuth config values
+ * 
+ * @author Pablo Fernandez
+ */
 public class OAuthConfig
 {
   private String apiKey;
diff --git a/src/main/java/org/scribe/model/OAuthConstants.java b/src/main/java/org/scribe/model/OAuthConstants.java
index 2c18624..bc0010b 100644
--- a/src/main/java/org/scribe/model/OAuthConstants.java
+++ b/src/main/java/org/scribe/model/OAuthConstants.java
@@ -19,7 +19,6 @@ package org.scribe.model;
  * This class contains OAuth constants, used project-wide
  * 
  * @author Pablo Fernandez
- * 
  */
 public class OAuthConstants
 {
diff --git a/src/main/java/org/scribe/model/Request.java b/src/main/java/org/scribe/model/Request.java
index f7853be..9052bca 100644
--- a/src/main/java/org/scribe/model/Request.java
+++ b/src/main/java/org/scribe/model/Request.java
@@ -14,7 +14,6 @@ import org.scribe.utils.*;
  */
 class Request
 {
-
   private static final String CONTENT_LENGTH = "Content-Length";
 
   private String url;
diff --git a/src/main/java/org/scribe/model/Response.java b/src/main/java/org/scribe/model/Response.java
index 536225f..6164e14 100644
--- a/src/main/java/org/scribe/model/Response.java
+++ b/src/main/java/org/scribe/model/Response.java
@@ -13,7 +13,6 @@ import org.scribe.utils.*;
  */
 public class Response
 {
-
   private static final String EMPTY = "";
 
   private int code;
@@ -52,11 +51,6 @@ public class Response
     return headers;
   }
 
-  /**
-   * Checks if the code is in the successful or redirect range.
-   * 
-   * @return true if successful
-   */
   private boolean wasSuccessful()
   {
     return getCode() >= 200 && getCode() < 400;
diff --git a/src/main/java/org/scribe/model/Token.java b/src/main/java/org/scribe/model/Token.java
index ee33391..6084e4e 100644
--- a/src/main/java/org/scribe/model/Token.java
+++ b/src/main/java/org/scribe/model/Token.java
@@ -1,11 +1,21 @@
 package org.scribe.model;
 
+/**
+ * Represents an OAuth token (either request or access token) and its secret
+ * 
+ * @author Pablo Fernandez
+ */
 public class Token
 {
-
   private final String token;
   private final String secret;
 
+  /**
+   * Default constructor
+   * 
+   * @param token token value
+   * @param secret token secret
+   */
   public Token(String token, String secret)
   {
     this.token = token;
diff --git a/src/main/java/org/scribe/model/Verifier.java b/src/main/java/org/scribe/model/Verifier.java
index 512ac00..2a98fd6 100644
--- a/src/main/java/org/scribe/model/Verifier.java
+++ b/src/main/java/org/scribe/model/Verifier.java
@@ -1,10 +1,19 @@
 package org.scribe.model;
 
+/**
+ * Represents an OAuth verifier code.
+ * 
+ * @author Pablo Fernandez
+ */
 public class Verifier
 {
-
   private final String value;
 
+  /**
+   * Default constructor.
+   * 
+   * @param value verifier value
+   */
   public Verifier(String value)
   {
     this.value = value;
diff --git a/src/main/java/org/scribe/oauth/OAuthService.java b/src/main/java/org/scribe/oauth/OAuthService.java
index 18da2f0..0b54f51 100644
--- a/src/main/java/org/scribe/oauth/OAuthService.java
+++ b/src/main/java/org/scribe/oauth/OAuthService.java
@@ -2,15 +2,50 @@ package org.scribe.oauth;
 
 import org.scribe.model.*;
 
+/**
+ * The main Scribe object. 
+ * 
+ * A facade responsible for the retrieval of request and access tokens and for the signing of HTTP requests.  
+ * 
+ * @author Pablo Fernandez
+ */
 public interface OAuthService
 {
+  /**
+   * Retrieve the request token.
+   * 
+   * @return request token
+   */
   public Token getRequestToken();
 
+  /**
+   * Retrieve the access token
+   * 
+   * @param requestToken request token (obtained previously)
+   * @param verifier verifier code
+   * @return access token
+   */
   public Token getAccessToken(Token requestToken, Verifier verifier);
 
+  /**
+   * Signs am OAuth request
+   * 
+   * @param accessToken access token (obtained previously)
+   * @param request request to sign
+   */
   public void signRequest(Token accessToken, OAuthRequest request);
 
+  /**
+   * Returns the OAuth version of the service.
+   * 
+   * @return oauth version as string
+   */
   public String getVersion();
 
+  /**
+   * Adds the 'scope' parameter. This is **not** a default OAuth parameter and the setting is optional.
+   * 
+   * @param scope OAuth Api scope (optional)
+   */
   public void addScope(String scope);
 }
diff --git a/src/main/java/org/scribe/services/HMACSha1SignatureService.java b/src/main/java/org/scribe/services/HMACSha1SignatureService.java
index 94db9c3..013a82d 100644
--- a/src/main/java/org/scribe/services/HMACSha1SignatureService.java
+++ b/src/main/java/org/scribe/services/HMACSha1SignatureService.java
@@ -7,15 +7,23 @@ import org.apache.commons.codec.binary.*;
 import org.scribe.exceptions.*;
 import org.scribe.utils.*;
 
+/**
+ * HMAC-SHA1 implementation of {@SignatureService}
+ * 
+ * @author Pablo Fernandez
+ *
+ */
 public class HMACSha1SignatureService implements SignatureService
 {
-
   private static final String EMPTY_STRING = "";
   private static final String CARRIAGE_RETURN = "\r\n";
   private static final String UTF8 = "UTF-8";
   private static final String HMAC_SHA1 = "HmacSHA1";
   private static final String METHOD = "HMAC-SHA1";
 
+  /**
+   * {@inheritDoc}
+   */
   public String getSignature(String baseString, String apiSecret, String tokenSecret)
   {
     try
@@ -39,6 +47,9 @@ public class HMACSha1SignatureService implements SignatureService
     return new String(Base64.encodeBase64(bytes)).replace(CARRIAGE_RETURN, EMPTY_STRING);
   }
 
+  /**
+   * {@inheritDoc}
+   */
   public String getSignatureMethod()
   {
     return METHOD;
diff --git a/src/main/java/org/scribe/services/SignatureService.java b/src/main/java/org/scribe/services/SignatureService.java
index fddf285..229c2f6 100644
--- a/src/main/java/org/scribe/services/SignatureService.java
+++ b/src/main/java/org/scribe/services/SignatureService.java
@@ -1,8 +1,28 @@
 package org.scribe.services;
 
+/**
+ * Signs a base string, returning the OAuth signature
+ * 
+ * @author Pablo Fernandez
+ *
+ */
 public interface SignatureService
 {
+  /**
+   * Returns the signature
+   * 
+   * @param baseString url-encoded string to sign
+   * @param apiSecret api secret for your app
+   * @param tokenSecret token secret (empty string for the request token step)
+   * 
+   * @return signature
+   */
   public String getSignature(String baseString, String apiSecret, String tokenSecret);
 
+  /**
+   * Returns the signature method/algorithm
+   * 
+   * @return
+   */
   public String getSignatureMethod();
 }
diff --git a/src/main/java/org/scribe/services/TimestampService.java b/src/main/java/org/scribe/services/TimestampService.java
index ada540b..221a226 100644
--- a/src/main/java/org/scribe/services/TimestampService.java
+++ b/src/main/java/org/scribe/services/TimestampService.java
@@ -1,9 +1,25 @@
 package org.scribe.services;
 
+/**
+ * Unix epoch timestamp generator.
+ * 
+ * This class is useful for stubbing in tests. 
+ * 
+ * @author Pablo Fernandez
+ */
 public interface TimestampService
 {
-
+  /**
+   * Returns the unix epoch timestamp in seconds
+   * 
+   * @return timestamp
+   */
   public String getTimestampInSeconds();
 
+  /**
+   * Returns a nonce (unique value for each request)
+   * 
+   * @return nonce
+   */
   public String getNonce();
 }
diff --git a/src/main/java/org/scribe/services/TimestampServiceImpl.java b/src/main/java/org/scribe/services/TimestampServiceImpl.java
index 894e07b..4aa27e0 100644
--- a/src/main/java/org/scribe/services/TimestampServiceImpl.java
+++ b/src/main/java/org/scribe/services/TimestampServiceImpl.java
@@ -2,22 +2,35 @@ package org.scribe.services;
 
 import java.util.*;
 
+/**
+ * Implementation of {@link TimestampService} using plain java classes.
+ * 
+ * @author Pablo Fernandez
+ */
 public class TimestampServiceImpl implements TimestampService
 {
-
   private Timer timer;
 
+  /**
+   * Default constructor. 
+   */
   public TimestampServiceImpl()
   {
     timer = new Timer();
   }
 
+  /**
+   * {@inheritDoc}
+   */
   public String getNonce()
   {
     Long ts = getTs();
     return String.valueOf(ts + timer.getRandomInteger());
   }
 
+  /**
+   * {@inheritDoc}
+   */
   public String getTimestampInSeconds()
   {
     return String.valueOf(getTs());
@@ -33,14 +46,19 @@ public class TimestampServiceImpl implements TimestampService
     this.timer = timer;
   }
 
+  /**
+   * Inner class that uses {@link System} for generating the timestamps.
+   * 
+   * @author Pablo Fernandez
+   */
   static class Timer
   {
-    public Long getMilis()
+    Long getMilis()
     {
       return System.currentTimeMillis();
     }
 
-    public Integer getRandomInteger()
+    Integer getRandomInteger()
     {
       return new Random().nextInt();
     }
diff --git a/src/main/java/org/scribe/utils/MapUtils.java b/src/main/java/org/scribe/utils/MapUtils.java
index 011d880..db08db3 100644
--- a/src/main/java/org/scribe/utils/MapUtils.java
+++ b/src/main/java/org/scribe/utils/MapUtils.java
@@ -2,9 +2,19 @@ package org.scribe.utils;
 
 import java.util.*;
 
+/**
+ * Utils for {@link Map} manipulation
+ * 
+ * @author Pablo Fernandez
+ */
 public class MapUtils
 {
-
+  /**
+   * Sorts a Map
+   * 
+   * @param map unsorted map
+   * @return sorted map
+   */
   public static final Map<String, String> sort(Map<String, String> map)
   {
     Preconditions.checkNotNull(map, "Cannot sort a null object.");
diff --git a/src/main/java/org/scribe/utils/Preconditions.java b/src/main/java/org/scribe/utils/Preconditions.java
index f63a20e..d7a06c3 100644
--- a/src/main/java/org/scribe/utils/Preconditions.java
+++ b/src/main/java/org/scribe/utils/Preconditions.java
@@ -4,27 +4,60 @@ import java.util.regex.Pattern;
 
 import org.scribe.model.OAuthConstants;
 
+/**
+ * Utils for checking preconditions and invariants
+ * 
+ * @author Pablo Fernandez
+ */
 public class Preconditions
 {
   private static final String DEFAULT_MESSAGE = "Received an invalid parameter";
   private static final Pattern URL_PATTERN = Pattern.compile("[a-zA-Z_-]+://\\S+");
 
+  /**
+   * Checks that an object is not null.
+   * 
+   * @param object any object
+   * @param errorMsg error message
+   * 
+   * @throws IllegalArgumentException if the object is null
+   */
   public static void checkNotNull(Object object, String errorMsg)
   {
     check(object != null, errorMsg);
   }
 
+  /**
+   * Checks that a string is not null or empty
+   * 
+   * @param string any string
+   * @param errorMsg error message
+   * 
+   * @throws IllegalArgumentException if the string is null or empty
+   */
   public static void checkEmptyString(String string, String errorMsg)
   {
     check(string != null && !string.trim().equals(""), errorMsg);
   }
 
+  /**
+   * Checks that a URL is valid
+   * 
+   * @param url any string
+   * @param errorMsg error message
+   */
   public static void checkValidUrl(String url, String errorMsg)
   {
     checkEmptyString(url, errorMsg);
     check(isUrl(url), errorMsg);
   }
   
+  /**
+   * Checks that a URL is a valid OAuth callback
+   *  
+   * @param url any string
+   * @param errorMsg error message
+   */
   public static void checkValidOAuthCallback(String url, String errorMsg)
   {
     checkEmptyString(url, errorMsg);
@@ -34,7 +67,7 @@ public class Preconditions
     }
   }
   
-  static boolean isUrl(String url)
+  private static boolean isUrl(String url)
   {
     return URL_PATTERN.matcher(url).matches();
   }
diff --git a/src/main/java/org/scribe/utils/StreamUtils.java b/src/main/java/org/scribe/utils/StreamUtils.java
index 20c477e..fc5be8c 100644
--- a/src/main/java/org/scribe/utils/StreamUtils.java
+++ b/src/main/java/org/scribe/utils/StreamUtils.java
@@ -2,9 +2,19 @@ package org.scribe.utils;
 
 import java.io.*;
 
+/**
+ * Utils to deal with Streams.
+ *  
+ * @author Pablo Fernandez
+ */
 public class StreamUtils
 {
-
+  /**
+   * Returns the stream contents as an UTF-8 encoded string
+   * 
+   * @param is input stream
+   * @return string contents
+   */
   public static String getStreamContents(InputStream is)
   {
     Preconditions.checkNotNull(is, "Cannot get String from a null object");
diff --git a/src/main/java/org/scribe/utils/URLUtils.java b/src/main/java/org/scribe/utils/URLUtils.java
index 11dbc1a..5cf08bd 100644
--- a/src/main/java/org/scribe/utils/URLUtils.java
+++ b/src/main/java/org/scribe/utils/URLUtils.java
@@ -6,9 +6,13 @@ import java.util.*;
 
 import org.scribe.exceptions.*;
 
+/**
+ * Utils to deal with URL and url-encodings 
+ * 
+ * @author Pablo Fernandez
+ */
 public class URLUtils
 {
-
   private static final String EMPTY_STRING = "";
   private static final String UTF_8 = "UTF-8";
   private static final char PAIR_SEPARATOR = '=';
@@ -16,6 +20,12 @@ public class URLUtils
 
   private static final String ERROR_MSG = String.format("Cannot find specified encoding: %s", UTF_8);
 
+  /**
+   * Turns a map into a form-url-encoded string (key=value&key2=value2)
+   * 
+   * @param map any map
+   * @return form-url-encoded string
+   */
   public static String formURLEncodeMap(Map<String, String> map)
   {
     Preconditions.checkNotNull(map, "Cannot url-encode a null object");
@@ -36,6 +46,12 @@ public class URLUtils
     return encodedString.toString();
   }
 
+  /**
+   * Percent encodes a string
+   * 
+   * @param plain
+   * @return percent encoded string
+   */
   public static String percentEncode(String string)
   {
     Preconditions.checkNotNull(string, "Cannot encode null string");
@@ -49,6 +65,12 @@ public class URLUtils
     }
   }
 
+  /**
+   * Percent decodes a string
+   * 
+   * @param string percent encoded string
+   * @return plain string
+   */
   public static String percentDecode(String string)
   {
     Preconditions.checkNotNull(string, "Cannot decode null string");