keycloak-aplcache

diff --git a/services/pom.xml b/services/pom.xml
index 25e1756..bfb07ce 100755
--- a/services/pom.xml
+++ b/services/pom.xml
@@ -292,6 +292,7 @@
                                         <!-- List of attributes:
                                         https://github.com/asciidoctor/asciidoctorj/blob/master/asciidoctorj-core/src/main/java/org/asciidoctor/Attributes.java
                                          -->
+                                        <toc/>
                                         <generated>${project.basedir}/target/apidocs-rest/asciidoc</generated>
                                     </attributes>
                                 </configuration>

diff --git a/services/src/main/java/org/keycloak/authentication/authenticators/client/ClientIdAndSecretAuthenticator.java b/services/src/main/java/org/keycloak/authentication/authenticators/client/ClientIdAndSecretAuthenticator.java
index e86e68e..bb17291 100644
--- a/services/src/main/java/org/keycloak/authentication/authenticators/client/ClientIdAndSecretAuthenticator.java
+++ b/services/src/main/java/org/keycloak/authentication/authenticators/client/ClientIdAndSecretAuthenticator.java
@@ -12,15 +12,10 @@ import javax.ws.rs.core.Response;
 
 import org.jboss.logging.Logger;
 import org.keycloak.OAuth2Constants;
-import org.keycloak.authentication.AuthenticationFlowContext;
 import org.keycloak.authentication.AuthenticationFlowError;
 import org.keycloak.authentication.ClientAuthenticationFlowContext;
-import org.keycloak.events.Details;
-import org.keycloak.events.Errors;
 import org.keycloak.models.AuthenticationExecutionModel;
 import org.keycloak.models.ClientModel;
-import org.keycloak.models.KeycloakSession;
-import org.keycloak.models.RealmModel;
 import org.keycloak.provider.ProviderConfigProperty;
 import org.keycloak.representations.idm.CredentialRepresentation;
 import org.keycloak.util.BasicAuthHelper;
@@ -147,7 +142,7 @@ public class ClientIdAndSecretAuthenticator extends AbstractClientAuthenticator 
 
     @Override
     public List<ProviderConfigProperty> getConfigPropertiesPerClient() {
-        // This impl doesn't use generic screen in admin console, but has it's own screen. So no need to return anything here
+        // This impl doesn't use generic screen in admin console, but has its own screen. So no need to return anything here
         return Collections.emptyList();
     }
 

diff --git a/services/src/main/java/org/keycloak/authentication/authenticators/client/JWTClientAuthenticator.java b/services/src/main/java/org/keycloak/authentication/authenticators/client/JWTClientAuthenticator.java
index bb87e34..0c308ab 100644
--- a/services/src/main/java/org/keycloak/authentication/authenticators/client/JWTClientAuthenticator.java
+++ b/services/src/main/java/org/keycloak/authentication/authenticators/client/JWTClientAuthenticator.java
@@ -19,7 +19,6 @@ import org.keycloak.jose.jws.JWSInput;
 import org.keycloak.jose.jws.crypto.RSAProvider;
 import org.keycloak.models.AuthenticationExecutionModel;
 import org.keycloak.models.ClientModel;
-import org.keycloak.models.KeycloakSession;
 import org.keycloak.models.RealmModel;
 import org.keycloak.models.utils.KeycloakModelUtils;
 import org.keycloak.provider.ProviderConfigProperty;
@@ -163,7 +162,7 @@ public class JWTClientAuthenticator extends AbstractClientAuthenticator {
 
     @Override
     public List<ProviderConfigProperty> getConfigPropertiesPerClient() {
-        // This impl doesn't use generic screen in admin console, but has it's own screen. So no need to return anything here
+        // This impl doesn't use generic screen in admin console, but has its own screen. So no need to return anything here
         return Collections.emptyList();
     }
 

diff --git a/services/src/main/java/org/keycloak/services/managers/RealmManager.java b/services/src/main/java/org/keycloak/services/managers/RealmManager.java
index bb582af..fb0578e 100755
--- a/services/src/main/java/org/keycloak/services/managers/RealmManager.java
+++ b/services/src/main/java/org/keycloak/services/managers/RealmManager.java
@@ -337,7 +337,7 @@ public class RealmManager implements RealmImporter {
         }
 
         // Could happen when migrating from older version and I have exported JSON file, which contains "realm-management" client but not "impersonation" client
-        // I need to postpone impersonation because it needs "realm-management" client and it's roles set
+        // I need to postpone impersonation because it needs "realm-management" client and its roles set
         if (postponeImpersonationSetup) {
             setupImpersonationService(realm);
         }

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/AttackDetectionResource.java b/services/src/main/java/org/keycloak/services/resources/admin/AttackDetectionResource.java
index 38eec9c..26b9956 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/AttackDetectionResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/AttackDetectionResource.java
@@ -2,64 +2,24 @@ package org.keycloak.services.resources.admin;
 
 import org.jboss.logging.Logger;
 import org.jboss.resteasy.annotations.cache.NoCache;
-import org.jboss.resteasy.spi.BadRequestException;
-import org.jboss.resteasy.spi.NotFoundException;
-import org.jboss.resteasy.spi.ResteasyProviderFactory;
 import org.keycloak.ClientConnection;
-import org.keycloak.events.Event;
-import org.keycloak.events.EventQuery;
-import org.keycloak.events.EventStoreProvider;
-import org.keycloak.events.EventType;
-import org.keycloak.events.admin.AdminEvent;
-import org.keycloak.events.admin.AdminEventQuery;
 import org.keycloak.events.admin.OperationType;
-import org.keycloak.exportimport.ClientImporter;
-import org.keycloak.models.ClientModel;
 import org.keycloak.models.KeycloakSession;
-import org.keycloak.models.ModelDuplicateException;
 import org.keycloak.models.RealmModel;
-import org.keycloak.models.UserFederationProviderModel;
-import org.keycloak.models.UserSessionModel;
 import org.keycloak.models.UsernameLoginFailureModel;
-import org.keycloak.models.cache.CacheRealmProvider;
-import org.keycloak.models.cache.CacheUserProvider;
-import org.keycloak.models.utils.ModelToRepresentation;
-import org.keycloak.models.utils.RepresentationToModel;
-import org.keycloak.protocol.oidc.TokenManager;
-import org.keycloak.representations.adapters.action.GlobalRequestResult;
-import org.keycloak.representations.idm.RealmEventsConfigRepresentation;
-import org.keycloak.representations.idm.RealmRepresentation;
-import org.keycloak.services.ErrorResponse;
-import org.keycloak.services.managers.AuthenticationManager;
 import org.keycloak.services.managers.BruteForceProtector;
-import org.keycloak.services.managers.LDAPConnectionTestManager;
-import org.keycloak.services.managers.RealmManager;
-import org.keycloak.services.managers.ResourceAdminManager;
-import org.keycloak.services.managers.UsersSyncManager;
-import org.keycloak.timer.TimerProvider;
 
-import javax.ws.rs.Consumes;
 import javax.ws.rs.DELETE;
 import javax.ws.rs.GET;
-import javax.ws.rs.POST;
-import javax.ws.rs.PUT;
 import javax.ws.rs.Path;
 import javax.ws.rs.PathParam;
 import javax.ws.rs.Produces;
-import javax.ws.rs.QueryParam;
 import javax.ws.rs.core.Context;
 import javax.ws.rs.core.HttpHeaders;
 import javax.ws.rs.core.MediaType;
-import javax.ws.rs.core.Response;
 import javax.ws.rs.core.UriInfo;
-import java.text.ParseException;
-import java.text.SimpleDateFormat;
-import java.util.Date;
 import java.util.HashMap;
-import java.util.LinkedList;
-import java.util.List;
 import java.util.Map;
-import java.util.regex.PatternSyntaxException;
 
 /**
  * Base resource class for the admin REST api of one realm
@@ -127,7 +87,9 @@ public class AttackDetectionResource {
     }
 
     /**
-     * Clear any user login failures for the user.  This can release temporary disabled user
+     * Clear any user login failures for the user
+     *
+     * This can release temporary disabled user
      *
      * @param username
      */
@@ -143,7 +105,9 @@ public class AttackDetectionResource {
     }
 
     /**
-     * Clear any user login failures for all users.  This can release temporary disabled users
+     * Clear any user login failures for all users
+     *
+     * This can release temporary disabled users
      *
      */
     @Path("brute-force/usernames")

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/AuthenticationManagementResource.java b/services/src/main/java/org/keycloak/services/resources/admin/AuthenticationManagementResource.java
index 0bb2e11..ede2e27 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/AuthenticationManagementResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/AuthenticationManagementResource.java
@@ -6,13 +6,10 @@ import org.jboss.resteasy.spi.BadRequestException;
 import org.jboss.resteasy.spi.NotFoundException;
 import org.keycloak.authentication.AuthenticationFlow;
 import org.keycloak.authentication.Authenticator;
-import org.keycloak.authentication.AuthenticatorUtil;
 import org.keycloak.authentication.ClientAuthenticator;
 import org.keycloak.authentication.ClientAuthenticatorFactory;
 import org.keycloak.authentication.ConfigurableAuthenticatorFactory;
-import org.keycloak.authentication.DefaultAuthenticationFlow;
 import org.keycloak.authentication.FormAction;
-import org.keycloak.authentication.FormAuthenticationFlow;
 import org.keycloak.authentication.FormAuthenticator;
 import org.keycloak.authentication.RequiredActionFactory;
 import org.keycloak.authentication.RequiredActionProvider;
@@ -22,7 +19,6 @@ import org.keycloak.models.AuthenticatorConfigModel;
 import org.keycloak.models.KeycloakSession;
 import org.keycloak.models.RealmModel;
 import org.keycloak.models.RequiredActionProviderModel;
-import org.keycloak.provider.ConfiguredProvider;
 import org.keycloak.provider.ProviderConfigProperty;
 import org.keycloak.provider.ProviderFactory;
 import org.keycloak.representations.idm.ConfigPropertyRepresentation;
@@ -172,6 +168,11 @@ public class AuthenticationManagementResource {
         }
     }
 
