Documentation improvements.

core/src/main/java/org/acegisecurity/Authentication.java

@@ -37,18 +37,19 @@ public interface Authentication {
 
     /**
      * Indicates whether or not authentication was attempted by the {@link
-     * net.sf.acegisecurity.SecurityInterceptor}. Note that  classes should
+     * net.sf.acegisecurity.intercept.AbstractSecurityInterceptor}. Note that
-     * not rely on this value as being valid unless it has been set by a
+     * classes should not rely on this value as being valid unless it has been
-     * trusted <code>SecurityInterceptor</code>.
+     * set by a trusted <code>AbstractSecurityInterceptor</code>.
      *
-     * @return true if authenticated by the <code>SecurityInterceptor</code>
+     * @return true if authenticated by the
+     *         <code>AbstractSecurityInterceptor</code>
      */
     public boolean isAuthenticated();
 
     /**
      * Set by an <code>AuthenticationManager</code> to indicate the authorities
-     * that the principal has been  granted. Note that classes should not rely
+     * that the principal has been granted. Note that classes should not rely
-     * on this value as being valid  unless it has been set by a trusted
+     * on this value as being valid unless it has been set by a trusted
      * <code>AuthenticationManager</code>.
      *
      * @return the authorities granted to the principal, or <code>null</code>

core/src/main/java/org/acegisecurity/ConfigAttribute.java

@@ -19,15 +19,16 @@ package net.sf.acegisecurity;
  * Stores a security system related configuration attribute.
  * 
  * <p>
- * When the {@link SecurityInterceptor} is setup, a list of configuration
+ * When an {@link net.sf.acegisecurity.intercept.AbstractSecurityInterceptor}
- * attributes is defined for secure method patterns. These configuration
+ * is setup, a list of configuration attributes is defined for secure object
- * attributes have special meaning to a {@link RunAsManager}, {@link
+ * patterns. These configuration attributes have special meaning to a {@link
- * AccessDecisionManager} or <code>AccessDecisionManager</code> delegate.
+ * RunAsManager}, {@link AccessDecisionManager} or
+ * <code>AccessDecisionManager</code> delegate.
  * </p>
  * 
  * <P>
  * Stored at runtime with other <code>ConfigAttribute</code>s for the same
- * method within a {@link ConfigAttributeDefinition}.
+ * secure object target within a {@link ConfigAttributeDefinition}.
  * </p>
  *
  * @author Ben Alex
@@ -47,7 +48,7 @@ public interface ConfigAttribute {
      * <p>
      * If the <code>ConfigAttribute</code> cannot be expressed with sufficient
      * precision as a <code>String</code>,  <code>null</code> should be
-     * returned. Returning <code>null</code> will require an relying classes
+     * returned. Returning <code>null</code> will require any relying classes
      * to specifically support the  <code>ConfigAttribute</code>
      * implementation, so returning  <code>null</code> should be avoided
      * unless actually  required.

core/src/main/java/org/acegisecurity/ConfigAttributeDefinition.java

@@ -22,12 +22,12 @@ import java.util.Vector;
 
 /**
  * Holds a group of {@link ConfigAttribute}s that are associated with a given
- * method.
+ * secure object target.
  * 
  * <p>
  * All the <code>ConfigAttributeDefinition</code>s associated with a given
- * <code>SecurityInterceptor</code> are stored in a  {@link
+ * {@link net.sf.acegisecurity.intercept.AbstractSecurityInterceptor} are
- * MethodDefinitionMap}.
+ * stored in an {@link net.sf.acegisecurity.intercept.ObjectDefinitionSource}.
  * </p>
  *
  * @author Ben Alex
@@ -47,18 +47,28 @@ public class ConfigAttributeDefinition {
     //~ Methods ================================================================
 
     /**
-     * DOCUMENT ME!
+     * Returns an <code>Iterator</code> over all the
+     * <code>ConfigAttribute</code>s defined by this
+     * <code>ConfigAttributeDefinition</code>.
      * 
-     * @return all the configuration attributes related to the method.
+     * <P>
+     * Allows <code>AccessDecisionManager</code>s and other classes to loop
+     * through every configuration attribute associated with a target secure
+     * object.
+     * </p>
+     *
+     * @return all the configuration attributes stored by the instance, or
+     *         <code>null</code> if an <code>Iterator</code> is unavailable
      */
     public Iterator getConfigAttributes() {
         return this.configAttributes.iterator();
     }
 
     /**
-     * Adds a <code>ConfigAttribute</code> that is related to the method.
+     * Adds a <code>ConfigAttribute</code> that is related to the secure object
+     * method.
      *
-     * @param newConfigAttribute DOCUMENT ME!
+     * @param newConfigAttribute the new configuration attribute to add
      */
     public void addConfigAttribute(ConfigAttribute newConfigAttribute) {
         this.configAttributes.add(newConfigAttribute);

core/src/main/java/org/acegisecurity/adapters/package.html

@@ -1,8 +1,11 @@
 <html>
 <body>
-Provides "adapters" so that containers can authenticate with the 
+Allows external containers to obtain authentication information from the
-Acegi Security System for Spring.
+system.
-<p>
+
+<p>It is recommended to use the <code>net.sf.acegisecurity.ui.webapp</code>
+package for standard web applications, as it has much lower configuration
+complexity.</p>
+
 </body>
 </html>
-

core/src/main/java/org/acegisecurity/context/SecureContext.java

@@ -24,7 +24,7 @@ import net.sf.acegisecurity.Authentication;
  * <p>
  * This interface must be implemented on contexts that will be presented to the
  * Acegi Security System for Spring, as it is required by the  {@link
- * net.sf.acegisecurity.SecurityInterceptor}.
+ * net.sf.acegisecurity.intercept.method.MethodSecurityInterceptor}.
  * </p>
  *
  * @author Ben Alex

core/src/main/java/org/acegisecurity/package.html

@@ -1,21 +1,6 @@
 <html>
 <body>
-Provides core security classes of the Acegi Security System for Spring.
+Provides core Acegi Security System for Spring interfaces and classes.
-<p>
-The {@link net.sf.acegisecurity.SecurityInterceptor} is the main class.
-It delegates to two interfaces, 
-{@link net.sf.acegisecurity.AuthenticationManager} and 
-{@link net.sf.acegisecurity.AccessDecisionManager} for authentication and
-authorization respectively.
-<p>
-When configuring <code>SecurityInterceptor</code> in the bean context, each 
-method to be secured is provided a comma separated list of configuration
-attributes ({@link net.sf.acegisecurity.ConfigAttribute}). 
-These configuration attributes are relevant only to 
-<Code>AccessDecisionManager</code>s.
-<p>
-Read the JavaDocs of the key classes listed above to learn more about how 
-the security classes operate.
 </body>
 </html>
 

core/src/main/java/org/acegisecurity/providers/package.html

@@ -1,7 +1,6 @@
 <html>
 <body>
-Implements a provider-based approach to authorization decisions.
+Implements a provider-based approach to authentication decisions.
 <p>
 </body>
 </html>
-

core/src/main/java/org/acegisecurity/runas/package.html

@@ -1,5 +1,5 @@
 <html>
 <body>
-Allows intercepted methods to be run under a different authentication identity.
+Allows secure objects to be run under a different authentication identity.
 </body>
 </html>