[LMS-1615] improved javadoc

SVN: 16995

openbis/source/java/ch/systemsx/cisd/openbis/generic/shared/authorization/annotation/RolesAllowed.java

@@ -26,9 +26,6 @@ import ch.systemsx.cisd.openbis.generic.shared.basic.dto.RoleWithHierarchy;
 
 /**
  * The roles that are allowed to execute an <i>openBIS</i> method.
- * <p>
- * {@link #value()} is additive.
- * </p>
  * 
  * @author Christian Ribeaud
  */
@@ -38,10 +35,8 @@ import ch.systemsx.cisd.openbis.generic.shared.basic.dto.RoleWithHierarchy;
 public @interface RolesAllowed
 {
     /**
-     * The set of roles that are allowed to execute a method.
-     * <p>
-     * Should be the primary choice to specify roles.
-     * </p>
+     * The set of roles that are allowed to execute a method. The method will be accessible by all
+     * users with a role defined in any of {@link RoleWithHierarchy#getRoles()}.
      */
     RoleWithHierarchy[] value() default {};
 

openbis/source/java/ch/systemsx/cisd/openbis/generic/shared/basic/dto/RoleWithHierarchy.java

@@ -26,12 +26,23 @@ import com.google.gwt.user.client.rpc.IsSerializable;
  * {@link RoleWithHierarchy}s that are stronger.
  * <p>
  * Available roles can:
+ * <ol>
  * <li>be presented to the user
  * <li>be easily mapped to database structure
  * <li>be used to restrict access to server methods
  * <li>define the role hierarchy by specifying which roles are stronger (users that have only the
  * "stronger" role will also be able to access given server method)
+ * </ol>
  * </p>
+ * <h4>Example:</h4>To annotate an interface method with a new role e.g. <code>SERCRET_AGENT</code>:
+ * <ol>
+ * <li>Add <code>SECRET_AGENT</code> to {@link RoleCode} enumerator.
+ * <li>Add <code>SECRET_AGENT</code> to <code>authorization_role</code> domain in the database (and
+ * prepare migration).
+ * <li>Add <code>INSTANCE_SECRET_AGENT</code> (or <code>SPACE_SECRET_AGENT</code>) to
+ * {@link RoleWithHierarchy} enumerator and define the "stronger" roles.
+ * <li>Use the new {@link RoleWithHierarchy} to annotate the interface method.
+ * </ol>
  * 
  * @author Izabela Adamczyk
  */