+    /**
+     * Get form providers
+     *
+     * Returns a list of form providers.
+     */
     @Path("/form-providers")
     @GET
     @NoCache
@@ -182,6 +183,11 @@ public class AuthenticationManagementResource {
         return buildProviderMetadata(factories);
     }
 
+    /**
+     * Get authenticator providers
+     *
+     * Returns a list of authenticator providers.
+     */
     @Path("/authenticator-providers")
     @GET
     @NoCache
@@ -192,6 +198,11 @@ public class AuthenticationManagementResource {
         return buildProviderMetadata(factories);
     }
 
+    /**
+     * Get client authenticator providers
+     *
+     * Returns a list of client authenticator providers.
+     */
     @Path("/client-authenticator-providers")
     @GET
     @NoCache
@@ -216,6 +227,11 @@ public class AuthenticationManagementResource {
         return providers;
     }
 
+    /**
+     * Get form action providers
+     *
+     * Returns a list of form action providers.
+     */
     @Path("/form-action-providers")
     @GET
     @NoCache
@@ -227,6 +243,11 @@ public class AuthenticationManagementResource {
     }
 
 
+    /**
+     * Get authentication flows
+     *
+     * Returns a list of authentication flows.
+     */
     @Path("/flows")
     @GET
     @NoCache
@@ -242,6 +263,12 @@ public class AuthenticationManagementResource {
         return flows;
     }
 
+    /**
+     * Create a new authentication flow
+     *
+     * @param model Authentication flow model
+     * @return
+     */
     @Path("/flows")
     @POST
     @NoCache
@@ -258,6 +285,12 @@ public class AuthenticationManagementResource {
 
     }
 
+    /**
+     * Get authentication flow for id
+     *
+     * @param id Flow id
+     * @return
+     */
     @Path("/flows/{id}")
     @GET
     @NoCache
@@ -272,6 +305,11 @@ public class AuthenticationManagementResource {
         return flow;
     }
 
+    /**
+     * Delete an authentication flow
+     *
+     * @param id Flow id
+     */
     @Path("/flows/{id}")
     @DELETE
     @NoCache
@@ -288,6 +326,14 @@ public class AuthenticationManagementResource {
         realm.removeAuthenticationFlow(flow);
     }
 
+    /**
+     * Copy existing authentication flow under a new name
+     *
+     * The new name is given as 'newName' attribute of the passed JSON object
+     *
+     * @param flowAlias Name of the existing authentication flow
+     * @param data JSON containing 'newName' attribute
+     */
     @Path("/flows/{flowAlias}/copy")
     @POST
     @NoCache
@@ -338,6 +384,12 @@ public class AuthenticationManagementResource {
         }
     }
 
+    /**
+     * Add new flow with new execution to existing flow
+     *
+     * @param flowAlias Alias of parent authentication flow
+     * @param data New authentication flow / execution JSON data containing 'alias', 'type', 'provider', and 'description' attributes
+     */
     @Path("/flows/{flowAlias}/executions/flow")
     @POST
     @NoCache
@@ -373,6 +425,12 @@ public class AuthenticationManagementResource {
         realm.addAuthenticatorExecution(execution);
     }
 
+    /**
+     * Add new authentication execution to a flow
+     *
+     * @param flowAlias Alias of parent flow
+     * @param data New execution JSON data containing 'provider' attribute
+     */
     @Path("/flows/{flowAlias}/executions/execution")
     @POST
     @NoCache
@@ -395,8 +453,11 @@ public class AuthenticationManagementResource {
         realm.addAuthenticatorExecution(execution);
     }
 
-
-
+    /**
+     * Get authentication executions for a flow
+     *
+     * @param flowAlias Flow alias
+     */
     @Path("/flows/{flowAlias}/executions")
     @GET
     @NoCache
@@ -467,6 +528,12 @@ public class AuthenticationManagementResource {
         }
     }
 
+    /**
+     * Update authentication executions of a flow
+     *
+     * @param flowAlias Flow alias
+     * @param rep
+     */
     @Path("/flows/{flowAlias}/executions")
     @PUT
     @NoCache
@@ -492,6 +559,11 @@ public class AuthenticationManagementResource {
         }
     }
 
+    /**
+     * Add new authentication execution
+     *
+     * @param model JSON model describing authentication execution
+     */
     @Path("/executions")
     @POST
     @NoCache
@@ -525,6 +597,11 @@ public class AuthenticationManagementResource {
         return parentFlow;
     }
 
+    /**
+     * Raise execution's priority
+     *
+     * @param execution Execution id
+     */
     @Path("/executions/{executionId}/raise-priority")
     @POST
     @NoCache
@@ -564,6 +641,11 @@ public class AuthenticationManagementResource {
         return executions;
     }
 
+    /**
+     * Lower execution's priority
+     *
+     * @param execution Execution id
+     */
     @Path("/executions/{executionId}/lower-priority")
     @POST
     @NoCache
@@ -597,6 +679,11 @@ public class AuthenticationManagementResource {
     }
 
 
+    /**
+     * Delete execution
+     *
+     * @param execution Execution id
+     */
     @Path("/executions/{executionId}")
     @DELETE
     @NoCache
@@ -617,9 +704,13 @@ public class AuthenticationManagementResource {
     }
 
 
-
-
-
+    /**
+     * Update execution with new configuration
+     *
+     * @param execution Execution id
+     * @param config JSON with new configuration
+     * @return
+     */
     @Path("/executions/{executionId}/config")
     @POST
     @NoCache
