improve rest api documentation of Repository, RepositoryImport, Search, SecuritySystem and User resource

2025-11-12 00:15:44 +01:00 · 2017-05-10 08:56:43 +02:00
parent 42f412faa4
commit 9ff0d1863c
7 changed files with 322 additions and 410 deletions
--- a/scm-webapp/src/main/java/sonia/scm/api/rest/resources/AbstractPermissionResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/rest/resources/AbstractPermissionResource.java
@@ -38,6 +38,10 @@ package sonia.scm.api.rest.resources;
 import com.google.common.base.Function;
 import com.google.common.base.Predicate;
 import com.google.common.collect.Lists;
+import com.webcohesion.enunciate.metadata.rs.ResponseCode;
+import com.webcohesion.enunciate.metadata.rs.ResponseHeader;
+import com.webcohesion.enunciate.metadata.rs.StatusCodes;
+import com.webcohesion.enunciate.metadata.rs.TypeHint;

 import sonia.scm.api.rest.Permission;
 import sonia.scm.security.AssignedPermission;
@@ -114,13 +118,7 @@ public abstract class AbstractPermissionResource
  //~--- methods --------------------------------------------------------------

  /**
-   * Adds a new permission to the user or group managed by the resource.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>201 add successful</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Adds a new permission to the user or group managed by the resource.
   *
   * @param uriInfo uri informations
   * @param permission permission to add
@@ -128,6 +126,13 @@ public abstract class AbstractPermissionResource
   * @return web response
   */
  @POST
