diff --git a/jetty-continuation/src/main/java/org/eclipse/jetty/continuation/Continuation.java b/jetty-continuation/src/main/java/org/eclipse/jetty/continuation/Continuation.java
index c60e6e110e3..7b9a86471c2 100644
--- a/jetty-continuation/src/main/java/org/eclipse/jetty/continuation/Continuation.java
+++ b/jetty-continuation/src/main/java/org/eclipse/jetty/continuation/Continuation.java
@@ -172,8 +172,8 @@ public interface Continuation
      * the container with a suspended request, the thread is freed for other
      * tasks and the request is held until either:
      * <ul>
-     * <li>a call to {@link ServletRequest#resume()}.</li>
-     * <li>a call to {@link ServletRequest#complete()}.</li>
+     * <li>a call to {@link #resume()}.</li>
+     * <li>a call to {@link #complete()}.</li>
      * <li>the timeout expires.</li>
      * </ul>
      * <p>
diff --git a/jetty-rewrite/src/main/java/org/eclipse/jetty/rewrite/handler/RewriteHandler.java b/jetty-rewrite/src/main/java/org/eclipse/jetty/rewrite/handler/RewriteHandler.java
index 1178cb04de2..5723fb7ca4c 100644
--- a/jetty-rewrite/src/main/java/org/eclipse/jetty/rewrite/handler/RewriteHandler.java
+++ b/jetty-rewrite/src/main/java/org/eclipse/jetty/rewrite/handler/RewriteHandler.java
@@ -30,31 +30,28 @@ import org.eclipse.jetty.server.handler.HandlerWrapper;
  * There is also handling for cookies, headers, redirection, setting status or error codes 
  * whenever the rule finds a match. 
  * 
- * <p> The rules can be matched by the ff. options: pattern matching of PathMap 
- * (class PatternRule), regular expressions (class RegexRule) or certain conditions set 
- * (e.g. MsieSslRule - the requests must be in SSL mode).
+ * <p> The rules can be matched by the either: pattern matching of PathMap 
+ * (eg {@link PatternRule}), regular expressions (eg {@link RegexRule}) or certain conditions set 
+ * (eg {@link MsieSslRule} - the requests must be in SSL mode).
  * 
- * Here are the list of rules:
- * <ul>
- * <li> CookiePatternRule - adds a new cookie in response. </li>
- * <li> HeaderPatternRule - adds/modifies the HTTP headers in response. </li>
- * <li> RedirectPatternRule - sets the redirect location. </li>
- * <li> ResponsePatternRule - sets the status/error codes. </li>
- * <li> RewritePatternRule - rewrites the requested URI. </li>
- * <li> RewriteRegexRule - rewrites the requested URI using regular expression for pattern matching. </li>
- * <li> MsieSslRule - disables the keep alive on SSL for IE5 and IE6. </li>
- * <li> LegacyRule - the old version of rewrite. </li>
- * <li> ForwardedSchemeHeaderRule - set the scheme according to the headers present. </li>
- * </ul>
- *
- * <p> The rules can be grouped into rule containers (class RuleContainerRule), and will only 
+ * <p> The rules can be grouped into rule containers (class {@link RuleContainer}), and will only 
  * be applied if the request matches the conditions for their container
  * (e.g., by virtual host name)
- *
- * Here are a list of rule containers:
+ * 
+ * <p>The list of predefined rules is:
  * <ul>
- * <li> VirtualHostRuleContainerRule - checks whether the request matches one of a set of virtual host names.</li>
+ * <li> {@link CookiePatternRule} - adds a new cookie in response. </li>
+ * <li> {@link HeaderPatternRule} - adds/modifies the HTTP headers in response. </li>
+ * <li> {@link RedirectPatternRule} - sets the redirect location. </li>
+ * <li> {@link ResponsePatternRule} - sets the status/error codes. </li>
+ * <li> {@link RewritePatternRule} - rewrites the requested URI. </li>
+ * <li> {@link RewriteRegexRule} - rewrites the requested URI using regular expression for pattern matching. </li>
+ * <li> {@link MsieSslRule} - disables the keep alive on SSL for IE5 and IE6. </li>
+ * <li> {@link LegacyRule} - the old version of rewrite. </li>
+ * <li> {@link ForwardedSchemeHeaderRule} - set the scheme according to the headers present. </li>
+ * <li> {@link VirtualHostRuleContainer} - checks whether the request matches one of a set of virtual host names.</li>
  * </ul>
+ *
  * 
  * Here is a typical jetty.xml configuration would be: <pre>
  * 
diff --git a/jetty-security/src/main/java/org/eclipse/jetty/security/DefaultAuthenticatorFactory.java b/jetty-security/src/main/java/org/eclipse/jetty/security/DefaultAuthenticatorFactory.java
index 290ae6b0d15..bec4b347c10 100644
--- a/jetty-security/src/main/java/org/eclipse/jetty/security/DefaultAuthenticatorFactory.java
+++ b/jetty-security/src/main/java/org/eclipse/jetty/security/DefaultAuthenticatorFactory.java
@@ -27,13 +27,17 @@ import org.eclipse.jetty.server.Server;
 /**
  * The Default Authenticator Factory.
  * Uses the {@link Configuration#getAuthMethod()} to select an {@link Authenticator} from: <ul>
- * <li>{@link BasicAuthenticator}</li>
- * <li>{@link DigestAuthenticator}</li>
- * <li>{@link FormAuthenticator}</li>
- * <li>{@link ClientCertAuthenticator}</li>
+ * <li>{@link org.eclipse.jetty.security.authentication.BasicAuthenticator}</li>
+ * <li>{@link org.eclipse.jetty.security.authentication.DigestAuthenticator}</li>
+ * <li>{@link org.eclipse.jetty.security.authentication.FormAuthenticator}</li>
+ * <li>{@link org.eclipse.jetty.security.authentication.ClientCertAuthenticator}</li>
  * </ul>
- * If {@link Configuration#isLazy()} is true, the Authenticator is wrapped with a {@link DeferredAuthenticator}
- * instance. The FormAuthenticator is always wrapped in a {@link SessionCachingAuthenticator}.
+ * All authenticators derived from {@link org.eclipse.jetty.security.authentication.LoginAuthenticator} are 
+ * wrapped with a {@link org.eclipse.jetty.security.authentication.DeferredAuthentication}
+ * instance, which is used if authentication is not mandatory.
+ * 
+ * The Authentications from the {@link org.eclipse.jetty.security.authentication.FormAuthenticator} are always wrapped in a 
+ * {@link org.eclipse.jetty.security.authentication.SessionAuthentication}
  * <p>
  * If a {@link LoginService} has not been set on this factory, then
  * the service is selected by searching the {@link Server#getBeans(Class)} results for
@@ -61,7 +65,6 @@ public class DefaultAuthenticatorFactory implements Authenticator.Factory
         return authenticator;
     }
    
-
     /* ------------------------------------------------------------ */
     /**
      * @return the loginService
diff --git a/jetty-security/src/main/java/org/eclipse/jetty/security/authentication/FormAuthenticator.java b/jetty-security/src/main/java/org/eclipse/jetty/security/authentication/FormAuthenticator.java
index 7a624ddc7fe..96833e16139 100644
--- a/jetty-security/src/main/java/org/eclipse/jetty/security/authentication/FormAuthenticator.java
+++ b/jetty-security/src/main/java/org/eclipse/jetty/security/authentication/FormAuthenticator.java
@@ -42,15 +42,16 @@ import org.eclipse.jetty.util.log.Log;
 /**
  * FORM Authenticator.
  * 
- * The form authenticator redirects unauthenticated requests to a log page
- * which should use a form to gather username/password from the user and send them
- * to the /j_security_check URI within the context.  FormAuthentication is intended
- * to be used together with the {@link SessionCachingAuthenticator} so that the
- * auth results may be associated with the session.
- *  
- * This authenticator implements form authentication will use dispatchers to
+ * <p>This authenticator implements form authentication will use dispatchers to
  * the login page if the {@link #__FORM_DISPATCH} init parameter is set to true.
- * Otherwise it will redirect.
+ * Otherwise it will redirect.</p>
+ * 
+ * <p>The form authenticator redirects unauthenticated requests to a log page
+ * which should use a form to gather username/password from the user and send them
+ * to the /j_security_check URI within the context.  FormAuthentication uses 
+ * {@link SessionAuthentication} to wrap Authentication results so that they
+ * are  associated with the session.</p>
+ *  
  * 
  */
 public class FormAuthenticator extends LoginAuthenticator
diff --git a/jetty-security/src/main/java/org/eclipse/jetty/security/authentication/SessionAuthentication.java b/jetty-security/src/main/java/org/eclipse/jetty/security/authentication/SessionAuthentication.java
index 5790677b019..ec20115ee53 100644
--- a/jetty-security/src/main/java/org/eclipse/jetty/security/authentication/SessionAuthentication.java
+++ b/jetty-security/src/main/java/org/eclipse/jetty/security/authentication/SessionAuthentication.java
@@ -24,7 +24,7 @@ import org.eclipse.jetty.security.Authenticator;
 import org.eclipse.jetty.security.UserAuthentication;
 import org.eclipse.jetty.server.UserIdentity;
 
-class SessionAuthentication extends UserAuthentication implements HttpSessionAttributeListener, Serializable
+public class SessionAuthentication extends UserAuthentication implements HttpSessionAttributeListener, Serializable
 {
     private static final long serialVersionUID = -4643200685888258706L;
 
diff --git a/jetty-server/src/main/java/org/eclipse/jetty/server/nio/SelectChannelConnector.java b/jetty-server/src/main/java/org/eclipse/jetty/server/nio/SelectChannelConnector.java
index 32e8bdde643..54fa98f2671 100644
--- a/jetty-server/src/main/java/org/eclipse/jetty/server/nio/SelectChannelConnector.java
+++ b/jetty-server/src/main/java/org/eclipse/jetty/server/nio/SelectChannelConnector.java
@@ -20,6 +20,7 @@ import java.nio.channels.SelectionKey;
 import java.nio.channels.ServerSocketChannel;
 import java.nio.channels.SocketChannel;
 
+import org.eclipse.jetty.continuation.Continuation;
 import org.eclipse.jetty.io.ConnectedEndPoint;
 import org.eclipse.jetty.io.Connection;
 import org.eclipse.jetty.io.EndPoint;
@@ -44,11 +45,11 @@ import org.eclipse.jetty.util.thread.Timeout.Task;
  * This connector is best used when there are a many connections that have idle periods.
  * </p>
  * <p>
- * When used with {@link org.eclipse.jetty.continuation.Continuation}, threadless waits are supported. When
- * a filter or servlet calls getEvent on a Continuation, a 
- * runtime exception is thrown to allow the thread to exit the current request handling. Jetty will
- * catch this exception and will not send a response to the client. Instead the thread is released
- * and the Continuation is placed on the timer queue. If the Continuation timeout expires, or it's
+ * When used with {@link org.eclipse.jetty.continuation.Continuation}, threadless waits are supported. 
+ * If a filter or servlet returns after calling {@link Continuation#suspend()} or when a
+ * runtime exception is thrown from a call to {@link Continuation#undispatch()}, Jetty will
+ * will not send a response to the client. Instead the thread is released and the Continuation is 
+ * placed on the timer queue. If the Continuation timeout expires, or it's
  * resume method is called, then the request is again allocated a thread and the request is retried.
  * The limitation of this approach is that request content is not available on the retried request,
  * thus if possible it should be read after the continuation or saved as a request attribute or as the
diff --git a/jetty-server/src/main/java/org/eclipse/jetty/server/session/AbstractSessionManager.java b/jetty-server/src/main/java/org/eclipse/jetty/server/session/AbstractSessionManager.java
index 08f3f756076..fc835697e57 100644
--- a/jetty-server/src/main/java/org/eclipse/jetty/server/session/AbstractSessionManager.java
+++ b/jetty-server/src/main/java/org/eclipse/jetty/server/session/AbstractSessionManager.java
@@ -54,10 +54,6 @@ import org.eclipse.jetty.util.statistic.SampleStatistic;
  * a specialized version of the Session inner class that provides an attribute
  * Map.
  * <p>
- * If the property
- * <code>org.eclipse.jetty.servlet.AbstractSessionManager.23Notifications</code> is set to
- * true, the 2.3 servlet spec notification style will be used.
- * <p>
  *
  * 
  */