@@ -639,6 +730,12 @@ public class AuthenticationManagementResource {
         return Response.created(uriInfo.getAbsolutePathBuilder().path(config.getId()).build()).build();
     }
 
+    /**
+     * Get execution's configuration
+     *
+     * @param execution Execution id
+     * @param id Configuration id
+     */
     @Path("/executions/{executionId}/config/{id}")
     @GET
     @Produces(MediaType.APPLICATION_JSON)
@@ -702,6 +799,11 @@ public class AuthenticationManagementResource {
         }
     }
 
+    /**
+     * Get unregistered required actions
+     *
+     * Returns a list of unregistered required actions.
+     */
     @Path("unregistered-required-actions")
     @GET
     @Produces(MediaType.APPLICATION_JSON)
@@ -729,6 +831,11 @@ public class AuthenticationManagementResource {
         return unregisteredList;
     }
 
+    /**
+     * Register a new required actions
+     *
+     * @param data JSON containing 'providerId', and 'name' attributes.
+     */
     @Path("register-required-action")
     @POST
     @Consumes(MediaType.APPLICATION_JSON)
@@ -746,7 +853,11 @@ public class AuthenticationManagementResource {
     }
 
 
-
+    /**
+     * Get required actions
+     *
+     * Returns a list of required actions.
+     */
     @Path("required-actions")
     @GET
     @Produces(MediaType.APPLICATION_JSON)
@@ -770,6 +881,10 @@ public class AuthenticationManagementResource {
         return rep;
     }
 
+    /**
+     * Get required action for alias
+     * @param alias Alias of required action
+     */
     @Path("required-actions/{alias}")
     @GET
     @Produces(MediaType.APPLICATION_JSON)
@@ -783,6 +898,12 @@ public class AuthenticationManagementResource {
     }
 
 
+    /**
+     * Update required action
+     *
+     * @param alias Alias of required action
+     * @param rep JSON describing new state of required action
+     */
     @Path("required-actions/{alias}")
     @PUT
     @Consumes(MediaType.APPLICATION_JSON)
@@ -803,6 +924,10 @@ public class AuthenticationManagementResource {
         realm.updateRequiredActionProvider(update);
     }
 
+    /**
+     * Delete required action
+     * @param alias Alias of required action
+     */
     @Path("required-actions/{alias}")
     @DELETE
     public void updateRequiredAction(@PathParam("alias") String alias) {
@@ -855,6 +980,9 @@ public class AuthenticationManagementResource {
     }
 
 
+    /**
+     * Get authenticator provider's configuration description
+     */
     @Path("config-description/{providerId}")
     @GET
     @Produces(MediaType.APPLICATION_JSON)
@@ -888,7 +1016,9 @@ public class AuthenticationManagementResource {
         return propRep;
     }
 
-
+    /**
+     *  Get configuration descriptions for all clients
+     */
     @Path("per-client-config-description")
     @GET
     @Produces(MediaType.APPLICATION_JSON)
@@ -915,6 +1045,10 @@ public class AuthenticationManagementResource {
         return toReturn;
     }
 
+    /**
+     * Create new authenticator configuration
+     * @param config JSON describing new authenticator configuration
+     */
     @Path("config")
     @POST
     @NoCache
@@ -924,6 +1058,10 @@ public class AuthenticationManagementResource {
         return Response.created(uriInfo.getAbsolutePathBuilder().path(config.getId()).build()).build();
     }
 
+    /**
+     * Get authenticator configuration
+     * @param id Configuration id
+     */
     @Path("config/{id}")
     @GET
     @Produces(MediaType.APPLICATION_JSON)
@@ -937,6 +1075,11 @@ public class AuthenticationManagementResource {
         }
         return config;
     }
+
+    /**
+     * Delete authenticator configuration
+     * @param id Configuration id
+     */
     @Path("config/{id}")
     @DELETE
     @NoCache
@@ -959,6 +1102,12 @@ public class AuthenticationManagementResource {
 
         realm.removeAuthenticatorConfig(config);
     }
+
+    /**
+     * Update authenticator configuration
+     * @param id Configuration id
+     * @param config JSON describing new state of authenticator configuration
+     */
     @Path("config/{id}")
     @PUT
     @Consumes(MediaType.APPLICATION_JSON)

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/ClientAttributeCertificateResource.java b/services/src/main/java/org/keycloak/services/resources/admin/ClientAttributeCertificateResource.java
index f6949fc..c6a5fea 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/ClientAttributeCertificateResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/ClientAttributeCertificateResource.java
@@ -64,6 +64,7 @@ public class ClientAttributeCertificateResource {
     }
 
     /**
+     * Get key info
      *
      * @return
      */
@@ -78,6 +79,7 @@ public class ClientAttributeCertificateResource {
     }
 
     /**
+     * Generate a new certificate with new key pair
      *
      * @return
      */
@@ -256,8 +258,9 @@ public class ClientAttributeCertificateResource {
     }
 
     /**
+     * Get a keystore file for the client, containing private key and public certificate
      *
-     * @param config
+     * @param config Keystore configuration as JSON
      * @return
      */
     @POST
@@ -288,10 +291,12 @@ public class ClientAttributeCertificateResource {
     }
 
     /**
-     * Generate new keypair and certificate and downloads private key into specified keystore format. Only generated certificate is saved in Keycloak DB, but private
-     * key is not.
+     * Generate a new keypair and certificate, and get the private key file
      *
-     * @param config
+     * Generates a keypair and certificate and serves the private key in a specified keystore format.
+     * Only generated public certificate is saved in Keycloak DB - the private key is not.
+     *
+     * @param config Keystore configuration as JSON
      * @return
      */
     @POST

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/ClientResource.java b/services/src/main/java/org/keycloak/services/resources/admin/ClientResource.java
index 821f279..2198333 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/ClientResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/ClientResource.java
@@ -92,7 +92,7 @@ public class ClientResource {
     }
 
     /**
-     * Update the client.
+     * Update the client
      * @param rep
      * @return
      */