+  @StatusCodes({
+    @ResponseCode(code = 201, condition = "creates", additionalHeaders = {
+      @ResponseHeader(name = "Location", description = "uri to new create permission")
+    }),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
  @Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public Response add(@Context UriInfo uriInfo, Permission permission)
  {
@@ -139,15 +144,7 @@ public abstract class AbstractPermissionResource
  }

  /**
-   * Deletes a permission from the user or group managed by the resource.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 delete successful</li>
-   *   <li>400 bad request, permission id does not belong to the user or group</li>
-   *   <li>404 not found, no permission with the specified id available</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Deletes a permission from the user or group managed by the resource.
   *
   * @param id id of the permission
   *
@@ -155,6 +152,13 @@ public abstract class AbstractPermissionResource
   */
  @DELETE
  @Path("{id}")
+  @StatusCodes({
+    @ResponseCode(code = 204, condition = "success"),
+    @ResponseCode(code = 400, condition = "bad request, permission id does not belong to the user or group"),
+    @ResponseCode(code = 404, condition = "not found, no permission with the specified id available"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
  public Response delete(@PathParam("id") String id)
  {
    StoredAssignedPermission sap = getPermission(id);
@@ -165,16 +169,7 @@ public abstract class AbstractPermissionResource
  }

  /**
-   * Updates the specified permission on the user or group managed by the
-   * resource.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>204 update successful</li>
-   *   <li>400 bad request, permission id does not belong to the user or group</li>
-   *   <li>404 not found, no permission with the specified id available</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Updates the specified permission on the user or group managed by the resource.
   *
   * @param id id of the permission
   * @param permission updated permission
@@ -183,6 +178,13 @@ public abstract class AbstractPermissionResource
   */
  @PUT
  @Path("{id}")
+  @StatusCodes({
+    @ResponseCode(code = 204, condition = "success"),
+    @ResponseCode(code = 400, condition = "bad request, permission id does not belong to the user or group"),
+    @ResponseCode(code = 404, condition = "not found, no permission with the specified id available"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
  @Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public Response update(@PathParam("id") String id, Permission permission)
  {
@@ -197,16 +199,7 @@ public abstract class AbstractPermissionResource
  //~--- get methods ----------------------------------------------------------

  /**
-   * Returns the {@link Permission} with the specified id.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>400 bad request, permission id does not belong to the user or group</li>
-   *   <li>404 not found, no permission with the specified id available</li>
-   *   <li>500 internal server error</li>
-   * </ul>
-   *
+   * Returns the {@link Permission} with the specified id.
   *
   * @param id id of the {@link Permission}
   *
@@ -214,6 +207,12 @@ public abstract class AbstractPermissionResource
   */
  @GET
  @Path("{id}")
+  @StatusCodes({
+    @ResponseCode(code = 204, condition = "success"),
+    @ResponseCode(code = 400, condition = "bad request, permission id does not belong to the user or group"),
+    @ResponseCode(code = 404, condition = "not found, no permission with the specified id available"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public Permission get(@PathParam("id") String id)
  {
@@ -223,17 +222,15 @@ public abstract class AbstractPermissionResource
  }

  /**
-   * Returns all permissions of the user or group managed by the resource.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns all permissions of the user or group managed by the resource.
   *
   * @return all permissions of the user or group
   */
  @GET
+  @StatusCodes({
+    @ResponseCode(code = 204, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public List<Permission> getAll()
  {
--- a/scm-webapp/src/main/java/sonia/scm/api/rest/resources/PluginResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/rest/resources/PluginResource.java
@@ -111,6 +111,7 @@ public class PluginResource
   * Installs a plugin from a package.
   *
   * @param uploadedInputStream
+   * 
   * @return
   *
   * @throws IOException
--- a/scm-webapp/src/main/java/sonia/scm/api/rest/resources/RepositoryImportResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/rest/resources/RepositoryImportResource.java
@@ -71,6 +71,9 @@ import static com.google.common.base.Preconditions.*;

 import com.sun.jersey.api.client.ClientResponse.Status;
 import com.sun.jersey.multipart.FormDataParam;
+import com.webcohesion.enunciate.metadata.rs.ResponseCode;
+import com.webcohesion.enunciate.metadata.rs.ResponseHeader;
+import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 import com.webcohesion.enunciate.metadata.rs.TypeHint;

 import java.io.File;
@@ -139,17 +142,8 @@ public class RepositoryImportResource
  /**
   * Imports a repository type specific bundle. The bundle file is uploaded to
   * the server which is running scm-manager. After the upload has finished, the
-   * bundle file is passed to the {@link UnbundleCommandBuilder}. This method
-   * requires admin privileges.<br />
-   *
-   * Status codes:
-   * <ul>
-   *   <li>201 created</li>
-   *   <li>400 bad request, the import bundle feature is not supported by this
-   *       type of repositories or the parameters are not valid.</li>
-   *   <li>500 internal server error</li>
-   *   <li>409 conflict, a repository with the name already exists.</li>
-   * </ul>
+   * bundle file is passed to the {@link UnbundleCommandBuilder}. <strong>Note:</strong> This method
+   * requires admin privileges.
   *
   * @param uriInfo uri info
   * @param type repository type
@@ -157,12 +151,23 @@ public class RepositoryImportResource
   * @param inputStream input bundle
   * @param compressed true if the bundle is gzip compressed
   *
-   * @return empty response with location header which points to the imported
-   *  repository
+   * @return empty response with location header which points to the imported repository
   * @since 1.43
   */
  @POST
  @Path("{type}/bundle")
+  @StatusCodes({
+    @ResponseCode(code = 201, condition = "created", additionalHeaders = {
+      @ResponseHeader(name = "Location", description = "uri to the imported repository")
+    }),
+    @ResponseCode(
+      code = 400, 
+      condition = "bad request, the import bundle feature is not supported by this type of repositories or the parameters are not valid"
+    ),
+    @ResponseCode(code = 409, condition = "conflict, a repository with the name already exists"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
  @Consumes(MediaType.MULTIPART_FORM_DATA)
  public Response importFromBundle(@Context UriInfo uriInfo,
    @PathParam("type") String type, @FormDataParam("name") String name,
@@ -179,18 +184,8 @@ public class RepositoryImportResource
   * This method works exactly like
   * {@link #importFromBundle(UriInfo, String, String, InputStream)}, but this
   * method returns an html content-type. The method exists only for a
-   * workaround of the javascript ui extjs. This method requires admin
-   * privileges.<br />
-   *
-   * Status codes:
-   * <ul>
-   *   <li>201 created</li>
-   *   <li>400 bad request, the import bundle feature is not supported by this
-   *       type of repositories or the parameters are not valid.</li>
-   *   <li>500 internal server error</li>
-   *   <li>409 conflict, a repository with the name already exists.</li>
-   * </ul>
-   *
+   * workaround of the javascript ui extjs. <strong>Note:</strong> This method requires admin
+   * privileges.
   *
   * @param type repository type
   * @param name name of the repository
@@ -203,6 +198,16 @@ public class RepositoryImportResource
   */
  @POST
  @Path("{type}/bundle.html")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(
+      code = 400, 
+      condition = "bad request, the import bundle feature is not supported by this type of repositories or the parameters are not valid"
+    ),
+    @ResponseCode(code = 409, condition = "conflict, a repository with the name already exists"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(RestActionUploadResult.class)
  @Consumes(MediaType.MULTIPART_FORM_DATA)
  @Produces(MediaType.TEXT_HTML)
  public Response importFromBundleUI(@PathParam("type") String type,
@@ -231,16 +236,7 @@ public class RepositoryImportResource
   * Imports a external repository which is accessible via url. The method can
   * only be used, if the repository type supports the {@link Command#PULL}. The
   * method will return a location header with the url to the imported
-   * repository. This method requires admin privileges.<br />
-   *
-   * Status codes:
-   * <ul>
-   *   <li>201 created</li>
-   *   <li>400 bad request, the import by url feature is not supported by this
-   *       type of repositories or the parameters are not valid.</li>
-   *   <li>409 conflict, a repository with the name already exists.</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * repository. <strong>Note:</strong> This method requires admin privileges.
   *
   * @param uriInfo uri info
   * @param type repository type
@@ -252,6 +248,18 @@ public class RepositoryImportResource
   */
  @POST
  @Path("{type}/url")
+  @StatusCodes({
+    @ResponseCode(code = 201, condition = "created", additionalHeaders = {
+      @ResponseHeader(name = "Location", description = "uri to the imported repository")
+    }),
+    @ResponseCode(
+      code = 400, 
+      condition = "bad request, the import feature is not supported by this type of repositories or the parameters are not valid"
+    ),
+    @ResponseCode(code = 409, condition = "conflict, a repository with the name already exists"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
  @Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public Response importFromUrl(@Context UriInfo uriInfo,
    @PathParam("type") String type, UrlImportRequest request)
@@ -295,15 +303,7 @@ public class RepositoryImportResource

  /**
   * Imports repositories of the given type from the configured repository
-   * directory. This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 ok, successful</li>
-   *   <li>400 bad request, the import feature is not
-   *       supported by this type of repositories.</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * directory. <strong>Note:</strong> This method requires admin privileges.
   *
   * @param type repository type
   *
@@ -311,6 +311,14 @@ public class RepositoryImportResource
   */
  @POST
  @Path("{type}")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(
+      code = 400, 
+      condition = "bad request, the import feature is not supported by this type of repositories"
+    ),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @TypeHint(Repository[].class)
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public Response importRepositories(@PathParam("type") String type)
@@ -330,19 +338,19 @@ public class RepositoryImportResource

  /**
   * Imports repositories of all supported types from the configured repository
-   * directories. This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 ok, successful</li>
-   *   <li>400 bad request, the import feature is not
-   *       supported by this type of repositories.</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * directories. <strong>Note:</strong> This method requires admin privileges.
   *
   * @return imported repositories
   */
  @POST
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(
+      code = 400, 
+      condition = "bad request, the import feature is not supported by this type of repositories"
+    ),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @TypeHint(Repository[].class)
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public Response importRepositories()
@@ -368,15 +376,7 @@ public class RepositoryImportResource
  /**
   * Imports repositories of the given type from the configured repository
   * directory. Returns a list of successfully imported directories and a list
-   * of failed directories. This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 ok, successful</li>
-   *   <li>400 bad request, the import feature is not
-   *       supported by this type of repositories.</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * of failed directories. <strong>Note:</strong> This method requires admin privileges.
   *
   * @param type repository type
   *
@@ -385,6 +385,14 @@ public class RepositoryImportResource
   */
  @POST
  @Path("{type}/directory")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(
+      code = 400, 
+      condition = "bad request, the import feature is not supported by this type of repositories"
+    ),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @TypeHint(ImportResult.class)
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public Response importRepositoriesFromDirectory(
@@ -453,22 +461,20 @@ public class RepositoryImportResource

  /**
   * Returns a list of repository types, which support the directory import
-   * feature.
-   *
-   * This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 ok, successful</li>
-   *   <li>400 bad request, the import feature is not
-   *       supported by this type of repositories.</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * feature. <strong>Note:</strong> This method requires admin privileges.
   *
   * @return list of repository types
   */
  @GET
  @TypeHint(Type[].class)
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(
+      code = 400, 
+      condition = "bad request, the import feature is not supported by this type of repositories"
+    ),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public Response getImportableTypes()
  {
--- a/scm-webapp/src/main/java/sonia/scm/api/rest/resources/RepositoryResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/rest/resources/RepositoryResource.java
@@ -39,6 +39,9 @@ import com.google.common.base.Strings;
 import com.google.common.io.Closeables;
 import com.google.inject.Inject;
 import com.google.inject.Singleton;
+import com.webcohesion.enunciate.metadata.rs.ResponseCode;
+import com.webcohesion.enunciate.metadata.rs.ResponseHeader;
+import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 import com.webcohesion.enunciate.metadata.rs.TypeHint;

 import org.apache.shiro.SecurityUtils;
@@ -104,13 +107,13 @@ import javax.ws.rs.core.StreamingOutput;
 import javax.ws.rs.core.UriInfo;

 /**
- *
+ * Repository related RESTful Web Service Endpoint.
+ * 
 * @author Sebastian Sdorra
 */
@Singleton
@Path("repositories")
-public class RepositoryResource
-  extends AbstractManagerResource<Repository, RepositoryException>
+public class RepositoryResource extends AbstractManagerResource<Repository, RepositoryException>
 {

  /** Field description */
@@ -147,22 +150,22 @@ public class RepositoryResource
  //~--- methods --------------------------------------------------------------

  /**
-   * Creates a new repository.<br />
-   * This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>201 create success</li>
-   *   <li>403 forbidden, the current user has no admin privileges</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Creates a new repository.<strong>Note:</strong> This method requires admin privileges.
   *
   * @param uriInfo current uri informations
   * @param repository the repository to be created
   *
-   * @return
+   * @return empty response with location header to the new repository
   */
  @POST
+  @StatusCodes({
+    @ResponseCode(code = 201, condition = "success", additionalHeaders = {
+      @ResponseHeader(name = "Location", description = "uri to the new created repository")
+    }),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no admin privileges"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
  @Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  @Override
  public Response create(@Context UriInfo uriInfo, Repository repository)
@@ -171,19 +174,7 @@ public class RepositoryResource
  }

  /**
-   * Deletes a repository.<br />
-   * This method requires owner privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *  <li>201 delete success</li>
-   *  <li>403 forbidden, the current user has no owner privileges</li>
-   *  <li>
-   *    412 forbidden, the repository is not archived,
-   *    this error occurs only with enabled repository archive.
-   *  </li>
-   *  <li>500 internal server error</li>
-   * </ul>
+   * Deletes a repository. <strong>Note:</strong> This method requires owner privileges.
   *
   * @param id the id of the repository to delete.
   *
@@ -191,6 +182,17 @@ public class RepositoryResource
   */
  @DELETE
  @Path("{id}")
+  @StatusCodes({
+    @ResponseCode(code = 204, condition = "delete success"),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no owner privileges"),
+    @ResponseCode(code = 404, condition = "could not find repository"),
+    @ResponseCode(
+      code = 412, 
+      condition = "precondition failed, the repository is not archived, this error occurs only with enabled repository archive"
+    ),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
  @Override
  public Response delete(@PathParam("id") String id)
  {
@@ -232,20 +234,20 @@ public class RepositoryResource
  }

  /**
-   * Re run repository health checks.<br />
-   * Status codes:
-   * <ul>
-   *  <li>201 re run success</li>
-   *  <li>403 forbidden, the current user has no owner privileges</li>
-   *  <li>404 could not find repository</li>
-   *  <li>500 internal server error</li>
-   * </ul>
+   * Re run repository health checks.
   *
   * @param id id of the repository
   *
   * @return
   */
  @POST
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "re run success"),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no owner privileges"),
+    @ResponseCode(code = 404, condition = "could not find repository"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
  @Path("{id}/healthcheck")
  public Response runHealthChecks(@PathParam("id") String id)
  {
@@ -254,6 +256,7 @@ public class RepositoryResource
    try
    {
      healthChecker.check(id);
+      // TODO should return 204 instead of 200
      response = Response.ok().build();
    }
    catch (RepositoryNotFoundException ex)
@@ -276,15 +279,7 @@ public class RepositoryResource
  }

  /**
-   * Modifies the given repository.<br />
-   * This method requires owner privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>201 update successful</li>
-   *   <li>403 forbidden, the current user has no owner privileges</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Modifies the given repository. <strong>Note:</strong> This method requires owner privileges.
   *
   * @param uriInfo current uri informations
   * @param id id of the repository to be modified
@@ -294,10 +289,16 @@ public class RepositoryResource
   */
  @PUT
  @Path("{id}")
+  @StatusCodes({
+    @ResponseCode(code = 204, condition = "update successful"),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no owner privileges"),
+    @ResponseCode(code = 404, condition = "could not find repository"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
  @Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  @Override
-  public Response update(@Context UriInfo uriInfo, @PathParam("id") String id,
-    Repository repository)
+  public Response update(@Context UriInfo uriInfo, @PathParam("id") String id, Repository repository)
  {
    return super.update(uriInfo, id, repository);
  }
@@ -305,14 +306,7 @@ public class RepositoryResource
  //~--- get methods ----------------------------------------------------------

  /**
-   * Returns the {@link Repository} with the specified id.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>404 not found, no repository with the specified id available</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns the {@link Repository} with the specified id.
   *
   * @param request the current request
   * @param id the id/name of the user
@@ -322,6 +316,11 @@ public class RepositoryResource
  @GET
  @Path("{id}")
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 404, condition = "not found, no repository with the specified id available"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @TypeHint(Repository.class)
  @Override
  public Response get(@Context Request request, @PathParam("id") String id)
@@ -330,13 +329,7 @@ public class RepositoryResource
  }

  /**
-   * Returns all repositories.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns all repositories.
   *
   * @param request the current request
   * @param start the start value for paging
@@ -348,6 +341,10 @@ public class RepositoryResource
   */
  @GET
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @TypeHint(Repository[].class)
  @Override
  public Response getAll(@Context Request request, @DefaultValue("0")
@@ -360,16 +357,7 @@ public class RepositoryResource
  }

  /**
-   * Returns a annotate/blame view for the given path.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>400 bad request, the blame feature is not
-   *       supported by this type of repositories.</li>
-   *   <li>404 not found, if the repository or the path could not be found</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns a annotate/blame view for the given path.
   *
   * @param id the id of the repository
   * @param revision the revision of the file
@@ -382,6 +370,12 @@ public class RepositoryResource
   */
  @GET
  @Path("{id}/blame")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 400, condition = "bad request, the blame feature is not supported by this type of repositories."),
+    @ResponseCode(code = 404, condition = "not found, the repository or the path could not be found"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @TypeHint(BlameResult.class)
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public Response getBlame(@PathParam("id") String id,
@@ -435,16 +429,7 @@ public class RepositoryResource
  }

  /**
-   * Returns all {@link Branches} of a repository.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>400 bad request, the content feature is not
-   *       supported by this type of repositories.</li>
-   *   <li>404 not found, if the repository or the path could not be found</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns all {@link Branches} of a repository.
   *
   * @param id the id of the repository
   *
@@ -457,6 +442,14 @@ public class RepositoryResource
   */
  @GET
  @Path("{id}/branches")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 400, condition = "bad request, the branch feature is not supported by this type of repositories."),
+    @ResponseCode(code = 404, condition = "not found, the repository could not be found"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(Branches.class)
+  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public Response getBranches(@PathParam("id") String id)
    throws RepositoryException, IOException
  {
@@ -495,16 +488,7 @@ public class RepositoryResource
  }

  /**
-   * Returns a list of folders and files for the given folder.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>400 bad request, the browse feature is not
-   *       supported by this type of repositories.</li>
-   *   <li>404 not found, if the repository or the path could not be found</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns a list of folders and files for the given folder.
   *
   * @param id the id of the repository
   * @param revision the revision of the file
@@ -520,6 +504,12 @@ public class RepositoryResource
   */
  @GET
  @Path("{id}/browse")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 400, condition = "bad request, the browse feature is not supported by this type of repositories."),
+    @ResponseCode(code = 404, condition = "not found, the repository or the path could not be found"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @TypeHint(BrowserResult.class)
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  //J-
@@ -586,15 +576,7 @@ public class RepositoryResource
  }

  /**
-   * Returns the {@link Repository} with the specified type and name.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>404 not found,
-   *       no repository with the specified type and name available</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns the {@link Repository} with the specified type and name.
   *
   * @param type the type of the repository
   * @param name the name of the repository
@@ -603,8 +585,13 @@ public class RepositoryResource
   */
  @GET
  @Path("{type: [a-z]+}/{name: .*}")
-  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 404, condition = "not found, no repository with the specified type and name available"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @TypeHint(Repository.class)
+  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public Response getByTypeAndName(@PathParam("type") String type,
    @PathParam("name") String name)
  {
@@ -626,17 +613,7 @@ public class RepositoryResource

  /**
   * Returns the {@link Changeset} from the given repository
-   * with the specified revision.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>400 bad request, the changeset feature is not
-   *       supported by this type of repositories.</li>
-   *   <li>404 not found, if the repository or
-   *       the revision could not be found</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * with the specified revision.
   *
   * @param id the id of the repository
   * @param revision the revision of the changeset
@@ -648,6 +625,14 @@ public class RepositoryResource
   */
  @GET
  @Path("{id}/changeset/{revision}")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 400, condition = "bad request, the changeset feature is not supported by this type of repositories."),
+    @ResponseCode(code = 404, condition = "not found, the repository or the revision could not be found"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(Changeset.class)
+  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public Response getChangeset(@PathParam("id") String id,
    @PathParam("revision") String revision)
    throws IOException, RepositoryException
@@ -700,16 +685,7 @@ public class RepositoryResource
  }

  /**
-   * Returns a list of {@link Changeset} for the given repository.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>400 bad request, the changeset feature is not
-   *       supported by this type of repositories.</li>
-   *   <li>404 not found, if the repository or the path could not be found</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns a list of {@link Changeset} for the given repository.
   *
   * @param id the id of the repository
   * @param path path of a file
@@ -725,6 +701,12 @@ public class RepositoryResource
   */
  @GET
  @Path("{id}/changesets")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 400, condition = "bad request, the changeset feature is not supported by this type of repositories."),
+    @ResponseCode(code = 404, condition = "not found, the repository or the path could not be found"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @TypeHint(ChangesetPagingResult.class)
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  //J-
@@ -793,16 +775,7 @@ public class RepositoryResource
  }

  /**
-   * Returns the content of a file.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>400 bad request, the content feature is not
-   *       supported by this type of repositories.</li>
-   *   <li>404 not found, if the repository or the path could not be found</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns the content of a file.
   *
   * @param id the id of the repository
   * @param revision the revision of the file
@@ -812,14 +785,20 @@ public class RepositoryResource
   */
  @GET
  @Path("{id}/content")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 400, condition = "bad request, the content feature is not supported by this type of repositories."),
+    @ResponseCode(code = 404, condition = "not found, the repository or the path could not be found"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @TypeHint(StreamingOutput.class)
  @Produces({ MediaType.APPLICATION_OCTET_STREAM })
  public Response getContent(@PathParam("id") String id,
    @QueryParam("revision") String revision, @QueryParam("path") String path)
  {
-    Response response = null;
-    StreamingOutput output = null;
-    RepositoryService service = null;
+    Response response;
+    StreamingOutput output;
+    RepositoryService service;

    try
    {
@@ -864,16 +843,7 @@ public class RepositoryResource
  }

  /**
-   * Returns the modifications of a {@link Changeset}.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>400 bad request, the content feature is not
-   *       supported by this type of repositories.</li>
-   *   <li>404 not found, if the repository or the path could not be found</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns the modifications of a {@link Changeset}.
   *
   * @param id the id of the repository
   * @param revision the revision of the file
@@ -887,6 +857,12 @@ public class RepositoryResource
   */
  @GET
  @Path("{id}/diff")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 400, condition = "bad request, the diff feature is not supported by this type of repositories."),
+    @ResponseCode(code = 404, condition = "not found, the repository or the path could not be found"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @TypeHint(DiffStreamingOutput.class)
  @Produces(MediaType.APPLICATION_OCTET_STREAM)
  public Response getDiff(@PathParam("id") String id,
@@ -903,8 +879,8 @@ public class RepositoryResource
     */
    HttpUtil.checkForCRLFInjection(revision);

-    RepositoryService service = null;
-    Response response = null;
+    RepositoryService service;
+    Response response;

    try
    {
@@ -952,16 +928,7 @@ public class RepositoryResource
  }

  /**
-   * Returns all {@link Tags} of a repository.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>400 bad request, the content feature is not
-   *       supported by this type of repositories.</li>
-   *   <li>404 not found, if the repository or the path could not be found</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns all {@link Tags} of a repository.
   *
   * @param id the id of the repository
   *
@@ -974,6 +941,14 @@ public class RepositoryResource
   */
  @GET
  @Path("{id}/tags")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 400, condition = "bad request, the tag feature is not supported by this type of repositories."),
+    @ResponseCode(code = 404, condition = "not found, the repository could not be found"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(Tags.class)
+  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public Response getTags(@PathParam("id") String id)
    throws RepositoryException, IOException
  {
--- a/scm-webapp/src/main/java/sonia/scm/api/rest/resources/SearchResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/rest/resources/SearchResource.java
@@ -38,6 +38,8 @@ package sonia.scm.api.rest.resources;
 import com.google.common.base.Function;
 import com.google.inject.Inject;
 import com.google.inject.Singleton;
+import com.webcohesion.enunciate.metadata.rs.ResponseCode;
+import com.webcohesion.enunciate.metadata.rs.StatusCodes;

 import sonia.scm.HandlerEvent;
 import sonia.scm.cache.Cache;
@@ -61,7 +63,9 @@ import javax.ws.rs.QueryParam;
 import javax.ws.rs.core.MediaType;

 /**
- *
+ * RESTful Web Service Resource to search users and groups. This endpoint can be used to implement typeahead input 
+ * fields for permissions.
+ * 
 * @author Sebastian Sdorra
 */
@Singleton
@@ -138,12 +142,7 @@ public class SearchResource implements UserListener, GroupListener
  }

  /**
-   * Returns a list of groups found by the given search string.<br />
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns a list of groups found by the given search string.
   *
   * @param queryString the search string
   *
@@ -151,6 +150,10 @@ public class SearchResource implements UserListener, GroupListener
   */
  @GET
  @Path("groups")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public SearchResults searchGroups(@QueryParam("query") String queryString)
  {
@@ -174,12 +177,7 @@ public class SearchResource implements UserListener, GroupListener
  }

  /**
-   * Returns a list of users found by the given search string.<br />
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns a list of users found by the given search string.
   *
   * @param queryString the search string
   *
@@ -187,6 +185,10 @@ public class SearchResource implements UserListener, GroupListener
   */
  @GET
  @Path("users")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  public SearchResults searchUsers(@QueryParam("query") String queryString)
  {
@@ -208,8 +210,8 @@ public class SearchResource implements UserListener, GroupListener
  //~--- fields ---------------------------------------------------------------

  /** Field description */
-  private SearchHandler<Group> groupSearchHandler;
+  private final SearchHandler<Group> groupSearchHandler;

  /** Field description */
-  private SearchHandler<User> userSearchHandler;
+  private final SearchHandler<User> userSearchHandler;
 }
--- a/scm-webapp/src/main/java/sonia/scm/api/rest/resources/SecuritySystemResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/rest/resources/SecuritySystemResource.java
@@ -47,7 +47,8 @@ import javax.ws.rs.Path;
 import javax.ws.rs.PathParam;

 /**
- *
+ * Resource for managing system security permissions.
+ * 
 * @author Sebastian Sdorra
 */
@Path("security/permission")
@@ -72,31 +73,28 @@ public class SecuritySystemResource
  //~--- get methods ----------------------------------------------------------

  /**
-   * Method description
+   * Returns group permission sub resource.
   *
+   * @param group name of group
   *
-   * @param group
-   *
-   * @return
+   * @return sub resource
   */
  @Path("group/{group}")
-  public GroupPermissionResource getGroupSubResource(
-    @PathParam("group") String group)
+  public GroupPermissionResource getGroupSubResource(@PathParam("group") String group)
  {
    return new GroupPermissionResource(system, group);
  }

  /**
-   * Method description
+   * Returns user permission sub resource.
   *
   *
-   * @param user
+   * @param user name of user
   *
-   * @return
+   * @return sub resource
   */
  @Path("user/{user}")
-  public UserPermissionResource getUserSubResource(
-    @PathParam("user") String user)
+  public UserPermissionResource getUserSubResource(@PathParam("user") String user)
  {
    return new UserPermissionResource(system, user);
  }
@@ -104,5 +102,5 @@ public class SecuritySystemResource
  //~--- fields ---------------------------------------------------------------

  /** Field description */
-  private SecuritySystem system;
+  private final SecuritySystem system;
 }
--- a/scm-webapp/src/main/java/sonia/scm/api/rest/resources/UserResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/rest/resources/UserResource.java
@@ -37,6 +37,9 @@ package sonia.scm.api.rest.resources;

 import com.google.inject.Inject;
 import com.google.inject.Singleton;
+import com.webcohesion.enunciate.metadata.rs.ResponseCode;
+import com.webcohesion.enunciate.metadata.rs.ResponseHeader;
+import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 import com.webcohesion.enunciate.metadata.rs.TypeHint;

 import org.apache.shiro.SecurityUtils;
@@ -71,7 +74,8 @@ import javax.ws.rs.core.Response;
 import javax.ws.rs.core.UriInfo;

 /**
- *
+ * RESTful Web Service Resource to manage users.
+ * 
 * @author Sebastian Sdorra
 */
@Singleton
@@ -96,8 +100,7 @@ public class UserResource extends AbstractManagerResource<User, UserException>
   * @param securityContextProvider
   */
  @Inject
-  public UserResource(UserManager userManager,
-    EncryptionHandler encryptionHandler)
+  public UserResource(UserManager userManager, EncryptionHandler encryptionHandler)
  {
    super(userManager);
    this.encryptionHandler = encryptionHandler;
@@ -106,15 +109,7 @@ public class UserResource extends AbstractManagerResource<User, UserException>
  //~--- methods --------------------------------------------------------------

  /**
-   * Creates a new user.<br />
-   * This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>201 create success</li>
-   *   <li>403 forbidden, the current user has no admin privileges</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Creates a new user. <strong>Note:</strong> This method requires admin privileges.
   *
   * @param uriInfo current uri informations
   * @param user the user to be created
@@ -122,6 +117,14 @@ public class UserResource extends AbstractManagerResource<User, UserException>
   * @return
   */
  @POST
+  @StatusCodes({
+    @ResponseCode(code = 201, condition = "create success", additionalHeaders = {
+      @ResponseHeader(name = "Location", description = "uri to the created group")
+    }),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no admin privileges"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
  @Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  @Override
  public Response create(@Context UriInfo uriInfo, User user)
@@ -130,15 +133,7 @@ public class UserResource extends AbstractManagerResource<User, UserException>
  }

  /**
-   * Deletes a user.<br />
-   * This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *  <li>201 delete success</li>
-   *  <li>403 forbidden, the current user has no admin privileges</li>
-   *  <li>500 internal server error</li>
-   * </ul>
+   * Deletes a user. <strong>Note:</strong> This method requires admin privileges.
   *
   * @param name the name of the user to delete.
   *
@@ -146,6 +141,12 @@ public class UserResource extends AbstractManagerResource<User, UserException>
   */
  @DELETE
  @Path("{id}")
+  @StatusCodes({
+    @ResponseCode(code = 204, condition = "delete success"),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no admin privileges"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
  @Override
  public Response delete(@PathParam("id") String name)
  {
@@ -153,15 +154,7 @@ public class UserResource extends AbstractManagerResource<User, UserException>
  }

  /**
-   * Modifies the given user.<br />
-   * This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>201 update successful</li>
-   *   <li>403 forbidden, the current user has no admin privileges</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Modifies the given user. <strong>Note:</strong> This method requires admin privileges.
   *
   * @param uriInfo current uri informations
   * @param name name of the user to be modified
@@ -171,6 +164,12 @@ public class UserResource extends AbstractManagerResource<User, UserException>
   */
  @PUT
  @Path("{id}")
+  @StatusCodes({
+    @ResponseCode(code = 204, condition = "update success"),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no admin privileges"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
  @Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  @Override
  public Response update(@Context UriInfo uriInfo,
@@ -182,16 +181,7 @@ public class UserResource extends AbstractManagerResource<User, UserException>
  //~--- get methods ----------------------------------------------------------

  /**
-   * Returns a user.<br />
-   * This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>403 forbidden, the current user has no admin privileges</li>
-   *   <li>404 not found, no user with the specified id/name available</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns a user. <strong>Note:</strong> This method requires admin privileges.
   *
   * @param request the current request
   * @param id the id/name of the user
@@ -201,6 +191,12 @@ public class UserResource extends AbstractManagerResource<User, UserException>
  @GET
  @Path("{id}")
  @TypeHint(User.class)
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no admin privileges"),
+    @ResponseCode(code = 404, condition = "not found, no group with the specified id/name available"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  @Override
  public Response get(@Context Request request, @PathParam("id") String id)
@@ -220,15 +216,7 @@ public class UserResource extends AbstractManagerResource<User, UserException>
  }

  /**
-   * Returns all users.<br />
-   * This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>403 forbidden, the current user has no admin privileges</li>
-   *   <li>500 internal server error</li>
-   * </ul>
+   * Returns all users. <strong>Note:</strong> This method requires admin privileges.
   *
   * @param request the current request
   * @param start the start value for paging
@@ -240,6 +228,11 @@ public class UserResource extends AbstractManagerResource<User, UserException>
   */
  @GET
  @TypeHint(User[].class)
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no admin privileges"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
  @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
  @Override
  public Response getAll(@Context Request request, @DefaultValue("0")
@@ -253,14 +246,6 @@ public class UserResource extends AbstractManagerResource<User, UserException>

  //~--- methods --------------------------------------------------------------

-  /**
-   * Method description
-   *
-   *
-   * @param items
-   *
-   * @return
-   */
  @Override
  protected GenericEntity<Collection<User>> createGenericEntity(
    Collection<User> items)
@@ -269,24 +254,12 @@ public class UserResource extends AbstractManagerResource<User, UserException>
    ;
  }

-  /**
-   * Method description
-   *
-   *
-   * @param user
-   */
  @Override
  protected void preCreate(User user)
  {
    encryptPassword(user);
  }
-
-  /**
-   * Method description
-   *
-   *
-   * @param user
-   */
+  
  @Override
  protected void preUpate(User user)
  {
@@ -303,14 +276,6 @@ public class UserResource extends AbstractManagerResource<User, UserException>
    }
  }

-  /**
-   * Method description
-   *
-   *
-   * @param users
-   *
-   * @return
-   */
  @Override
  protected Collection<User> prepareForReturn(Collection<User> users)
  {
@@ -325,14 +290,6 @@ public class UserResource extends AbstractManagerResource<User, UserException>
    return users;
  }

-  /**
-   * Method description
-   *
-   *
-   * @param user
-   *
-   * @return
-   */
  @Override
  protected User prepareForReturn(User user)
  {
@@ -341,42 +298,18 @@ public class UserResource extends AbstractManagerResource<User, UserException>
    return user;
  }

-  //~--- get methods ----------------------------------------------------------
-
-  /**
-   * Method description
-   *
-   *
-   * @param user
-   *
-   * @return
-   */
  @Override
  protected String getId(User user)
  {
    return user.getName();
  }

-  /**
-   * Method description
-   *
-   *
-   * @return
-   */
  @Override
  protected String getPathPart()
  {
    return PATH_PART;
  }

-  //~--- methods --------------------------------------------------------------
-
-  /**
-   * Method description
-   *
-   *
-   * @param user
-   */
  private void encryptPassword(User user)
  {
    String password = user.getPassword();