@@ -116,7 +116,7 @@ public class ClientResource {
 
 
     /**
-     * Get representation of the client.
+     * Get representation of the client
      *
      * @return
      */
@@ -129,6 +129,7 @@ public class ClientResource {
     }
 
     /**
+     * Get representation of certificate resource
      *
      * @param attributePrefix
      * @return
@@ -140,7 +141,9 @@ public class ClientResource {
 
 
     /**
-     * Return keycloak.json file for this client to be used to configure the adapter of that client.
+     * Get keycloak.json file
+     *
+     * Returns a keycloak.json file to be used to configure the adapter of the specified client.
      *
      * @return
      * @throws IOException
@@ -160,7 +163,9 @@ public class ClientResource {
     }
 
     /**
-     * Return XML that can be included in the JBoss/Wildfly Keycloak subsystem to configure the adapter of that client.
+     * Get adapter configuration XML for JBoss / Wildfly Keycloak subsystem
+     *
+     * Returns XML that can be included in the JBoss / Wildfly Keycloak subsystem to configure the adapter of that client.
      *
      * @return
      * @throws IOException
@@ -177,7 +182,7 @@ public class ClientResource {
     }
 
     /**
-     * Delete this client.
+     * Delete the client
      *
      */
     @DELETE
@@ -190,7 +195,7 @@ public class ClientResource {
 
 
     /**
-     * Generates a new secret for this client
+     * Generate a new secret for the client
      *
      * @return
      */
@@ -209,7 +214,7 @@ public class ClientResource {
     }
 
     /**
-     * Get the secret of this client
+     * Get the client secret
      *
      * @return
      */
@@ -227,7 +232,7 @@ public class ClientResource {
     }
 
     /**
-     * Base path for managing the scope mappings for this client
+     * Base path for managing the scope mappings for the client
      *
      * @return
      */
@@ -242,7 +247,9 @@ public class ClientResource {
     }
 
     /**
-     * Returns set of allowed origin.  This is used for CORS requests.  Access tokens will have
+     * Get allowed origins
+     *
+     * This is used for CORS requests.  Access tokens will have
      * their allowedOrigins claim set to this value for tokens created for this client.
      *
      * @return
@@ -258,7 +265,9 @@ public class ClientResource {
     }
 
     /**
-     * Change the set of allowed origins.   This is used for CORS requests.  Access tokens will have
+     * Update allowed origins
+     *
+     * This is used for CORS requests.  Access tokens will have
      * their allowedOrigins claim set to this value for tokens created for this client.
      *
      * @param allowedOrigins
@@ -275,10 +284,12 @@ public class ClientResource {
     }
 
     /**
-     * Remove set of allowed origins from current allowed origins list.  This is used for CORS requests.  Access tokens will have
+     * Delete the specified origins from current allowed origins
+     *
+     * This is used for CORS requests.  Access tokens will have
      * their allowedOrigins claim set to this value for tokens created for this client.
      *
-     * @param allowedOrigins
+     * @param allowedOrigins List of origins to delete
      */
     @Path("allowed-origins")
     @DELETE
@@ -294,7 +305,7 @@ public class ClientResource {
     }
 
     /**
-     * Returns user dedicated to this service account
+     * Get a user dedicated to the service account
      *
      * @return
      */
@@ -319,8 +330,9 @@ public class ClientResource {
     }
 
     /**
-     * If the client has an admin URL, push the client's revocation policy to it.
+     * Push the client's revocation policy to its admin URL
      *
+     * If the client has an admin URL, push revocation policy to it.
      */
     @Path("push-revocation")
     @POST
@@ -332,7 +344,9 @@ public class ClientResource {
     }
     
     /**
-     * Number of user sessions associated with this client
+     * Get application session count
+     *
+     * Returns a number of user sessions associated with this client
      *
      * {
      *     "count": number
@@ -352,8 +366,12 @@ public class ClientResource {
     }
 
     /**
-     * Return a list of user sessions associated with this client
+     * Get user sessions for client
+     *
+     * Returns a list of user sessions associated with this client
      *
+     * @param firstResult Paging offset
+     * @param maxResults Paging size
      * @return
      */
     @Path("user-sessions")
@@ -373,6 +391,8 @@ public class ClientResource {
     }
 
     /**
+     * Logout all sessions
+     *
      * If the client has an admin URL, invalidate all sessions associated with that client directly.
      *
      */
@@ -386,6 +406,8 @@ public class ClientResource {
     }
 
     /**
+     * Logout the user by username
+     *
      * If the client has an admin URL, invalidate the sessions for a particular user directly.
      *
      */
@@ -403,6 +425,8 @@ public class ClientResource {
     }
 
     /**
+     * Register a cluster node with the client
+     *
      * Manually register cluster node to this client - usually it's not needed to call this directly as adapter should handle
      * by sending registration request to Keycloak
      *
@@ -423,7 +447,7 @@ public class ClientResource {
     }
 
     /**
-     * Unregister cluster node from this client
+     * Unregister a cluster node from the client
      *
      * @param node
      */
@@ -443,7 +467,9 @@ public class ClientResource {
     }
 
     /**
-     * Test if registered cluster nodes are available by sending 'ping' request to all of them
+     * Test if registered cluster nodes are available
+     *
+     * Tests availability by sending 'ping' request to all cluster nodes.
      *
      * @return
      */

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/ClientsResource.java b/services/src/main/java/org/keycloak/services/resources/admin/ClientsResource.java
index 862aa09..e780dbf 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/ClientsResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/ClientsResource.java
@@ -52,9 +52,9 @@ public class ClientsResource {
     }
 
     /**
-     * List of clients belonging to this realm.
+     * Get clients belonging to the realm
      *
-     * @return
+     * Returns a list of clients belonging to the realm
      */
     @GET
     @Produces(MediaType.APPLICATION_JSON)
@@ -80,7 +80,9 @@ public class ClientsResource {
     }
 
     /**
-     * Create a new client.  Client client_id must be unique!
+     * Create a new client
+     *
+     * Client's client_id must be unique!
      *
      * @param uriInfo
      * @param rep

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java b/services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java
index eeffe5d..bf17f4b 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java
@@ -7,7 +7,6 @@ import org.keycloak.broker.provider.IdentityProvider;
 import org.keycloak.broker.provider.IdentityProviderFactory;
 import org.keycloak.broker.provider.IdentityProviderMapper;
 import org.keycloak.events.admin.OperationType;
-import org.keycloak.models.ClientModel;
 import org.keycloak.models.FederatedIdentityModel;
 import org.keycloak.models.IdentityProviderMapperModel;
 import org.keycloak.models.IdentityProviderModel;
@@ -70,6 +69,11 @@ public class IdentityProviderResource {
         this.adminEvent = adminEvent;
     }
 
+    /**
+     * Get the identity provider
+     *
+     * @return
+     */
     @GET
     @NoCache
     @Produces(MediaType.APPLICATION_JSON)
@@ -79,6 +83,11 @@ public class IdentityProviderResource {
         return rep;
     }
 
+    /**
+     * Delete the identity provider
+     *
+     * @return
+     */
     @DELETE
     @NoCache
     public Response delete() {
@@ -91,6 +100,12 @@ public class IdentityProviderResource {
         return Response.noContent().build();
     }
 
+    /**
+     * Update the identity provider
+     *
+     * @param providerRep
+     * @return
+     */
     @PUT
     @Consumes(MediaType.APPLICATION_JSON)
     @NoCache
@@ -161,7 +176,13 @@ public class IdentityProviderResource {
         return null;
     }
 
-
+    /**
+     * Export public broker configuration for identity provider
+     *
+     * @param uriInfo
+     * @param format Format to use
+     * @return
+     */
     @GET
     @Path("export")
     @NoCache
@@ -175,6 +196,9 @@ public class IdentityProviderResource {
         }
     }
 
+    /**
+     * Get mapper types for identity provider
+     */
     @GET
     @Path("mapper-types")
     @NoCache
@@ -210,6 +234,9 @@ public class IdentityProviderResource {
         return types;
     }
 
+    /**
+     * Get mappers for identity provider
+     */
     @GET
     @Path("mappers")
     @Produces(MediaType.APPLICATION_JSON)
@@ -223,6 +250,12 @@ public class IdentityProviderResource {
         return mappers;
     }
 
+    /**
+     * Add a mapper to identity provider
+     *
+     * @param mapper
+     * @return
+     */
     @POST
     @Path("mappers")
     @Consumes(MediaType.APPLICATION_JSON)
@@ -238,6 +271,12 @@ public class IdentityProviderResource {
 
     }
 
+    /**
+     * Get mapper by id for the identity provider
+     *
+     * @param id
+     * @return
+     */
     @GET
     @NoCache
     @Path("mappers/{id}")
@@ -249,6 +288,12 @@ public class IdentityProviderResource {
         return ModelToRepresentation.toRepresentation(model);
     }
 
+    /**
+     * Update a mapper for the identity provider
+     *
+     * @param id Mapper id
+     * @param rep
+     */
     @PUT
     @NoCache
     @Path("mappers/{id}")
@@ -263,6 +308,11 @@ public class IdentityProviderResource {
 
     }
 
+    /**
+     * Delete a mapper for the identity provider
+     *
+     * @param id Mapper id
+     */
     @DELETE
     @NoCache
     @Path("mappers/{id}")

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/IdentityProvidersResource.java b/services/src/main/java/org/keycloak/services/resources/admin/IdentityProvidersResource.java
index 8b2a049..d3dc33a 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/IdentityProvidersResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/IdentityProvidersResource.java
@@ -57,6 +57,12 @@ public class IdentityProvidersResource {
         this.adminEvent = adminEvent;
     }
 
+    /**
+     * Get identity providers
+     *
+     * @param providerId Provider id
+     * @return
+     */
     @Path("/providers/{provider_id}")
     @GET
     @NoCache
@@ -70,6 +76,14 @@ public class IdentityProvidersResource {
         return Response.status(BAD_REQUEST).build();
     }
 
+    /**
+     * Import identity provider from uploaded JSON file
+     *
+     * @param uriInfo
+     * @param input
+     * @return
+     * @throws IOException
+     */
     @POST
     @Path("import-config")
     @Consumes(MediaType.MULTIPART_FORM_DATA)
@@ -85,6 +99,14 @@ public class IdentityProvidersResource {
         return config;
     }
 
+    /**
+     * Import identity provider from JSON body
+     *
+     * @param uriInfo
+     * @param data JSON body
+     * @return
+     * @throws IOException
+     */
     @POST
     @Path("import-config")
     @Consumes(MediaType.APPLICATION_JSON)
@@ -108,6 +130,11 @@ public class IdentityProvidersResource {
         }
     }
 
+    /**
+     * Get identity providers
+     *
+     * @return
+     */
     @GET
     @Path("instances")
     @NoCache
@@ -123,6 +150,13 @@ public class IdentityProvidersResource {
         return representations;
     }
 
+    /**
+     * Create a new identity provider
+     *
+     * @param uriInfo
+     * @param representation JSON body
+     * @return
+     */
     @POST
     @Path("instances")
     @Consumes(MediaType.APPLICATION_JSON)

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/info/ServerInfoAdminResource.java b/services/src/main/java/org/keycloak/services/resources/admin/info/ServerInfoAdminResource.java
index fd0afc9..70022c0 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/info/ServerInfoAdminResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/info/ServerInfoAdminResource.java
@@ -38,7 +38,7 @@ public class ServerInfoAdminResource {
     private KeycloakSession session;
 
     /**
-     * Returns a list of themes, social providers, auth providers, and event listeners available on this server
+     * Get themes, social providers, auth providers, and event listeners available on this server
      *
      * @return
      */

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/ProtocolMappersResource.java b/services/src/main/java/org/keycloak/services/resources/admin/ProtocolMappersResource.java
index 145a26d..306d350 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/ProtocolMappersResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/ProtocolMappersResource.java
@@ -7,7 +7,6 @@ import org.keycloak.events.admin.OperationType;
 import org.keycloak.models.ClientModel;
 import org.keycloak.models.KeycloakSession;
 import org.keycloak.models.ProtocolMapperModel;
-import org.keycloak.models.RealmModel;
 import org.keycloak.models.utils.ModelToRepresentation;
 import org.keycloak.models.utils.RepresentationToModel;
 import org.keycloak.representations.idm.ProtocolMapperRepresentation;
@@ -39,7 +38,7 @@ public class ProtocolMappersResource {
     
     protected ClientModel client;
 
-    protected  RealmAuth auth;
+    protected RealmAuth auth;
     
     protected AdminEventBuilder adminEvent;
 
@@ -58,7 +57,7 @@ public class ProtocolMappersResource {
     }
 
     /**
-     * Map of mappers by name for a specific protocol
+     * Get mappers by name for a specific protocol
      *
      * @param protocol
      * @return
@@ -77,7 +76,7 @@ public class ProtocolMappersResource {
     }
 
     /**
-     * creates mapper
+     * Create a mapper
      *
      * @param rep
      */
@@ -93,7 +92,7 @@ public class ProtocolMappersResource {
         return Response.created(uriInfo.getAbsolutePathBuilder().path(model.getId()).build()).build();
     }
     /**
-     * creates multiple mapper
+     * Create multiple mappers
      *
      */
     @Path("add-models")
@@ -110,6 +109,11 @@ public class ProtocolMappersResource {
         adminEvent.operation(OperationType.CREATE).resourcePath(uriInfo).representation(reps).success();
     }
 
+    /**
+     * Get mappers
+     *
+     * @return
+     */
     @GET
     @NoCache
     @Path("models")
@@ -123,6 +127,12 @@ public class ProtocolMappersResource {
         return mappers;
     }
 
+    /**
+     * Get mapper by id
+     *
+     * @param id Mapper id
+     * @return
+     */
     @GET
     @NoCache
     @Path("models/{id}")
@@ -134,6 +144,12 @@ public class ProtocolMappersResource {
         return ModelToRepresentation.toRepresentation(model);
     }
 
+    /**
+     * Update the mapper
+     *
+     * @param id Mapper id
+     * @param rep
+     */
     @PUT
     @NoCache
     @Path("models/{id}")
@@ -147,6 +163,11 @@ public class ProtocolMappersResource {
         adminEvent.operation(OperationType.UPDATE).resourcePath(uriInfo).representation(rep).success();
     }
 
+    /**
+     * Delete the mapper
+     *
+     * @param id Mapper id
+     */
     @DELETE
     @NoCache
     @Path("models/{id}")

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/RealmAdminResource.java b/services/src/main/java/org/keycloak/services/resources/admin/RealmAdminResource.java
index 40710a1..bab74d6 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/RealmAdminResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/RealmAdminResource.java
@@ -6,8 +6,6 @@ import org.jboss.resteasy.spi.BadRequestException;
 import org.jboss.resteasy.spi.NotFoundException;
 import org.jboss.resteasy.spi.ResteasyProviderFactory;
 import org.keycloak.ClientConnection;
-import org.keycloak.authentication.RequiredActionFactory;
-import org.keycloak.authentication.RequiredActionProvider;
 import org.keycloak.events.Event;
 import org.keycloak.events.EventQuery;
 import org.keycloak.events.EventStoreProvider;
@@ -27,7 +25,6 @@ import org.keycloak.models.cache.CacheUserProvider;
 import org.keycloak.models.utils.ModelToRepresentation;
 import org.keycloak.models.utils.RepresentationToModel;
 import org.keycloak.protocol.oidc.TokenManager;
-import org.keycloak.provider.ProviderFactory;
 import org.keycloak.representations.adapters.action.GlobalRequestResult;
 import org.keycloak.representations.idm.RealmEventsConfigRepresentation;
 import org.keycloak.representations.idm.RealmRepresentation;
@@ -143,7 +140,9 @@ public class RealmAdminResource {
     }
 
     /**
-     * Get the top-level representation of the realm.  It will not include nested information like User and Client representations.
+     * Get the top-level representation of the realm
+     *
+     * It will not include nested information like User and Client representations.
      *
      * @return
      */
@@ -172,7 +171,9 @@ public class RealmAdminResource {
     }
 
     /**
-     * Update the top-level information of this realm.  Any user, roles or client information in the representation
+     * Update the top-level information of the realm
+     *
+     * Any user, roles or client information in the representation
      * will be ignored.  This will only update top-level attributes of the realm.
      *
      * @param rep
@@ -215,7 +216,7 @@ public class RealmAdminResource {
     }
 
     /**
-     * Delete this realm.
+     * Delete the realm
      *
      */
     @DELETE
@@ -260,7 +261,7 @@ public class RealmAdminResource {
     }
 
     /**
-     * Path for managing all realm-level or client-level roles defined in this realm by it's id.
+     * Path for managing all realm-level or client-level roles defined in this realm by its id.
      *
      * @return
      */
@@ -316,8 +317,10 @@ public class RealmAdminResource {
     }
 
     /**
+     * Get client session stats
+     *
      * Returns a JSON map.  The key is the client id, the value is the number of sessions that currently are active
-     * with that client.  Only client's that actually have a session associated with them will be in this map.
+     * with that client.  Only clients that actually have a session associated with them will be in this map.
      *
      * @return
      */
@@ -341,7 +344,9 @@ public class RealmAdminResource {
     }
 
     /**
-     * View the events provider and how it is configured.
+     * Get the events provider configuration
+     *
+     * Returns JSON object with events provider configuration
      *
      * @return
      */
@@ -356,7 +361,9 @@ public class RealmAdminResource {
     }
 
     /**
-     * Change the events provider and/or it's configuration
+     * Update the events provider
+     *
+     * Change the events provider and/or its configuration
      *
      * @param rep
      */
@@ -371,15 +378,17 @@ public class RealmAdminResource {
     }
 
     /**
-     * Query events.  Returns all events, or will query based on URL query parameters listed here
+     * Get events
      *
-     * @param client app or oauth client name
-     * @param user user id
-     * @param ipAddress
-     * @param dateTo
-     * @param dateFrom
-     * @param firstResult
-     * @param maxResults
+     * Returns all events, or filters them based on URL query parameters listed here
+     *
+     * @param client App or oauth client name
+     * @param user User id
+     * @param ipAddress IP address
+     * @param dateTo To date
+     * @param dateFrom From date
+     * @param firstResult Paging offset
+     * @param maxResults Paging size
      * @return
      */
     @Path("events")
@@ -448,7 +457,9 @@ public class RealmAdminResource {
     }
     
     /**
-     * Query admin events.  Returns all admin events, or will query based on URL query parameters listed here
+     * Get admin events
+     *
+     * Returns all admin events, or filters events based on URL query parameters listed here
      *
      * @param authRealm
      * @param authClient
@@ -538,7 +549,7 @@ public class RealmAdminResource {
     }
 
     /**
-     * Delete all events.
+     * Delete all events
      *
      */
     @Path("events")
@@ -551,7 +562,7 @@ public class RealmAdminResource {
     }
     
     /**
-     * Delete all admin events.
+     * Delete all admin events
      *
      */
     @Path("admin-events")
@@ -563,6 +574,15 @@ public class RealmAdminResource {
         eventStore.clearAdmin(realm.getId());
     }
 
+    /**
+     * Test LDAP connection
+     *
+     * @param action
+     * @param connectionUrl
+     * @param bindDn
+     * @param bindCredential
+     * @return
+     */
     @Path("testLDAPConnection")
     @GET
     @NoCache

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/RealmsAdminResource.java b/services/src/main/java/org/keycloak/services/resources/admin/RealmsAdminResource.java
index f2494c9..d0fb521 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/RealmsAdminResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/RealmsAdminResource.java
@@ -73,7 +73,9 @@ public class RealmsAdminResource {
     }
 
     /**
-     * Returns a list of realms.  This list is filtered based on what realms the caller is allowed to view.
+     * Get accessible realms
+     *
+     * Returns a list of accessible realms. The list is filtered based on what realms the caller is allowed to view.
      *
      * @return
      */
@@ -107,10 +109,12 @@ public class RealmsAdminResource {
     }
 
     /**
-     * Import a realm from a full representation of that realm.  Realm name must be unique.
+     * Import a realm
+     *
+     * Imports a realm from a full representation of that realm.  Realm name must be unique.
      *
      * @param uriInfo
-     * @param rep JSON representation
+     * @param rep JSON representation of the realm
      * @return
      */
     @POST
@@ -141,7 +145,9 @@ public class RealmsAdminResource {
     }
 
     /**
-     * Upload a realm from a uploaded JSON file.  The posted represenation is expected to be a multipart/form-data encapsulation
+     * Import a realm from uploaded JSON file
+     *
+     * The posted represenation is expected to be a multipart/form-data encapsulation
      * of a JSON file.  The same format a browser would use when uploading a file.
      *
      * @param uriInfo

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/RoleByIdResource.java b/services/src/main/java/org/keycloak/services/resources/admin/RoleByIdResource.java
index bea5d52..1482cab 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/RoleByIdResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/RoleByIdResource.java
@@ -87,7 +87,7 @@ public class RoleByIdResource extends RoleResource {
     }
 
     /**
-     * Delete this role
+     * Delete the role
      *
      * @param id id of role
      */
@@ -102,7 +102,7 @@ public class RoleByIdResource extends RoleResource {
     }
 
     /**
-     * Update this role
+     * Update the role
      *
      * @param id id of role
      * @param rep
@@ -118,7 +118,7 @@ public class RoleByIdResource extends RoleResource {
     }
 
     /**
-     * Make this role a composite role by associating some child roles to it.
+     * Make the role a composite role by associating some child roles
      *
      * @param id
      * @param roles
@@ -133,7 +133,9 @@ public class RoleByIdResource extends RoleResource {
     }
 
     /**
-     * If this role is a composite, return a set of its children
+     * Get role's children
+     *
+     * Returns a set of role's children provided the role is a composite.
      *
      * @param id
      * @return
@@ -151,7 +153,7 @@ public class RoleByIdResource extends RoleResource {
     }
 
     /**
-     * Return a set of realm-level roles that are in the role's composite
+     * Get realm-level roles that are in the role's composite
      *
      * @param id
      * @return
@@ -167,7 +169,7 @@ public class RoleByIdResource extends RoleResource {
     }
 
     /**
-     * Return a set of client-level roles for a specific client that are in the role's composite
+     * Get client-level roles for the client that are in the role's composite
      *
      * @param id
      * @param client
@@ -189,7 +191,7 @@ public class RoleByIdResource extends RoleResource {
     }
 
     /**
-     * Return a set of client-level roles for a specific client that are in the role's composite
+     * Get client-level roles for the client that are in the role's composite
      *
      * @param role
      * @param client
@@ -212,10 +214,10 @@ public class RoleByIdResource extends RoleResource {
     }
 
     /**
-     * Remove the listed set of roles from this role's composite
+     * Remove a set of roles from the role's composite
      *
-     * @param id
-     * @param roles
+     * @param id Role id
+     * @param roles A set of roles to be removed
      */
     @Path("{role-id}/composites")
     @DELETE

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/RoleContainerResource.java b/services/src/main/java/org/keycloak/services/resources/admin/RoleContainerResource.java
index f267d15..168ff47 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/RoleContainerResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/RoleContainerResource.java
@@ -4,7 +4,6 @@ import org.jboss.resteasy.annotations.cache.NoCache;
 import org.jboss.resteasy.spi.NotFoundException;
 import org.keycloak.events.admin.OperationType;
 import org.keycloak.models.ClientModel;
-import org.keycloak.models.KeycloakSession;
 import org.keycloak.models.ModelDuplicateException;
 import org.keycloak.models.RealmModel;
 import org.keycloak.models.RoleContainerModel;
@@ -51,7 +50,7 @@ public class RoleContainerResource extends RoleResource {
     }
 
     /**
-     * List all roles for this realm or client
+     * Get all roles for the realm or client
      *
      * @return
      */
@@ -70,7 +69,7 @@ public class RoleContainerResource extends RoleResource {
     }
 
     /**
-     * Create a new role for this realm or client
+     * Create a new role for the realm or client
      *
      * @param rep
      * @return
@@ -164,7 +163,7 @@ public class RoleContainerResource extends RoleResource {
     }
 
     /**
-     * Add a composite to this role
+     * Add a composite to the role
      *
      * @param roleName role's name (not id!)
      * @param roles
@@ -183,7 +182,7 @@ public class RoleContainerResource extends RoleResource {
     }
 
     /**
-     * List composites of this role
+     * Get composites of the role
      *
      * @param roleName role's name (not id!)
      * @return
@@ -203,7 +202,7 @@ public class RoleContainerResource extends RoleResource {
     }
 
     /**
-     * Get realm-level roles of this role's composite
+     * Get realm-level roles of the role's composite
      *
      * @param roleName role's name (not id!)
      * @return
@@ -223,7 +222,7 @@ public class RoleContainerResource extends RoleResource {
     }
 
     /**
-     * An app-level roles for a specific app for this role's composite
+     * An app-level roles for the specified app for the role's composite
      *
      * @param roleName role's name (not id!)
      * @param client
@@ -252,7 +251,7 @@ public class RoleContainerResource extends RoleResource {
 
 
     /**
-     * Remove roles from this role's composite
+     * Remove roles from the role's composite
      *
      * @param roleName role's name (not id!)
      * @param roles roles to remove

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedClientResource.java b/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedClientResource.java
index c087197..44b355e 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedClientResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedClientResource.java
@@ -44,7 +44,9 @@ public class ScopeMappedClientResource {
     }
 
     /**
-     * Get the roles associated with a client's scope for a specific client.
+     * Get the roles associated with a client's scope
+     *
+     * Returns roles for the client.
      *
      * @return
      */
@@ -63,7 +65,9 @@ public class ScopeMappedClientResource {
     }
 
     /**
-     * The available client-level roles that can be associated with the client's scope
+     * The available client-level roles
+     *
+     * Returns the roles for the client that can be associated with the client's scope
      *
      * @return
      */
@@ -79,7 +83,9 @@ public class ScopeMappedClientResource {
     }
 
     /**
-     * Get effective client roles that are associated with the client's scope for a specific client.
+     * Get effective client roles
+     *
+     * Returns the roles for the client that are associated with the client's scope.
      *
      * @return
      */

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedResource.java b/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedResource.java
index 4075944..2d9b6a2 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedResource.java
@@ -19,9 +19,7 @@ import javax.ws.rs.POST;
 import javax.ws.rs.Path;
 import javax.ws.rs.PathParam;
 import javax.ws.rs.Produces;
-import javax.ws.rs.core.Context;
 import javax.ws.rs.core.MediaType;
-import javax.ws.rs.core.UriInfo;
 
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -51,7 +49,7 @@ public class ScopeMappedResource {
     }
 
     /**
-     * Get all scope mappings for this client
+     * Get all scope mappings for the client
      *
      * @return
      */
@@ -94,7 +92,7 @@ public class ScopeMappedResource {
     }
 
     /**
-     * Get list of realm-level roles associated with this client's scope.
+     * Get realm-level roles associated with the client's scope
      *
      * @return
      */
@@ -114,7 +112,7 @@ public class ScopeMappedResource {
     }
 
     /**
-     * Get list of realm-level roles that are available to attach to this client's scope.
+     * Get realm-level roles that are available to attach to this client's scope
      *
      * @return
      */
@@ -139,7 +137,9 @@ public class ScopeMappedResource {
     }
 
     /**
-     * Get all effective realm-level roles that are associated with this client's scope.  What this does is recurse
+     * Get effective realm-level roles associated with the client's scope
+     *
+     * What this does is recurse
      * any composite roles associated with the client's scope and adds the roles to this lists.  The method is really
      * to show a comprehensive total view of realm-level roles associated with the client.
      *

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/UserClientRoleMappingsResource.java b/services/src/main/java/org/keycloak/services/resources/admin/UserClientRoleMappingsResource.java
index 228ebbd..8c5851c 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/UserClientRoleMappingsResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/UserClientRoleMappingsResource.java
@@ -5,7 +5,6 @@ import org.jboss.resteasy.annotations.cache.NoCache;
 import org.jboss.resteasy.spi.NotFoundException;
 import org.keycloak.events.admin.OperationType;
 import org.keycloak.models.ClientModel;
-import org.keycloak.models.KeycloakSession;
 import org.keycloak.models.RealmModel;
 import org.keycloak.models.RoleModel;
 import org.keycloak.models.UserModel;
@@ -18,7 +17,6 @@ import javax.ws.rs.GET;
 import javax.ws.rs.POST;
 import javax.ws.rs.Path;
 import javax.ws.rs.Produces;
-import javax.ws.rs.core.Context;
 import javax.ws.rs.core.MediaType;
 import javax.ws.rs.core.UriInfo;
 
@@ -51,7 +49,7 @@ public class UserClientRoleMappingsResource {
     }
 
     /**
-     * Get client-level role mappings for this user for a specific app
+     * Get client-level role mappings for the user, and the app
      *
      * @return
      */
@@ -70,7 +68,9 @@ public class UserClientRoleMappingsResource {
     }
 
     /**
-     * Get effective client-level role mappings.  This recurses any composite roles
+     * Get effective client-level role mappings
+     *
+     * This recurses any composite roles
      *
      * @return
      */
@@ -120,9 +120,9 @@ public class UserClientRoleMappingsResource {
     }
 
     /**
-     * Add client-level roles to the user role mapping.
+     * Add client-level roles to the user role mapping
      *
-      * @param roles
+     * @param roles
      */
     @POST
     @Consumes(MediaType.APPLICATION_JSON)
@@ -141,7 +141,7 @@ public class UserClientRoleMappingsResource {
     }
 
     /**
-     * Delete client-level roles from user role mapping.
+     * Delete client-level roles from user role mapping
      *
      * @param roles
      */

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProviderResource.java b/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProviderResource.java
index db1e278..6f7bedf 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProviderResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProviderResource.java
@@ -98,7 +98,7 @@ public class UserFederationProviderResource {
     }
 
     /**
-     * get a provider
+     * Get a provider
      *
      */
     @GET
@@ -126,7 +126,7 @@ public class UserFederationProviderResource {
     }
 
     /**
-     * trigger sync of users
+     * Trigger sync of users
      *
      * @return
      */
@@ -150,7 +150,7 @@ public class UserFederationProviderResource {
     }
 
     /**
-     * List of available User Federation mapper types
+     * Get available user federation mapper types
      *
      * @return
      */
@@ -227,7 +227,7 @@ public class UserFederationProviderResource {
     }
 
     /**
-     * Create mapper
+     * Create a mapper
      *
      * @param mapper
      * @return
@@ -251,9 +251,9 @@ public class UserFederationProviderResource {
     }
 
     /**
-     * Get mapper
+     * Get a mapper
      *
-     * @param id mapperId
+     * @param id Mapper id
      * @return
      */
     @GET
@@ -268,9 +268,9 @@ public class UserFederationProviderResource {
     }
 
     /**
-     * Update mapper
+     * Update a mapper
      *
-     * @param id
+     * @param id Mapper id
      * @param rep
      */
     @PUT
@@ -291,9 +291,9 @@ public class UserFederationProviderResource {
     }
 
     /**
-     * Delete mapper with given ID
+     * Delete a mapper with a given id
      *
-     * @param id
+     * @param id Mapper id
      */
     @DELETE
     @NoCache

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProvidersResource.java b/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProvidersResource.java
index 294e633..8946c36 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProvidersResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProvidersResource.java
@@ -8,8 +8,6 @@ import org.keycloak.constants.KerberosConstants;
 import org.keycloak.events.admin.OperationType;
 import org.keycloak.models.KeycloakSession;
 import org.keycloak.models.RealmModel;
-import org.keycloak.models.RequiredCredentialModel;
-import org.keycloak.models.UserCredentialModel;
 import org.keycloak.models.UserFederationProvider;
 import org.keycloak.models.UserFederationProviderFactory;
 import org.keycloak.models.UserFederationProviderModel;
@@ -84,7 +82,9 @@ public class UserFederationProvidersResource {
     }
 
     /**
-     * Get List of available provider factories
+     * Get available provider factories
+     *
+     * Returns a list of available provider factories.
      *
      * @return
      */
@@ -105,7 +105,7 @@ public class UserFederationProvidersResource {
     }
 
     /**
-     * Get factory with given ID
+     * Get factory with given id
      *
      * @return
      */
@@ -159,7 +159,7 @@ public class UserFederationProvidersResource {
     }
 
     /**
-     * list configured providers
+     * Get configured providers
      *
      * @return
      */

diff --git a/services/src/main/java/org/keycloak/services/resources/admin/UsersResource.java b/services/src/main/java/org/keycloak/services/resources/admin/UsersResource.java
index e3e2437..24aa35a 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/UsersResource.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/UsersResource.java
@@ -118,7 +118,7 @@ public class UsersResource {
     /**
      * Update the user
      *
-     * @param id
+     * @param id User id
      * @param rep
      * @return
      */
@@ -164,7 +164,9 @@ public class UsersResource {
     }
 
     /**
-     * Create a new user.  Must be a unique username!
+     * Create a new user
+     *
+     * Username must be unique.
      *
      * @param uriInfo
      * @param rep
@@ -245,7 +247,7 @@ public class UsersResource {
     /**
      * Get represenation of the user
      *
-     * @param id user id
+     * @param id User id
      * @return
      */
     @Path("{id}")
@@ -274,6 +276,12 @@ public class UsersResource {
         return rep;
     }
 
+    /**
+     * Impersonate the user
+     *
+     * @param id User id
+     * @return
+     */
     @Path("{id}/impersonation")
     @POST
     @NoCache
@@ -314,9 +322,9 @@ public class UsersResource {
 
 
     /**
-     * List set of sessions associated with this user.
+     * Get sessions associated with the user
      *
-     * @param id
+     * @param id User id
      * @return
      */
     @Path("{id}/sessions")
@@ -339,9 +347,9 @@ public class UsersResource {
     }
 
     /**
-     * List set of social logins associated with this user.
+     * Get social logins associated with the user
      *
-     * @param id
+     * @param id User id
      * @return
      */
     @Path("{id}/federated-identity")
@@ -373,6 +381,14 @@ public class UsersResource {
         return result;
     }
 
+    /**
+     * Add a social login provider to the user
+     *
+     * @param id User id
+     * @param provider Social login provider id
+     * @param rep
+     * @return
+     */
     @Path("{id}/federated-identity/{provider}")
     @POST
     @NoCache
@@ -392,6 +408,12 @@ public class UsersResource {
         return Response.noContent().build();
     }
 
+    /**
+     * Remove a social login provider from user
+     *
+     * @param id User id
+     * @param provider Social login provider id
+     */
     @Path("{id}/federated-identity/{provider}")
     @DELETE
     @NoCache
@@ -408,9 +430,9 @@ public class UsersResource {
     }
 
     /**
-     * List set of consents granted by this user.
+     * Get consents granted by the user
      *
-     * @param id
+     * @param id User id
      * @return
      */
     @Path("{id}/consents")
@@ -435,10 +457,10 @@ public class UsersResource {
     }
 
     /**
-     * Revoke consent for particular client
+     * Revoke consent for particular client from user
      *
-     * @param id
-     * @param clientId
+     * @param id User id
+     * @param clientId Client id
      */
     @Path("{id}/consents/{client}")
     @DELETE
@@ -462,10 +484,11 @@ public class UsersResource {
     }
 
     /**
-     * Remove all user sessions associated with this user.  And, for all client that have an admin URL, tell
-     * them to invalidate the sessions for this particular user.
+     * Remove all user sessions associated with the user
+     *
+     * Also send notification to all clients that have an admin URL to invalidate the sessions for the particular user.
      *
-     * @param id user id
+     * @param id User id
      */
     @Path("{id}/logout")
     @POST
@@ -484,9 +507,9 @@ public class UsersResource {
     }
 
     /**
-     * delete this user
+     * Delete the user
      *
-     * @param id user id
+     * @param id User id
      */
     @Path("{id}")
     @DELETE
@@ -509,13 +532,17 @@ public class UsersResource {
     }
 
     /**
-     * Query list of users.  May pass in query criteria
+     * Get users
      *
-     * @param search string contained in username, first or last name, or email
+     * Returns a list of users, filtered according to query parameters
+     *
+     * @param search A String contained in username, first or last name, or email
      * @param last
      * @param first
      * @param email
      * @param username
+     * @param first Pagination offset
+     * @param maxResults Pagination size
      * @return
      */
     @GET
@@ -563,9 +590,9 @@ public class UsersResource {
     }
 
     /**
-     * Get role mappings for this user
+     * Get role mappings for the user
      *
-     * @param id user id
+     * @param id User id
      * @return
      */
     @Path("{id}/role-mappings")
@@ -614,9 +641,9 @@ public class UsersResource {
     }
 
     /**
-     * Get realm-level role mappings for this user
+     * Get realm-level role mappings for the user
      *
-     * @param id user id
+     * @param id User id
      * @return
      */
     @Path("{id}/role-mappings/realm")
@@ -640,9 +667,11 @@ public class UsersResource {
     }
 
     /**
-     * Effective realm-level role mappings for this user.  Will recurse all composite roles to get this list.
+     * Get effective realm-level role mappings for the user
+     *
+     * This will recurse all composite roles to get the result.
      *
-     * @param id user id
+     * @param id User id
      * @return
      */
     @Path("{id}/role-mappings/realm/composite")
@@ -668,9 +697,9 @@ public class UsersResource {
     }
 
     /**
-     * Realm-level roles that can be mapped to this user
+     * Get realm-level roles that can be mapped to this user
      *
-     * @param id
+     * @param id User id
      * @return
      */
     @Path("{id}/role-mappings/realm/available")
@@ -690,10 +719,10 @@ public class UsersResource {
     }
 
     /**
-     * Add realm-level role mappings
+     * Add realm-level role mappings to the user
      *
-     * @param id
-     * @param roles
+     * @param id User id
+     * @param roles Roles to add
      */
     @Path("{id}/role-mappings/realm")
     @POST
@@ -720,7 +749,7 @@ public class UsersResource {
     /**
      * Delete realm-level role mappings
      *
-     * @param id user id
+     * @param id User id
      * @param roles
      */
     @Path("{id}/role-mappings/realm")
@@ -770,12 +799,14 @@ public class UsersResource {
         return new UserClientRoleMappingsResource(uriInfo, realm, auth, user, clientModel, adminEvent);
 
     }
+
     /**
-     *  Set up a temporary password for this user.  User will have to reset this temporary password when they log
-     *  in next.
+     * Set up a temporary password for the user
+     *
+     * User will have to reset the temporary password next time they log in.
      *
-     * @param id
-     * @param pass temporary password
+     * @param id User id
+     * @param pass A Temporary password
      */
     @Path("{id}/reset-password")
     @PUT
@@ -805,9 +836,9 @@ public class UsersResource {
     }
 
     /**
+     * Remove TOTP from the user
      *
-     *
-     * @param id
+     * @param id User id
      */
     @Path("{id}/remove-totp")
     @PUT
@@ -825,13 +856,15 @@ public class UsersResource {
     }
 
     /**
-     * Send an email to the user with a link they can click to reset their password.
+     * Send a password-reset email to the user
+     *
+     * An email contains a link the user can click to reset their password.
      * The redirectUri and clientId parameters are optional. The default for the
      * redirect is the account client.
      *
-     * @param id
-     * @param redirectUri redirect uri
-     * @param clientId client id
+     * @param id User is
+     * @param redirectUri Redirect uri
+     * @param clientId Client id
      * @return
      */
     @Path("{id}/execute-actions-email")
@@ -880,13 +913,15 @@ public class UsersResource {
     }
 
     /**
-     * Send an email to the user with a link they can click to verify their email address.
+     * Send an email-verification email to the user
+     *
+     * An email contains a link the user can click to verify their email address.
      * The redirectUri and clientId parameters are optional. The default for the
      * redirect is the account client.
      *
-     * @param id
-     * @param redirectUri redirect uri
-     * @param clientId client id
+     * @param id User id
+     * @param redirectUri Redirect uri
+     * @param clientId Client id
      * @return
      */
     @Path("{id}/send-verify-email")