TSK-1532: Refactor names of entities in REST-Doc by capitalizing them; refactor Java-doc according to guidelines

lib/taskana-core/src/main/java/pro/taskana/classification/api/ClassificationQuery.java

@@ -1,5 +1,6 @@
 package pro.taskana.classification.api;
 
+import pro.taskana.classification.api.models.Classification;
 import pro.taskana.classification.api.models.ClassificationSummary;
 import pro.taskana.common.api.BaseQuery;
 import pro.taskana.common.api.TimeInterval;
@@ -10,7 +11,7 @@ public interface ClassificationQuery
     extends BaseQuery<ClassificationSummary, ClassificationQueryColumnName> {
 
   /**
-   * Add your key to your query.
+   * Add one or multiple {@linkplain ClassificationSummary#getKey() keys} to your query.
    *
    * @param key as String
    * @return the query
@@ -18,7 +19,7 @@ public interface ClassificationQuery
   ClassificationQuery keyIn(String... key);
 
   /**
-   * Add your Id to your query.
+   * Add one or multiple {@linkplain ClassificationSummary#getId() ids} to your query.
    *
    * @param id as String
    * @return the query
@@ -26,7 +27,7 @@ public interface ClassificationQuery
   ClassificationQuery idIn(String... id);
 
   /**
-   * Add your parentIds to your query.
+   * Add one or multiple {@linkplain ClassificationSummary#getParentId() parentIds} to your query.
    *
    * @param parentId as an array of Strings
    * @return the query
@@ -34,7 +35,7 @@ public interface ClassificationQuery
   ClassificationQuery parentIdIn(String... parentId);
 
   /**
-   * Add your parentKeys to your query.
+   * Add your {@linkplain ClassificationSummary#getParentKey() parentKeys} to your query.
    *
    * @param parentKey as an array of Strings
    * @return the query
@@ -42,7 +43,7 @@ public interface ClassificationQuery
   ClassificationQuery parentKeyIn(String... parentKey);
 
   /**
-   * Add your category to your query.
+   * Add your {@linkplain ClassificationSummary#getCategory() categories} to your query.
    *
    * @param category as String
    * @return the query
@@ -50,7 +51,7 @@ public interface ClassificationQuery
   ClassificationQuery categoryIn(String... category);
 
   /**
-   * Add your type to your query.
+   * Add your {@linkplain ClassificationSummary#getType() types} to your query.
    *
    * @param type as String
    * @return the query
@@ -58,7 +59,8 @@ public interface ClassificationQuery
   ClassificationQuery typeIn(String... type);
 
   /**
-   * Add your domains to your query which are used as filter.
+   * Add your {@linkplain ClassificationSummary#getDomain() domains} to your query which are used as
+   * filter.
    *
    * @param domain or domains for filtering.
    * @return the query
@@ -66,7 +68,8 @@ public interface ClassificationQuery
   ClassificationQuery domainIn(String... domain);
 
   /**
-   * Add to your query if the Classification shall be valid in its domain.
+   * Add to your query if the {@linkplain pro.taskana.classification.api.models.Classification
+   * Classification} shall be valid in its {@linkplain ClassificationSummary#getDomain() domain}.
    *
    * @param validInDomain a simple flag showing if domain is valid
    * @return the query
@@ -74,25 +77,25 @@ public interface ClassificationQuery
   ClassificationQuery validInDomainEquals(Boolean validInDomain);
 
   /**
-   * Add your created-Dates to your query.
+   * Add your {@linkplain Classification#getCreated() created}-Dates to your query.
    *
-   * @param createdIn the {@link TimeInterval} within which the searched-for classifications were
+   * @param createdIn the {@linkplain TimeInterval} within which the searched-for classifications
-   *     created.
+   *     were created.
    * @return the query
    */
   ClassificationQuery createdWithin(TimeInterval... createdIn);
 
   /**
-   * Add your modified-Dates to your query.
+   * Add your {@linkplain Classification#getModified() modified}-Dates to your query.
    *
-   * @param modifiedIn the {@link TimeInterval} within which the searched-for classifications were
+   * @param modifiedIn the {@linkplain TimeInterval} within which the searched-for classifications
-   *     modified the last time.
+   *     were modified the last time.
    * @return the query
    */
   ClassificationQuery modifiedWithin(TimeInterval... modifiedIn);
 
   /**
-   * Add your name to your query.
+   * Add your {@linkplain ClassificationSummary#getName() names} to your query.
    *
    * @param nameIn as String
    * @return the query
@@ -100,7 +103,8 @@ public interface ClassificationQuery
   ClassificationQuery nameIn(String... nameIn);
 
   /**
-   * Add your name to your query. It will be compared in SQL with an LIKE.
+   * Add your {@linkplain ClassificationSummary#getName() names} to your query. They will be
+   * compared in SQL with a LIKE.
    *
    * @param nameLike as String
    * @return the query
@@ -108,8 +112,9 @@ public interface ClassificationQuery
   ClassificationQuery nameLike(String... nameLike);
 
   /**
-   * Add your description to your query. It will be compared in SQL with an LIKE. If you use a
+   * Add your {@linkplain Classification#getDescription() descriptions} to your query. They will be
-   * wildcard like % then it will be transmitted to the database.
+   * compared in SQL with a LIKE. If you use a wildcard like % then it will be transmitted to the
+   * database.
    *
    * @param descriptionLike your description
    * @return the query
@@ -117,7 +122,7 @@ public interface ClassificationQuery
   ClassificationQuery descriptionLike(String descriptionLike);
 
   /**
-   * Add your priority to your query.
+   * Add your {@linkplain ClassificationSummary#getPriority() priorities} to your query.
    *
    * @param priorities as integers
    * @return the query
@@ -125,7 +130,7 @@ public interface ClassificationQuery
   ClassificationQuery priorityIn(int... priorities);
 
   /**
-   * Add your serviceLevel to your query.
+   * Add your {@linkplain ClassificationSummary#getServiceLevel() serviceLevels} to your query.
    *
    * @param serviceLevelIn as String
    * @return the query
@@ -133,7 +138,8 @@ public interface ClassificationQuery
   ClassificationQuery serviceLevelIn(String... serviceLevelIn);
 
   /**
-   * Add your serviceLevel to your query. It will be compared in SQL with an LIKE.
+   * Add your {@linkplain ClassificationSummary#getServiceLevel() serviceLevels} to your query. They
+   * will be compared in SQL with a LIKE.
    *
    * @param serviceLevelLike as String
    * @return the query
@@ -141,7 +147,8 @@ public interface ClassificationQuery
   ClassificationQuery serviceLevelLike(String... serviceLevelLike);
 
   /**
-   * Add your applicationEntryPoint to your query.
+   * Add your {@linkplain ClassificationSummary#getApplicationEntryPoint() applicationEntryPoints}
+   * to your query.
    *
    * @param applicationEntryPointIn name of the applications entrypoint
    * @return the query
@@ -149,7 +156,8 @@ public interface ClassificationQuery
   ClassificationQuery applicationEntryPointIn(String... applicationEntryPointIn);
 
   /**
-   * Add your applicationEntryPoint to your query. It will be compared in SQL with an LIKE.
+   * Add your {@linkplain ClassificationSummary#getApplicationEntryPoint() applicationEntryPoints}
+   * to your query. They will be compared in SQL with a LIKE.
    *
    * @param applicationEntryPointLike name of the applications entrypoint
    * @return the query
@@ -157,9 +165,10 @@ public interface ClassificationQuery
   ClassificationQuery applicationEntryPointLike(String... applicationEntryPointLike);
 
   /**
-   * Add the values of custom attributes for exact matching to your query.
+   * Add the values of specified {@linkplain ClassificationCustomField ClassificationCustomFields}
+   * for exact matching to your query.
    *
-   * @param customField identifies which custom attribute is affected.
+   * @param customField identifies which custom attribute is affected
    * @param searchArguments the customField values of the searched for tasks
    * @return the query
    * @throws InvalidArgumentException if searchArguments is empty or null
@@ -169,9 +178,10 @@ public interface ClassificationQuery
       throws InvalidArgumentException;
 
   /**
-   * Add the values of custom attributes for pattern matching to your query. They will be compared
+   * Add the values of specified {@linkplain ClassificationCustomField ClassificationCustomFields}
-   * in SQL with the LIKE operator. You may use a wildcard like % to specify the pattern. If you
+   * for pattern matching to your query. They will be compared in SQL with the LIKE operator. You
-   * specify multiple arguments they are combined with the OR keyword.
+   * may use a wildcard like % to specify the pattern. If you specify multiple arguments they are
+   * combined with the OR keyword.
    *
    * @param customField identifies which custom attribute is affected.
    * @param searchArguments the customField values of the searched-for tasks
@@ -183,25 +193,26 @@ public interface ClassificationQuery
       throws InvalidArgumentException;
 
   /**
-   * Sort the query result by key.
+   * Sort the query result by {@linkplain ClassificationSummary#getKey() key}.
    *
-   * @param sortDirection Determines whether the result is sorted in ascending or descending order.
+   * @param sortDirection Determines whether the result is sorted in ascending or descending order
    *     If sortDirection is null, the result is sorted in ascending order
    * @return the query
    */
   ClassificationQuery orderByKey(SortDirection sortDirection);
 
   /**
-   * Sort the query result by the parent classification ID.
+   * Sort the query result by the {@linkplain ClassificationSummary#getParentId() id of the parent}.
    *
-   * @param sortDirection Determines whether the result is sorted in ascending or descending order.
+   * @param sortDirection Determines whether the result is sorted in ascending or descending order
    *     If sortDirection is null, the result is sorted in ascending order
    * @return the query
    */
   ClassificationQuery orderByParentId(SortDirection sortDirection);
 
   /**
-   * Sort the query result by the parent classification key.
+   * Sort the query result by the {@linkplain ClassificationSummary#getParentKey() key of the
+   * parent}.
    *
    * @param sortDirection Determines whether the result is sorted in ascending or descending order.
    *     If sortDirection is null, the result is sorted in ascending order
@@ -210,16 +221,16 @@ public interface ClassificationQuery
   ClassificationQuery orderByParentKey(SortDirection sortDirection);
 
   /**
-   * Sort the query result by category.
+   * Sort the query result by {@linkplain ClassificationSummary#getCategory() category}.
    *
-   * @param sortDirection Determines whether the result is sorted in ascending or descending order.
+   * @param sortDirection Determines whether the result is sorted in ascending or descending order
    *     If sortDirection is null, the result is sorted in ascending order
    * @return the query
    */
   ClassificationQuery orderByCategory(SortDirection sortDirection);
 
   /**
-   * Sort the query result by domain.
+   * Sort the query result by {@linkplain ClassificationSummary#getDomain() domain}.
    *
    * @param sortDirection Determines whether the result is sorted in ascending or descending order.
    *     If sortDirection is null, the result is sorted in ascending order
@@ -228,7 +239,7 @@ public interface ClassificationQuery
   ClassificationQuery orderByDomain(SortDirection sortDirection);
 
   /**
-   * Sort the query result by name.
+   * Sort the query result by {@linkplain ClassificationSummary#getName() name}.
    *
    * @param sortDirection Determines whether the result is sorted in ascending or descending order.
    *     If sortDirection is null, the result is sorted in ascending order
@@ -237,7 +248,7 @@ public interface ClassificationQuery
   ClassificationQuery orderByName(SortDirection sortDirection);
 
   /**
-   * Sort the query result by service level.
+   * Sort the query result by {@linkplain ClassificationSummary#getServiceLevel() serviceLevel}.
    *
    * @param sortDirection Determines whether the result is sorted in ascending or descending order.
    *     If sortDirection is null, the result is sorted in ascending order
@@ -246,7 +257,7 @@ public interface ClassificationQuery
   ClassificationQuery orderByServiceLevel(SortDirection sortDirection);
 
   /**
-   * Sort the query result by priority.
+   * Sort the query result by {@linkplain ClassificationSummary#getPriority() priority}.
    *
    * @param sortDirection Determines whether the result is sorted in ascending or descending order.
    *     If sortDirection is null, the result is sorted in ascending order
@@ -255,7 +266,8 @@ public interface ClassificationQuery
   ClassificationQuery orderByPriority(SortDirection sortDirection);
 
   /**
-   * Sort the query result by the application entry point name.
+   * Sort the query result by the {@linkplain ClassificationSummary#getApplicationEntryPoint() name
+   * of the application entry point}.
    *
    * @param sortDirection Determines whether the result is sorted in ascending or descending order.
    *     If sortDirection is null, the result is sorted in ascending order
@@ -264,7 +276,8 @@ public interface ClassificationQuery
   ClassificationQuery orderByApplicationEntryPoint(SortDirection sortDirection);
 
   /**
-   * This method sorts the query result according to the value of a custom field.
+   * This method sorts the query result according to the value of the specified {@linkplain
+   * ClassificationCustomField custom field}.
    *
    * @param customField identifies which custom attribute is affected.
    * @param sortDirection Determines whether the result is sorted in ascending or descending order.

lib/taskana-core/src/main/java/pro/taskana/classification/api/ClassificationService.java

@@ -10,86 +10,110 @@ import pro.taskana.common.api.exceptions.DomainNotFoundException;
 import pro.taskana.common.api.exceptions.InvalidArgumentException;
 import pro.taskana.common.api.exceptions.NotAuthorizedException;
 
-/** This class manages the classifications. */
+/** This class manages {@linkplain Classification Classifications}. */
 public interface ClassificationService {
 
   /**
-   * Get the Classification for key and domain. If there's no Classification in the given domain,
+   * Gets the {@linkplain Classification} identified by the provided {@linkplain
-   * return the Classification from the master domain.
+   * Classification#getKey() key} and {@linkplain Classification#getDomain() domain}. If there's no
+   * {@linkplain Classification} in the given {@linkplain Classification#getDomain() domain},
+   * returns the {@linkplain Classification} from the master domain.
    *
-   * @param key the key of the searched-for classifications
+   * @param key the {@linkplain Classification#getKey() key} of the searched-for {@linkplain
-   * @param domain the domain of the searched-for classifications
+   *     Classification}
-   * @return If exist: domain-specific classification, else master classification
+   * @param domain the {@linkplain Classification#getDomain() domain} of the searched-for
-   * @throws ClassificationNotFoundException if no classification is found that matches the key
+   *     {@linkplain Classification}
-   *     either in domain or in the master domain.
+   * @return if exist: domain-specific {@linkplain Classification}, else master {@linkplain
+   *     Classification}
+   * @throws ClassificationNotFoundException if no {@linkplain Classification} is found that matches
+   *     the {@linkplain Classification#getKey() key} either in {@linkplain
+   *     Classification#getDomain() domain} or in the master {@linkplain Classification#getDomain()
+   *     domain}
    */
   Classification getClassification(String key, String domain)
       throws ClassificationNotFoundException;
 
   /**
-   * Get the Classification by id.
+   * Gets the {@linkplain Classification} identified by the provided {@linkplain
+   * Classification#getId() id}.
    *
-   * @param id the id of the searched-for classifications
+   * @param id the {@linkplain Classification#getId() id} of the searched-for {@linkplain
-   * @return the classification identified by id
+   *     Classification}
-   * @throws ClassificationNotFoundException if no classification is found that matches the id.
+   * @return the {@linkplain Classification} identified by {@linkplain Classification#getId() id}
+   * @throws ClassificationNotFoundException if no {@linkplain Classification} is found that matches
+   *     the {@linkplain Classification#getId() id}
    */
   Classification getClassification(String id) throws ClassificationNotFoundException;
 
   /**
-   * Delete a classification with all child classifications.
+   * Deletes a {@linkplain Classification} with all child {@linkplain Classification
+   * Classifications}.
    *
-   * @param id the id of the searched-for classifications
+   * @param id the {@linkplain Classification#getId() id} of the searched-for {@linkplain
-   * @throws ClassificationInUseException if there are Task existing, which refer to this
+   *     Classification}
-   *     classification.
+   * @throws ClassificationInUseException if there are {@linkplain
-   * @throws ClassificationNotFoundException if for an domain no classification specification is
+   *     pro.taskana.task.api.models.Task}s which refer to this {@linkplain Classification}
-   *     found.
+   * @throws ClassificationNotFoundException if no {@linkplain Classification} with the specified
-   * @throws NotAuthorizedException if the current user is not member of role BUSINESS_ADMIN or
+   *     {@linkplain Classification#getId() id} is found
-   *     ADMIN
+   * @throws NotAuthorizedException if the current user is not member of role {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN} or {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#ADMIN}
    */
   void deleteClassification(String id)
       throws ClassificationInUseException, ClassificationNotFoundException, NotAuthorizedException;
 
   /**
-   * Delete a classification with all child classifications.
+   * Deletes the {@linkplain Classification} identified by the provided {@linkplain
+   * Classification#getKey() key} and {@linkplain Classification#getDomain() domain} with all its
+   * child {@linkplain Classification Classifications}.
    *
-   * @param classificationKey the key of the classification you want to delete.
+   * @param classificationKey the {@linkplain Classification#getKey() key} of the {@linkplain
-   * @param domain the domains for which you want to delete the classification. if "", the function
+   *     Classification} you want to delete.
-   *     tries to delete the "master domain" classification and any other classification with this
+   * @param domain the {@linkplain Classification#getDomain() domain} of the the {@linkplain
-   *     key.
+   *     Classification} you want to delete. if "", the function tries to delete the "master domain"
-   * @throws ClassificationInUseException if there are Task existing, which refer to this
+   *     {@linkplain Classification} and any other {@linkplain Classification} with this {@linkplain
-   *     classification.
+   *     Classification#getKey() key}.
-   * @throws ClassificationNotFoundException if for an domain no classification specification is
+   * @throws ClassificationInUseException if there are {@linkplain
-   *     found.
+   *     pro.taskana.task.api.models.Task}s which refer to this {@linkplain Classification}.
-   * @throws NotAuthorizedException if the current user is not member of role BUSINESS_ADMIN or
+   * @throws ClassificationNotFoundException if no {@linkplain Classification} with the specified
-   *     ADMIN
+   *     {@linkplain Classification#getKey() key} and {@linkplain Classification#getDomain() domain}
+   *     is found.
+   * @throws NotAuthorizedException if the current user is not member of role {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN} or {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#ADMIN}
    */
   void deleteClassification(String classificationKey, String domain)
       throws ClassificationInUseException, ClassificationNotFoundException, NotAuthorizedException;
 
   /**
-   * Inserts a new Classification after adding default values. <br>
+   * Inserts a new {@linkplain Classification} after applying default values. <br>
-   * The Classification will be added to master-domain, too - if not already existing. <br>
+   * The {@linkplain Classification} will be added to master-domain, too - if not already existing.
+   * <br>
    * The default values are:
    *
    * <ul>
-   *   <li><b>id</b> - generated by {@linkplain pro.taskana.common.internal.util.IdGenerator
+   *   <li><b>{@linkplain Classification#getId() id}</b> - generated by {@linkplain
-   *       IdGenerator}
+   *       pro.taskana.common.internal.util.IdGenerator IdGenerator}
-   *   <li><b>parentId</b> - ""
+   *   <li><b>{@linkplain Classification#getParentId() parentId}</b> - ""
-   *   <li><b>parentKey</b> - ""
+   *   <li><b>{@linkplain Classification#getParentKey() parentKey}</b> - ""
-   *   <li><b>serviceLevel</b> - "P0D"
+   *   <li><b>{@linkplain Classification#getServiceLevel() serviceLevel}</b> - "P0D"
-   *   <li><b>isValidInDomain</b> - {@code true} <br>
+   *   <li><b>{@linkplain Classification#getIsValidInDomain() isValidInDomain}</b> - {@code true}
-   *       if {@code domain} an empty string than {@code false}
+   *       <br>
+   *       if {@linkplain Classification#getDomain() domain} an empty string than {@code false}
    * </ul>
    *
-   * @param classification the Classification to insert
+   * @param classification the {@linkplain Classification} to insert
-   * @return Classification which is equipped with unique ID.
+   * @return the inserted {@linkplain Classification} with unique {@linkplain Classification#getId()
-   * @throws ClassificationAlreadyExistException if the Classification does already exists at the
+   *     id}.
-   *     given domain.
+   * @throws ClassificationAlreadyExistException if the {@linkplain Classification} already exists
-   * @throws NotAuthorizedException if the current user is not member of role BUSINESS_ADMIN or
+   *     in the given {@linkplain Classification#getDomain() domain}.
-   *     ADMIN
+   * @throws NotAuthorizedException if the current user is not member of role {@linkplain
-   * @throws DomainNotFoundException if the {@code domain} does not exist in the configuration
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN} or {@linkplain
-   * @throws MalformedServiceLevelException if the {@code serviceLevel} property does not comply
+   *     pro.taskana.common.api.TaskanaRole#ADMIN}
-   *     with the ISO 8601 specification
+   * @throws DomainNotFoundException if the {@linkplain Classification#getDomain() domain} does not
+   *     exist in the configuration
+   * @throws MalformedServiceLevelException if the {@linkplain Classification#getServiceLevel()
+   *     serviceLevel} does not comply with the ISO 8601 specification
    * @throws InvalidArgumentException if the {@linkplain Classification} contains invalid properties
    */
   Classification createClassification(Classification classification)
@@ -97,16 +121,20 @@ public interface ClassificationService {
           InvalidArgumentException, MalformedServiceLevelException;
 
   /**
-   * Updates a Classification.
+   * Updates the specified {@linkplain Classification}.
    *
-   * @param classification the Classification to update
+   * @param classification the {@linkplain Classification} to update
-   * @return the updated Classification.
+   * @return the updated {@linkplain Classification}.
-   * @throws ClassificationNotFoundException if the classification OR it's parent does not exist.
+   * @throws ClassificationNotFoundException if the {@linkplain Classification} or its parent does
-   * @throws NotAuthorizedException if the caller got no ADMIN or BUSINESS_ADMIN permissions.
+   *     not exist.
-   * @throws ConcurrencyException If the classification was modified in the meantime and is not the
+   * @throws NotAuthorizedException if the caller got no {@linkplain
-   *     most up to date anymore.
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN} or {@linkplain
-   * @throws MalformedServiceLevelException if the {@code serviceLevel} property does not comply
+   *     pro.taskana.common.api.TaskanaRole#ADMIN} permissions.
-   *     with the ISO 8601 specification
+   * @throws ConcurrencyException if the {@linkplain Classification} was modified in the meantime
+   *     and is not the most up to date anymore; that's the case if the given modified timestamp
+   *     differs from the one in the database
+   * @throws MalformedServiceLevelException if the {@linkplain Classification#getServiceLevel()
+   *     serviceLevel} does not comply with the ISO 8601 specification
    * @throws InvalidArgumentException if the {@linkplain Classification} contains invalid properties
    */
   Classification updateClassification(Classification classification)
@@ -116,18 +144,22 @@ public interface ClassificationService {
   /**
    * This method provides a query builder for querying the database.
    *
-   * @return a {@link ClassificationQuery}
+   * @return a {@linkplain ClassificationQuery}
    */
   ClassificationQuery createClassificationQuery();
 
   /**
-   * Creating a new {@link Classification} with unchangeable default values. It will be only
+   * Creating a new {@link Classification} initialized with unchangeable values for {@linkplain
-   * generated and is not inserted until CREATE-call.
+   * Classification#getKey() key}, {@linkplain Classification#getDomain() domain} and {@linkplain
+   * Classification#getType() type}. The classification will not be inserted into the database until
+   * {@linkplain ClassificationService#createClassification(Classification)} call.
    *
-   * @param key the key of the classification
+   * @param key the {@linkplain Classification#getKey() key} of the {@linkplain Classification}
-   * @param domain the domain of the new classification
+   * @param domain the {@linkplain Classification#getDomain() domain} of the new {@linkplain
-   * @param type the type of the new classification
+   *     Classification}
-   * @return classification to specify
+   * @param type the {@linkplain Classification#getType() type} of the new {@linkplain
+   *     Classification}
+   * @return the initialized {@linkplain Classification}
    */
   Classification newClassification(String key, String domain, String type);
 }

lib/taskana-core/src/main/java/pro/taskana/classification/api/models/Classification.java

@@ -8,51 +8,51 @@ import pro.taskana.classification.api.ClassificationCustomField;
 public interface Classification extends ClassificationSummary {
 
   /**
-   * Set/Change a reference to the current parent classification via ID. EMPTY if there is no
+   * Sets/Changes a reference to the current parent Classification via id. If the Classification has
-   * parent.
+   * no parent, the value of parentId should be an empty String.
    *
-   * @param parentId The ID of the parent classification.
+   * @param parentId the id of the parent Classification
    */
   void setParentId(String parentId);
 
   /**
-   * Set/Change a reference to the current parent classification via key. EMPTY if there is no
+   * Sets/Changes a reference to the current parent Classification via key. If the Classification
-   * parent.
+   * has no parent, the value of parentKey should be an empty String.
    *
-   * @param parentKey The key of the parent classification.
+   * @param parentKey the key of the parent Classification
    */
   void setParentKey(String parentKey);
 
   /**
-   * Set/Change the category of this classification.
+   * Sets/Changes the category of the Classification.
    *
-   * @param category The category of the classification.
+   * @param category the category of the Classification
    */
   void setCategory(String category);
 
   /**
-   * Get the current domain-name of this classification.
+   * Returns the current domain of the Classification.
    *
-   * @return domain name
+   * @return domain
    */
   String getDomain();
 
   /**
-   * Get the logical name of the associated application entry point.
+   * Returns the logical name of the associated applicationEntryPoint of the Classification.
    *
    * @return applicationEntryPoint
    */
   String getApplicationEntryPoint();
 
   /**
-   * Set the logical name of the associated application entry point.
+   * Sets the logical name of the associated applicationEntryPoint of the Classification.
    *
-   * @param applicationEntryPoint The application entry point
+   * @param applicationEntryPoint the applicationEntryPoint
    */
   void setApplicationEntryPoint(String applicationEntryPoint);
 
   /**
-   * Duplicates this Classification without the id.
+   * Duplicates the Classification without the id.
    *
    * @param key for the new Classification
    * @return a copy of this Classification
@@ -60,91 +60,94 @@ public interface Classification extends ClassificationSummary {
   Classification copy(String key);
 
   /**
-   * Get a flag if the classification if currently valid in the used domain.
+   * Returns whether the Classification is currently valid in the used domain.
    *
-   * @return isValidInDomain - flag
+   * @return isValidInDomain
    */
   Boolean getIsValidInDomain();
 
   /**
-   * Set/Change the flag which marks the classification as valid/invalid in the currently used
+   * Sets/Changes the flag which marks the Classification as valid/invalid in the currently used
    * domain.
    *
-   * @param isValidInDomain - flag
+   * @param isValidInDomain flag
    */
   void setIsValidInDomain(Boolean isValidInDomain);
 
   /**
-   * Get the timestamp when this classification was as created.
+   * Returns the time when the Classification was created.
    *
-   * @return created as instant
+   * @return the time of creation as Instant
    */
   Instant getCreated();
 
   /**
-   * Get the timestamp when this classification was as modified the last time.
+   * Returns the time when the Classification was modified the last time.
    *
-   * @return modified as instant
+   * @return the time of last modification as Instant
    */
   Instant getModified();
 
   /**
-   * Set/Change the classification name.
+   * Sets/Changes the name of the Classification.
    *
    * @param name the name of the Classification
    */
   void setName(String name);
 
   /**
-   * Get the description of a classification.
+   * Returns the description of the Classification.
    *
    * @return description
    */
   String getDescription();
 
   /**
-   * Set/Change the classification description.
+   * Sets/Changes the description of the Classification.
    *
    * @param description the description of the Classification
    */
   void setDescription(String description);
 
   /**
-   * Set/Change the numeric priority of a classification.
+   * Sets/Changes the numeric priority of the Classification.
    *
-   * @param priority the Priority of the Classification
+   * @param priority the priority of the Classification
    */
   void setPriority(int priority);
 
   /**
-   * Set/Change the service level.
+   * Sets/Changes the serviceLevel of the Classification.
    *
-   * @param serviceLevel the service level. Must be a String in ISO-8601 duration format. See the
+   * @param serviceLevel the serviceLevel; must be a String in ISO-8601 duration format; see the
-   *     parse() method of {@code Duration} for details.
+   *     parse() method of {@code Duration} for details
    */
   void setServiceLevel(String serviceLevel);
 
   /**
-   * Sets the value for custom Attribute.
+   * Sets the value for the specified {@linkplain ClassificationCustomField
+   * ClassificationCustomField}.
    *
-   * @param customField identifies which custom attribute is to be set.
+   * @param customField the {@linkplain ClassificationCustomField ClassificationCustomField}
-   * @param value the value of the custom attribute to be set
+   *     identifies which custom attribute is to be set
-   * @deprecated Use {@link #setCustomField(ClassificationCustomField, String)} instead
+   * @param value the value of the {@linkplain ClassificationCustomField ClassificationCustomField}
+   *     to be set
+   * @deprecated Use {@linkplain #setCustomField(ClassificationCustomField, String)} instead
    */
   void setCustomAttribute(ClassificationCustomField customField, String value);
 
   /**
-   * Sets the value for custom field.
+   * Sets the value for {@linkplain ClassificationCustomField}.
    *
-   * @param customField identifies which custom field is to be set.
+   * @param customField identifies which {@linkplain ClassificationCustomField} is to be set
-   * @param value the value of the custom field to be set
+   * @param value the value of the {@linkplain ClassificationCustomField} to be set
    */
   void setCustomField(ClassificationCustomField customField, String value);
 
   /**
-   * Return a summary of the current Classification.
+   * Return a summary of the Classification.
    *
-   * @return the ClassificationSummary object for the current classification
+   * @return the {@linkplain ClassificationSummary} object for the current Classification
    */
   ClassificationSummary asSummary();
 }

lib/taskana-core/src/main/java/pro/taskana/classification/api/models/ClassificationSummary.java

@@ -4,102 +4,108 @@ import pro.taskana.classification.api.ClassificationCustomField;
 
 /**
  * Interface for ClassificationSummaries. This is a specific short model-object which only requieres
- * the most important information. Specific ones can be load afterwards via ID.
+ * the most important information. Detailed information can be load afterwards via id.
  */
 public interface ClassificationSummary {
 
   /**
-   * Gets the id of the classification.
+   * Returns the id of the Classification.
    *
-   * @return classificationId
+   * @return the id of the Classification
    */
   String getId();
 
   /**
-   * Gets the key of the classification.
+   * Returns the key of the Classification.
    *
-   * @return classificationKey
+   * @return the key of the Classification
    */
   String getKey();
 
   /**
-   * Gets the category of the classification.
+   * Returns the category of the Classification.
    *
-   * @return classificationCategory
+   * @return the category of the Classification
    */
   String getCategory();
 
   /**
-   * Gets the type of the classification.
+   * Returns the type of the Classification.
    *
-   * @return classificationType
+   * @return the type of the Classification
    */
   String getType();
 
   /**
-   * Gets the domain of the classification.
+   * Returns the domain of the Classification.
    *
-   * @return classificationDomain
+   * @return the domain of the Classification
    */
   String getDomain();
 
   /**
-   * Gets the name of the classification.
+   * Returns the name of the Classification.
    *
-   * @return classificationName
+   * @return the name of the Classification
    */
   String getName();
 
   /**
-   * Gets the ID of the parent classification.
+   * Returns the id of the parent Classification.
    *
    * @return parentId
    */
   String getParentId();
 
   /**
-   * Gets the key of the parent classification.
+   * Returns the key of the parent Classification.
    *
    * @return parentKey
    */
   String getParentKey();
 
   /**
-   * Gets the service level of the classification. It is a String in ISO-8601 duration format. See
+   * Returns the serviceLevel of the Classification. It is a String in ISO-8601 duration format. See
    * the parse() method of {@code Duration} for details.
    *
-   * @return the service level
+   * @return serviceLevel
    */
   String getServiceLevel();
 
   /**
-   * Gets the application entry point of the classification.
+   * Returns the applicationEntryPoint of the Classification.
    *
-   * @return the application entry point
+   * @return applicationEntryPoint
    */
   String getApplicationEntryPoint();
 
   /**
-   * Gets the priority of the classification.
+   * Returns the priority of the Classification.
    *
-   * @return the priority
+   * @return priority
    */
   int getPriority();
 
   /**
-   * Gets the custom attribute of the classification.
+   * Returns the value of the specified {@linkplain ClassificationCustomField
+   * ClassificationCustomField} of the Classification.
    *
-   * @param customField identifies which custom attribute is requested.
+   * @param customField identifies which {@linkplain ClassificationCustomField
-   * @return the value for the given customField
+   *     ClassificationCustomField} is requested
-   * @deprecated Use {@link #getCustomField(ClassificationCustomField)} instead
+   * @return the value for the given {@linkplain ClassificationCustomField
+   *     ClassificationCustomField}
+   * @deprecated Use {@linkplain #getCustomField(ClassificationCustomField)} instead
    */
   String getCustomAttribute(ClassificationCustomField customField);
 
   /**
-   * Gets the custom field of the classification.
+   * Returns the value of the specified {@linkplain ClassificationCustomField
+   * ClassificationCustomField} of the classification.
    *
-   * @param customField identifies which custom field is requested.
+   * @param customField identifies which {@linkplain ClassificationCustomField
-   * @return the value for the given custom field
+   *     ClassificationCustomField} is requested
+   * @return the value for the given {@linkplain ClassificationCustomField
+   *     ClassificationCustomField}
    */
   String getCustomField(ClassificationCustomField customField);
 

lib/taskana-core/src/main/java/pro/taskana/classification/internal/ClassificationServiceImpl.java

@@ -508,8 +508,9 @@ public class ClassificationServiceImpl implements ClassificationService {
    *
    * @param classificationImpl the classification
    * @return the old classification
-   * @throws ConcurrencyException if the classification has been modified by some other process.
+   * @throws ConcurrencyException if the classification has been modified by some other process;
-   * @throws ClassificationNotFoundException if the given classification does not exist.
+   *     that's the case if the given modified timestamp differs from the one in the database
+   * @throws ClassificationNotFoundException if the given classification does not exist
    */
   private Classification getExistingClassificationAndVerifyTimestampHasNotChanged(
       ClassificationImpl classificationImpl)

lib/taskana-core/src/main/java/pro/taskana/common/api/JobService.java

@@ -1,13 +1,15 @@
 package pro.taskana.common.api;
 
-/** Service to manage the TASKANA jobs. */
+import pro.taskana.common.internal.jobs.TaskanaJob;
+
+/** Service to manage the {@linkplain TaskanaJob TaskanaJobs}. */
 public interface JobService {
 
   /**
-   * Create a schedule a new job.
+   * Initializes the given {@linkplain ScheduledJob} and inserts it into the database.
    *
-   * @param job {@link ScheduledJob} The job to be created.
+   * @param job the {@linkplain ScheduledJob job} to be created
-   * @return {@link ScheduledJob} The created job.
+   * @return the created {@linkplain ScheduledJob job}
    */
   ScheduledJob createJob(ScheduledJob job);
 }

lib/taskana-core/src/main/java/pro/taskana/common/api/TaskanaEngine.java

@@ -9,6 +9,7 @@ import pro.taskana.common.api.exceptions.NotAuthorizedException;
 import pro.taskana.common.api.security.CurrentUserContext;
 import pro.taskana.monitor.api.MonitorService;
 import pro.taskana.task.api.TaskService;
+import pro.taskana.task.api.models.Task;
 import pro.taskana.user.api.UserService;
 import pro.taskana.workbasket.api.WorkbasketService;
 
@@ -16,131 +17,167 @@ import pro.taskana.workbasket.api.WorkbasketService;
 public interface TaskanaEngine {
 
   /**
-   * The TaskService can be used for operations on all Tasks.
+   * Returns a {@linkplain TaskService} initialized with the current TaskanaEngine. {@linkplain
+   * TaskService} can be used for operations on all {@linkplain Task Tasks}.
    *
-   * @return the TaskService
+   * @return an instance of {@linkplain TaskService}
    */
   TaskService getTaskService();
 
   /**
-   * The MonitorService can be used for monitoring Tasks.
+   * Returns a {@linkplain MonitorService} initialized with the current TaskanaEngine. {@linkplain
+   * MonitorService} can be used for monitoring {@linkplain Task Tasks}.
    *
-   * @return the MonitorService
+   * @return an instance of {@linkplain MonitorService}
    */
   MonitorService getMonitorService();
 
   /**
-   * The WorkbasketService can be used for operations on all Workbaskets.
+   * Returns a {@linkplain WorkbasketService} initialized with the current TaskanaEngine. The
+   * {@linkplain WorkbasketService} can be used for operations on all {@linkplain
+   * pro.taskana.workbasket.api.models.Workbasket Workbaskets}.
    *
-   * @return the WorbasketService
+   * @return an instance of {@linkplain WorkbasketService}
    */
   WorkbasketService getWorkbasketService();
 
   /**
-   * The ClassificationService can be used for operations on all Categories.
+   * Returns a {@linkplain ClassificationService} initialized with the current TaskanaEngine. The
+   * {@linkplain ClassificationService} can be used for operations on all {@linkplain
+   * pro.taskana.classification.api.models.Classification Classifications}.
    *
-   * @return the ClassificationService
+   * @return an instance of {@linkplain ClassificationService}
    */
   ClassificationService getClassificationService();
 
   /**
-   * The JobService can be user for all job operations.
+   * Returns a {@linkplain JobService} initialized with the current TaskanaEngine. The {@linkplain
+   * JobService} can be used for all operations on {@linkplain
+   * pro.taskana.common.internal.jobs.TaskanaJob TaskanaJobs}.
    *
-   * @return the JobService
+   * @return an instance of {@linkplain JobService}
    */
   JobService getJobService();
 
+  /**
+   * Returns a {@linkplain UserService} initialized with the current TaskanaEngine. The {@linkplain
+   * UserService} can be used for all operations on {@linkplain pro.taskana.user.api.models.User
+   * Users}.
+   *
+   * @return an instance of {@linkplain UserService}
+   */
   UserService getUserService();
 
+  /**
+   * Returns a {@linkplain ConfigurationService} initialized with the current TaskanaEngine. The
+   * {@linkplain ConfigurationService} can be used to manage custom configuration options.
+   *
+   * @return an instance of {@linkplain ConfigurationService}
+   */
   ConfigurationService getConfigurationService();
 
   /**
-   * The Taskana configuration.
+   * Returns the {@linkplain TaskanaEngineConfiguration configuration} of the TaskanaEngine.
    *
-   * @return the TaskanaConfiguration
+   * @return {@linkplain TaskanaEngineConfiguration configuration}
    */
   TaskanaEngineConfiguration getConfiguration();
 
   /**
-   * The WorkingDaysToDaysConverter used to compute holidays.
+   * Returns the {@linkplain WorkingDaysToDaysConverter} of the TaskanaEngine. The {@linkplain
+   * WorkingDaysToDaysConverter} is used to compute holidays.
    *
-   * @return the converter
+   * @return {@linkplain WorkingDaysToDaysConverter}
    */
   WorkingDaysToDaysConverter getWorkingDaysToDaysConverter();
 
   /**
-   * Checks if the history plugin is enabled.
+   * Checks if the {@linkplain pro.taskana.spi.history.api.TaskanaHistory TaskanaHistory} plugin is
+   * enabled.
    *
-   * @return true if the history is enabled. Otherwise false.
+   * @return true if the history is enabled; otherwise false
    */
   boolean isHistoryEnabled();
 
   /**
-   * gets the current connection management mode.
+   * Returns the {@linkplain ConnectionManagementMode ConnectionManagementMode} of the
+   * TaskanaEngine.
    *
-   * @return the current connection management mode.
+   * @return {@linkplain ConnectionManagementMode ConnectionManagementMode}
    */
   ConnectionManagementMode getConnectionManagementMode();
 
   /**
-   * sets the connection management mode.
+   * Sets {@linkplain ConnectionManagementMode ConnectionManagementMode} of the TaskanaEngine.
    *
-   * @param mode the connection management mode Valid values are:
+   * @param mode the valid values for the {@linkplain ConnectionManagementMode} are:
    *     <ul>
-   *       <li>PARTICIPATE - taskana participates in global transaction. This is the default mode.
+   *       <li>{@linkplain ConnectionManagementMode#PARTICIPATE PARTICIPATE} - taskana participates
-   *       <li>AUTOCOMMIT - taskana commits each API call separately
+   *           in global transaction; this is the default mode
-   *       <li>EXPLICIT - commit processing is managed explicitly by the client
+   *       <li>{@linkplain ConnectionManagementMode#AUTOCOMMIT AUTOCOMMIT} - taskana commits each
+   *           API call separately
+   *       <li>{@linkplain ConnectionManagementMode#EXPLICIT EXPLICIT} - commit processing is
+   *           managed explicitly by the client
    *     </ul>
    */
   void setConnectionManagementMode(ConnectionManagementMode mode);
 
   /**
-   * Set the connection to be used by TASKANA in mode {@linkplain
+   * Set the {@code Connection} to be used by TASKANA in mode {@linkplain
-   * ConnectionManagementMode#EXPLICIT}. If this Api is called, taskana uses the connection passed
+   * ConnectionManagementMode#EXPLICIT EXPLICIT}. If this API is called, TASKANA uses the {@code
-   * by the client for all subsequent API calls until the client resets this connection. Control
+   * Connection} passed by the client for all subsequent API calls until the client resets this
-   * over commit and rollback of the connection is the responsibility of the client. In order to
+   * {@code Connection}. Control over commit and rollback of the {@code Connection} is the
-   * close the connection, closeConnection() or setConnection(null) has to be called.
+   * responsibility of the client. In order to close the {@code Connection}, {@code
+   * closeConnection()} or {@code setConnection(null)} has to be called.
    *
-   * @param connection - The java.sql.Connection that is controlled by the client
+   * @param connection - The {@code java.sql.Connection} that is controlled by the client
    * @throws SQLException if a database access error occurs
    */
   void setConnection(java.sql.Connection connection) throws SQLException;
 
   /**
-   * Closes the client's connection, sets it to null and switches to mode PARTICIPATE. Only
+   * Closes the client's connection, sets it to null and switches to mode {@linkplain
-   * applicable in mode EXPLICIT. Has the same effect as setConnection(null).
+   * ConnectionManagementMode#PARTICIPATE PARTICIPATE}. Only applicable in mode {@linkplain
+   * ConnectionManagementMode#EXPLICIT EXPLICIT}. Has the same effect as {@code
+   * setConnection(null)}.
    */
   void closeConnection();
 
   /**
-   * check whether the current user is member of one of the roles specified.
+   * Check whether the current user is member of one of the {@linkplain TaskanaRole TaskanaRoles}
+   * specified.
    *
-   * @param roles The roles that are checked for membership of the current user
+   * @param roles The {@linkplain TaskanaRole TaskanaRoles} that are checked for membership of the
-   * @return true if the current user is a member of at least one of the specified groups
+   *     current user
+   * @return true if the current user is a member of at least one of the specified {@linkplain
+   *     TaskanaRole TaskanaRole}
    */
   boolean isUserInRole(TaskanaRole... roles);
 
   /**
-   * Checks whether current user is member of any of the specified roles.
+   * Checks whether current user is member of any of the specified {@linkplain TaskanaRole
+   * TaskanaRoles}.
    *
-   * @param roles The roles that are checked for membership of the current user
+   * @param roles The {@linkplain TaskanaRole TaskanaRoles} that are checked for membership of the
-   * @throws NotAuthorizedException If the current user is not member of any specified role
+   *     current user
+   * @throws NotAuthorizedException If the current user is not member of any specified {@linkplain
+   *     TaskanaRole TaskanaRole}
    */
   void checkRoleMembership(TaskanaRole... roles) throws NotAuthorizedException;
 
   /**
-   * Executes a given supplier with admin privileges and thus skips further permission checks. With
+   * Executes a given {@code Supplier} with admin privileges and thus skips further permission
-   * great power comes great responsibility.
+   * checks. With great power comes great responsibility.
    *
    * @param supplier will be executed with admin privileges
-   * @param <T> defined with the supplier return value
+   * @param <T> defined with the return value of the {@code Supplier}
-   * @return output from supplier
+   * @return output from {@code Supplier}
    */
   <T> T runAsAdmin(Supplier<T> supplier);
 
   /**
-   * Executes a given runnable with admin privileges and thus skips further permission checks. With
+   * Executes a given {@code Runnable} with admin privileges and thus skips further permission
-   * great power comes great responsibility.
+   * checks. With great power comes great responsibility.
    *
    * @see #runAsAdmin(Supplier)
    */
@@ -154,9 +191,9 @@ public interface TaskanaEngine {
   }
 
   /**
-   * Returns the CurrentUserContext class.
+   * Returns the {@linkplain CurrentUserContext} of the TaskanaEngine.
    *
-   * @return the CurrentUserContext
+   * @return {@linkplain CurrentUserContext}
    */
   CurrentUserContext getCurrentUserContext();
 
@@ -164,9 +201,12 @@ public interface TaskanaEngine {
    * Connection management mode. Controls the connection handling of taskana
    *
    * <ul>
-   *   <li>PARTICIPATE - taskana participates in global transaction. This is the default mode
+   *   <li>{@linkplain ConnectionManagementMode#PARTICIPATE PARTICIPATE} - taskana participates * in
-   *   <li>AUTOCOMMIT - taskana commits each API call separately
+   *       global transaction; this is the default mode *
-   *   <li>EXPLICIT - commit processing is managed explicitly by the client
+   *   <li>{@linkplain ConnectionManagementMode#AUTOCOMMIT AUTOCOMMIT} - taskana commits each * API
+   *       call separately *
+   *   <li>{@linkplain ConnectionManagementMode#EXPLICIT EXPLICIT} - commit processing is * managed
+   *       explicitly by the client
    * </ul>
    */
   enum ConnectionManagementMode {

lib/taskana-core/src/main/java/pro/taskana/common/internal/TaskanaEngineImpl.java

@@ -309,7 +309,7 @@ public class TaskanaEngineImpl implements TaskanaEngine {
    * This method creates the sqlSessionManager of myBatis. It integrates all the SQL mappers and
    * sets the databaseId attribute.
    *
-   * @return a {@link SqlSessionFactory}
+   * @return a {@linkplain SqlSessionFactory}
    * @throws SystemException when a connection to the database could not be opened.
    */
   protected SqlSessionManager createSqlSessionManager() {

lib/taskana-core/src/main/java/pro/taskana/monitor/api/CombinedClassificationFilter.java

@@ -1,12 +1,17 @@
 package pro.taskana.monitor.api;
 
+import pro.taskana.classification.api.models.Classification;
 import pro.taskana.monitor.api.reports.WorkbasketReport;
+import pro.taskana.task.api.models.Attachment;
+import pro.taskana.task.api.models.Task;
 
 /**
- * The CombinedClassificationFilter is a pair of a classificationId for a task and a
+ * The CombinedClassificationFilter is a pair of a classificationId for a {@linkplain Task} and a
- * classificationId for the corresponding attachment that is used to filter the {@link
+ * classificationId for the corresponding {@linkplain Attachment}. Such pair can only be created for
- * WorkbasketReport} by the classification of the attachment. To filter by the classification of the
+ * tasks that have no more than one {@linkplain Attachment}. The pair is used to filter the
- * task, the classificationId of the attachment should be null.
+ * {@linkplain WorkbasketReport} by the {@linkplain Classification} of the {@linkplain Attachment}.
+ * To filter by the {@linkplain Classification} of the {@linkplain Task}, the
+ * attachmentClassificationId of the CombinedClassificationFilter should be NULL.
  */
 public class CombinedClassificationFilter {
 

lib/taskana-core/src/main/java/pro/taskana/monitor/api/MonitorService.java

@@ -13,57 +13,58 @@ import pro.taskana.task.api.TaskCustomField;
 public interface MonitorService {
 
   /**
-   * Provides a {@link WorkbasketReport.Builder} for creating a {@link WorkbasketReport}.
+   * Provides a {@linkplain WorkbasketReport.Builder} for creating a {@linkplain WorkbasketReport}.
    *
-   * @return a {@link WorkbasketReport.Builder}
+   * @return a {@linkplain WorkbasketReport.Builder}
    */
   WorkbasketReport.Builder createWorkbasketReportBuilder();
 
   /**
-   * Provides a {@link WorkbasketPriorityReport.Builder} for creating a {@link
+   * Provides a {@linkplain WorkbasketPriorityReport.Builder} for creating a {@link
    * WorkbasketPriorityReport}.
    *
-   * @return a {@link WorkbasketReport.Builder}
+   * @return a {@linkplain WorkbasketReport.Builder}
    */
   WorkbasketPriorityReport.Builder createWorkbasketPriorityReportBuilder();
 
   /**
-   * Provides a {@link ClassificationCategoryReport.Builder} for creating a {@link
+   * Provides a {@linkplain ClassificationCategoryReport.Builder} for creating a {@link
    * ClassificationCategoryReport}.
    *
-   * @return a {@link ClassificationCategoryReport.Builder}
+   * @return a {@linkplain ClassificationCategoryReport.Builder}
    */
   ClassificationCategoryReport.Builder createClassificationCategoryReportBuilder();
 
   /**
-   * Provides a {@link ClassificationReport.Builder} for creating a {@link ClassificationReport} or
+   * Provides a {@linkplain ClassificationReport.Builder} for creating a {@linkplain
-   * a {@link pro.taskana.monitor.api.reports.ClassificationReport.DetailedClassificationReport}.
+   * ClassificationReport} or a {@linkplain
+   * pro.taskana.monitor.api.reports.ClassificationReport.DetailedClassificationReport}.
    *
-   * @return a {@link ClassificationReport.Builder}
+   * @return a {@linkplain ClassificationReport.Builder}
    */
   ClassificationReport.Builder createClassificationReportBuilder();
 
   /**
-   * Provides a {@link TaskCustomFieldValueReport.Builder} for creating a {@link
+   * Provides a {@linkplain TaskCustomFieldValueReport.Builder} for creating a {@link
    * TaskCustomFieldValueReport}.
    *
    * @param taskCustomField the customField whose values should appear in the report
-   * @return a {@link TaskCustomFieldValueReport.Builder}
+   * @return a {@linkplain TaskCustomFieldValueReport.Builder}
    */
   TaskCustomFieldValueReport.Builder createTaskCustomFieldValueReportBuilder(
       TaskCustomField taskCustomField);
 
   /**
-   * Provides a {@link TaskStatusReport.Builder} for creating a {@link TaskStatusReport}.
+   * Provides a {@linkplain TaskStatusReport.Builder} for creating a {@linkplain TaskStatusReport}.
    *
-   * @return a {@link TaskStatusReport.Builder}
+   * @return a {@linkplain TaskStatusReport.Builder}
    */
   TaskStatusReport.Builder createTaskStatusReportBuilder();
 
   /**
-   * Provides a {@link TimestampReport.Builder} for creating a {@link TimestampReport}.
+   * Provides a {@linkplain TimestampReport.Builder} for creating a {@linkplain TimestampReport}.
    *
-   * @return a {@link TimestampReport.Builder}
+   * @return a {@linkplain TimestampReport.Builder}
    */
   TimestampReport.Builder createTimestampReportBuilder();
 }

lib/taskana-core/src/main/java/pro/taskana/monitor/api/TaskTimestamp.java

@@ -2,7 +2,7 @@ package pro.taskana.monitor.api;
 
 import pro.taskana.task.api.models.Task;
 
-/** This enum contains all timestamps saved in the database table for a {@link Task}. */
+/** This enum contains all timestamps saved in the database table for a {@linkplain Task}. */
 public enum TaskTimestamp {
   CREATED,
   CLAIMED,

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/ClassificationCategoryReport.java

@@ -28,7 +28,7 @@ public class ClassificationCategoryReport
     super(timeIntervalColumnHeaders, new String[] {"CLASSIFICATION CATEGORIES"});
   }
 
-  /** Builder for {@link ClassificationCategoryReport}. */
+  /** Builder for {@linkplain ClassificationCategoryReport}. */
   public interface Builder
       extends TimeIntervalReportBuilder<Builder, MonitorQueryItem, TimeIntervalColumnHeader> {
 

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/ClassificationReport.java

@@ -30,7 +30,7 @@ public class ClassificationReport extends Report<MonitorQueryItem, TimeIntervalC
     super(timeIntervalColumnHeaders, new String[] {"CLASSIFICATION"});
   }
 
-  /** Builder for {@link ClassificationReport}. */
+  /** Builder for {@linkplain ClassificationReport}. */
   public interface Builder
       extends TimeIntervalReportBuilder<Builder, MonitorQueryItem, TimeIntervalColumnHeader> {
 
@@ -42,9 +42,9 @@ public class ClassificationReport extends Report<MonitorQueryItem, TimeIntervalC
         throws NotAuthorizedException, InvalidArgumentException;
 
     /**
-     * Returns a {@link DetailedClassificationReport} containing all tasks after applying the
+     * Returns a {@linkplain DetailedClassificationReport} containing all tasks after applying the
      * filters. If the column headers are set the report is subdivided into clusters. Its {@link
-     * FoldableRow}s contain an additional list of {@link Row}s for the classifications of the
+     * FoldableRow}s contain an additional list of {@linkplain Row}s for the classifications of the
      * attachments of the tasks.
      *
      * @return the DetailedClassificationReport

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/Report.java

@@ -16,15 +16,15 @@ import pro.taskana.monitor.api.reports.row.Row;
 import pro.taskana.monitor.api.reports.row.SingleRow;
 
 /**
- * A Report represents an abstract table that consists of {@link Row}s and a list of
+ * A Report represents an abstract table that consists of {@linkplain Row}s and a list of
  * <ColumnHeader>s. Since a report does not specify <Item> and <ColumnHeader> it
  * does not contain functional logic. Due to readability implicit definition of functional logic is
  * prevented and thus prevent initialization of an abstract Report. In order to create a specific
  * Report a subclass has to be created.
  *
- * @param <I> {@link QueryItem} whose value is relevant for this report.
+ * @param <I> {@linkplain QueryItem} whose value is relevant for this report.
- * @param <H> {@link ColumnHeader} which can determine if an &lt;Item&gt; belongs into that column
+ * @param <H> {@linkplain ColumnHeader} which can determine if an &lt;Item&gt; belongs into that
- *     or not.
+ *     column or not.
  */
 public abstract class Report<I extends QueryItem, H extends ColumnHeader<? super I>> {
 
@@ -125,11 +125,11 @@ public abstract class Report<I extends QueryItem, H extends ColumnHeader<? super
   }
 
   /**
-   * Builder for {@link Report}.
+   * Builder for {@linkplain Report}.
    *
-   * @param <I> {@link QueryItem} whose value is relevant for this report.
+   * @param <I> {@linkplain QueryItem} whose value is relevant for this report.
-   * @param <H> {@link ColumnHeader} which can determine if an &lt;Item&gt; belongs into that column
+   * @param <H> {@linkplain ColumnHeader} which can determine if an &lt;Item&gt; belongs into that
-   *     or not.
+   *     column or not.
    */
   public interface Builder<I extends QueryItem, H extends ColumnHeader<? super I>> {
 

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/TaskCustomFieldValueReport.java

@@ -26,7 +26,7 @@ public class TaskCustomFieldValueReport extends Report<MonitorQueryItem, TimeInt
     super(timeIntervalColumnHeaders, new String[] {"TASK CUSTOM FIELDS"});
   }
 
-  /** Builder for {@link TaskCustomFieldValueReport}. */
+  /** Builder for {@linkplain TaskCustomFieldValueReport}. */
   public interface Builder
       extends TimeIntervalReportBuilder<Builder, MonitorQueryItem, TimeIntervalColumnHeader> {
 

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/TaskStatusReport.java

@@ -30,7 +30,7 @@ public class TaskStatusReport extends Report<TaskQueryItem, TaskStatusColumnHead
         new String[] {"DOMAINS"});
   }
 
-  /** Builder for {@link TaskStatusReport}. */
+  /** Builder for {@linkplain TaskStatusReport}. */
   public interface Builder extends Report.Builder<TaskQueryItem, TaskStatusColumnHeader> {
 
     @Override

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/TimeIntervalReportBuilder.java

@@ -26,24 +26,24 @@ public interface TimeIntervalReportBuilder<
     extends Report.Builder<I, H> {
 
   /**
-   * Adds a list {@linkplain TimeIntervalColumnHeader}s to the builder to subdivide the report into
+   * Adds a list {@linkplain TimeIntervalColumnHeader}s to the Builder to subdivide the {@link
-   * clusters.
+   * Report} into clusters.
    *
-   * @param columnHeaders the column headers the report should consist of.
+   * @param columnHeaders the column headers the {@linkplain Report} should consist of.
    * @return the TimeIntervalReportBuilder
    */
   B withColumnHeaders(List<H> columnHeaders);
 
   /**
-   * If this filter is used, the days of the report are counted in working days.
+   * If this filter is used, the days of the Report are counted in working days.
    *
    * @return the TimeIntervalReportBuilder
    */
   B inWorkingDays();
 
   /**
-   * Adds a list of workbasket ids to the builder. The created report contains only tasks with a
+   * Adds a list of workbasket ids to the builder. The created {@linkplain Report} contains only
-   * workbasket id in this list.
+   * {@linkplain Task}s with a workbasketId in this list.
    *
    * @param workbasketIds a list of workbasket ids
    * @return the TimeIntervalReportBuilder
@@ -51,8 +51,8 @@ public interface TimeIntervalReportBuilder<
   B workbasketIdIn(List<String> workbasketIds);
 
   /**
-   * Adds a list of states to the builder. The created report contains only tasks with a state in
+   * Adds a list of states to the builder. The created {@linkplain Report} contains only {@linkplain
-   * this list.
+   * Task Tasks} with a state in this list.
    *
    * @param states a list of states
    * @return the TimeIntervalReportBuilder
@@ -60,8 +60,8 @@ public interface TimeIntervalReportBuilder<
   B stateIn(List<TaskState> states);
 
   /**
-   * Adds a list of classificationCategories to the builder. The created report contains only tasks
+   * Adds a list of classificationCategories to the builder. The created {@linkplain Report}
-   * with a category in this list.
+   * contains only {@linkplain Task Tasks} with a category in this list.
    *
    * @param classificationCategory a list of classificationCategories
    * @return the TimeIntervalReportBuilder
@@ -69,8 +69,8 @@ public interface TimeIntervalReportBuilder<
   B classificationCategoryIn(List<String> classificationCategory);
 
   /**
-   * Adds a list of classificationIds to the builder. The created report contains only tasks with a
+   * Adds a list of classificationIds to the builder. The created {@linkplain Report} contains only
-   * classificationId in this list.
+   * {@linkplain Task Tasks} with a classificationId in this list.
    *
    * @param classificationIds a list of classificationIds
    * @return the TimeIntervalReportBuilder
@@ -78,8 +78,8 @@ public interface TimeIntervalReportBuilder<
   B classificationIdIn(List<String> classificationIds);
 
   /**
-   * Adds a list of excludedClassificationIds to the builder. The created report contains only tasks
+   * Adds a list of excludedClassificationIds to the builder. The created {@linkplain Report}
-   * with a classificationId NOT in this list.
+   * contains only {@linkplain Task Tasks} with a classificationId NOT in this list.
    *
    * @param excludedClassificationIds a list of excludedClassificationIds
    * @return the TimeIntervalReportBuilder
@@ -87,8 +87,8 @@ public interface TimeIntervalReportBuilder<
   B excludedClassificationIdIn(List<String> excludedClassificationIds);
 
   /**
-   * Adds a list of domains to the builder. The created report contains only tasks with a domain in
+   * Adds a list of domains to the builder. The created {@linkplain Report} contains only
-   * this list.
+   * {@linkplain Task Tasks} with a domain in this list.
    *
    * @param domains a list of domains
    * @return the TimeIntervalReportBuilder
@@ -98,9 +98,9 @@ public interface TimeIntervalReportBuilder<
   /**
    * Adds the values of a certain {@linkplain TaskCustomField} for exact matching to the builder.
    *
-   * <p>The created report contains only tasks with a {@linkplain
+   * <p>The created {@linkplain Report} contains only {@linkplain Task Tasks} with a {@linkplain
    * Task#getCustomField(TaskCustomField) custom attribute} value exactly matching one of the items
-   * in the list.
+   * in the List.
    *
    * @param customField the specified {@linkplain TaskCustomField}
    * @param strings the values the specified {@linkplain Task#getCustomField(TaskCustomField) custom
@@ -114,14 +114,14 @@ public interface TimeIntervalReportBuilder<
   /**
    * Excludes the values of a certain {@linkplain TaskCustomField} to the builder.
    *
-   * <p>The created report contains only tasks with a {@linkplain
+   * <p>The created {@linkplain Report} contains only {@linkplain Task Tasks} with a {@linkplain
    * Task#getCustomField(TaskCustomField) custom attribute} value not matching one of the items in
-   * the list.
+   * the List.
    *
    * @param customField the specified {@linkplain TaskCustomField}
    * @param strings the values the specified {@linkplain Task#getCustomField(TaskCustomField) custom
    *     attribute} should not match
-   * @return the modified {@linkplain TimeIntervalReportBuilder}
+   * @return the modified TimeIntervalReportBuilder
    * @throws InvalidArgumentException if filter values are not given
    */
   B customAttributeNotIn(TaskCustomField customField, String... strings)
@@ -130,7 +130,7 @@ public interface TimeIntervalReportBuilder<
   /**
    * Adds the values of a certain {@linkplain TaskCustomField} for pattern matching to the builder.
    *
-   * <p>The created report contains only tasks with a {@linkplain
+   * <p>The created {@linkplain Report} contains only {@linkplain Task Tasks} with a {@linkplain
    * Task#getCustomField(TaskCustomField) custom attribute} value pattern-matching one of the items
    * in the list. They will be compared in SQL with the LIKE operator. You may use a wildcard like %
    * to specify the pattern. If you specify multiple arguments they are combined with the OR
@@ -146,10 +146,11 @@ public interface TimeIntervalReportBuilder<
       throws InvalidArgumentException;
 
   /**
-   * Returns a list of all taskIds of the report that are in the list of selected items.
+   * Returns a list of all taskIds of the {@linkplain Report} that are in the list of selected
+   * items.
    *
    * @param selectedItems a list of selectedItems
-   * @param timestamp the task timestamp of interest
+   * @param timestamp the {@linkplain TaskTimestamp} of interest
    * @return the list of all taskIds
    * @throws InvalidArgumentException if the column headers are not initialized
    * @throws NotAuthorizedException if the user has no rights to access the monitor
@@ -159,9 +160,9 @@ public interface TimeIntervalReportBuilder<
       throws NotAuthorizedException, InvalidArgumentException;
 
   /**
-   * Returns a list of all values of an entered custom field that are in the report.
+   * Returns a list of all values of an entered custom field that are in the {@linkplain Report}.
    *
-   * @param taskCustomField the customField whose values should appear in the list
+   * @param taskCustomField the {@linkplain TaskCustomField} whose values should appear in the list
    * @return the list of all custom attribute values
    * @throws NotAuthorizedException if the user has no rights to access the monitor
    */
@@ -169,10 +170,10 @@ public interface TimeIntervalReportBuilder<
       throws NotAuthorizedException;
 
   /**
-   * Builds the given report.
+   * Builds the {@linkplain Report} for the specified {@linkplain TaskTimestamp}.
    *
-   * @param timestamp The task timestamp of interest
+   * @param timestamp The {@linkplain TaskTimestamp} of interest
-   * @return The build report
+   * @return The build {@linkplain Report}
    * @throws NotAuthorizedException if the user has no rights to access the monitor
    * @throws InvalidArgumentException if an error occurs
    */

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/TimestampReport.java

@@ -39,7 +39,7 @@ public class TimestampReport extends Report<TimestampQueryItem, TimeIntervalColu
     return new TimestampRow(key, columnSize);
   }
 
-  /** Builder for {@link TimestampReport}. */
+  /** Builder for {@linkplain TimestampReport}. */
   public interface Builder
       extends TimeIntervalReportBuilder<
           TimestampReport.Builder, TimestampQueryItem, TimeIntervalColumnHeader> {

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/WorkbasketPriorityReport.java

@@ -27,7 +27,7 @@ public class WorkbasketPriorityReport extends Report<PriorityQueryItem, Priority
     super(priorityColumnHeaders, new String[] {"WORKBASKET"});
   }
 
-  /** Builder for {@link WorkbasketPriorityReport}. */
+  /** Builder for {@linkplain WorkbasketPriorityReport}. */
   public interface Builder extends Report.Builder<PriorityQueryItem, PriorityColumnHeader> {
 
     @Override

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/WorkbasketReport.java

@@ -27,7 +27,7 @@ public class WorkbasketReport extends Report<MonitorQueryItem, TimeIntervalColum
     super(timeIntervalColumnHeaders, new String[] {"WORKBASKET"});
   }
 
-  /** Builder for {@link WorkbasketReport}. */
+  /** Builder for {@linkplain WorkbasketReport}. */
   public interface Builder
       extends TimeIntervalReportBuilder<Builder, MonitorQueryItem, TimeIntervalColumnHeader> {
 
@@ -39,7 +39,7 @@ public class WorkbasketReport extends Report<MonitorQueryItem, TimeIntervalColum
         throws NotAuthorizedException, InvalidArgumentException;
 
     /**
-     * Adds a list of {@link CombinedClassificationFilter} to the builder. The created report
+     * Adds a list of {@linkplain CombinedClassificationFilter} to the builder. The created report
      * contains only tasks with a pair of a classificationId for a task and a classificationId for
      * the corresponding attachment in this list.
      *

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/header/ColumnHeader.java

@@ -4,10 +4,10 @@ import pro.taskana.monitor.api.reports.Report;
 import pro.taskana.monitor.api.reports.item.QueryItem;
 
 /**
- * A ColumnHeader is an element of a {@link Report}. It determines weather a given <Item>
+ * A ColumnHeader is an element of a {@linkplain Report}. It determines weather a given <Item>
  * belongs into the representing column.
  *
- * @param <I> {@link QueryItem} on which the {@link Report} is based on.
+ * @param <I> {@linkplain QueryItem} on which the {@linkplain Report} is based on.
  */
 public interface ColumnHeader<I extends QueryItem> {
 

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/header/TaskStatusColumnHeader.java

@@ -3,7 +3,7 @@ package pro.taskana.monitor.api.reports.header;
 import pro.taskana.monitor.api.reports.item.TaskQueryItem;
 import pro.taskana.task.api.TaskState;
 
-/** The TaskStatusColumnHeader represents a column for each {@link TaskState}. */
+/** The TaskStatusColumnHeader represents a column for each {@linkplain TaskState}. */
 public class TaskStatusColumnHeader implements ColumnHeader<TaskQueryItem> {
 
   private final TaskState state;

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/item/AgeQueryItem.java

@@ -1,9 +1,6 @@
 package pro.taskana.monitor.api.reports.item;
 
-/**
+/** The AgeQueryItem contains age in days. */
- * The MonitorQueryItem entity contains the number of tasks for a key (e.g. workbasketKey) and age
- * in days.
- */
 public interface AgeQueryItem extends QueryItem {
 
   int getAgeInDays();

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/item/DetailedMonitorQueryItem.java

@@ -1,8 +1,8 @@
 package pro.taskana.monitor.api.reports.item;
 
 /**
- * The DetailedMonitorQueryItem extends the {@link MonitorQueryItem}. The additional attachment key
+ * The DetailedMonitorQueryItem extends the {@linkplain MonitorQueryItem}. The additional attachment
- * is used for the detailed classification report.
+ * key is used for the detailed classification report.
  */
 public class DetailedMonitorQueryItem extends MonitorQueryItem {
 

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/item/QueryItem.java

@@ -2,18 +2,23 @@ package pro.taskana.monitor.api.reports.item;
 
 import pro.taskana.monitor.api.reports.Report;
 
-/** A QueryItem is en entity on which a {@link Report} is based on. */
+/**
+ * A QueryItem is en entity on which a {@linkplain Report} is based on. It represents the content of
+ * a cell in the {@linkplain Report}.
+ */
 public interface QueryItem {
 
   /**
-   * The key of a QueryItem determines its row within a {@link Report}.
+   * The key of a QueryItem determines its {@linkplain pro.taskana.monitor.api.reports.row.Row row}
+   * within a {@linkplain Report}.
    *
-   * @return the key of this query item.
+   * @return the key of this QueryItem.
    */
   String getKey();
 
   /**
-   * Its value will be added to the existing cell value during the insertion into a report.
+   * Its value will be added to the existing cell value during the insertion into a {@linkplain
+   * Report}.
    *
    * @return the value
    */

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/item/QueryItemPreprocessor.java

@@ -3,9 +3,9 @@ package pro.taskana.monitor.api.reports.item;
 import pro.taskana.monitor.api.reports.Report;
 
 /**
- * The QueryItemPreprocessor is used when adding {@link QueryItem}s into a {@link Report}. It
+ * The QueryItemPreprocessor is used when adding {@linkplain QueryItem}s into a {@linkplain Report}.
- * defines a processing step which is executed on each {@link QueryItem} before inserting it into
+ * It defines a processing step which is executed on each {@linkplain QueryItem} before inserting it
- * the {@link Report}.
+ * into the {@linkplain Report}.
  *
  * @param <I> Item class which is being pre processed.
  */

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/item/TimestampQueryItem.java

@@ -3,7 +3,7 @@ package pro.taskana.monitor.api.reports.item;
 import pro.taskana.monitor.api.TaskTimestamp;
 import pro.taskana.monitor.api.reports.TimestampReport;
 
-/** The TimestampQueryItem contains the necessary information for the {@link TimestampReport}. */
+/** The TimestampQueryItem represents the content of a cell in the {@linkplain TimestampReport}. */
 public class TimestampQueryItem implements AgeQueryItem {
 
   private static final String N_A = "N/A";

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/row/DetailedClassificationRow.java

@@ -4,8 +4,8 @@ import pro.taskana.monitor.api.reports.ClassificationReport;
 import pro.taskana.monitor.api.reports.item.DetailedMonitorQueryItem;
 
 /**
- * Represents a single Row inside {@link ClassificationReport.DetailedClassificationReport}. The
+ * Represents a single Row inside {@linkplain ClassificationReport.DetailedClassificationReport}.
- * collapsing criteria is the attachement key of each {@link DetailedMonitorQueryItem}.
+ * The collapsing criteria is the attachement key of each {@linkplain DetailedMonitorQueryItem}.
  */
 public class DetailedClassificationRow extends FoldableRow<DetailedMonitorQueryItem> {
 

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/row/FoldableRow.java

@@ -9,11 +9,11 @@ import pro.taskana.monitor.api.reports.Report;
 import pro.taskana.monitor.api.reports.item.QueryItem;
 
 /**
- * The FoldableRow extends the {@link SingleRow}. In contrast to the {@link SingleRow} the
+ * The FoldableRow extends the {@linkplain SingleRow}. In contrast to the {@linkplain SingleRow} the
  * FoldableRow contains rows which can be collapsed or expanded. The FoldableRow itself displays the
  * sum of all foldable rows.
  *
- * @param <I> the {@link QueryItem} on which the {@link Report} is based on.
+ * @param <I> the {@linkplain QueryItem} on which the {@linkplain Report} is based on.
  */
 public abstract class FoldableRow<I extends QueryItem> extends SingleRow<I> {
 

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/row/Row.java

@@ -7,10 +7,10 @@ import pro.taskana.monitor.api.reports.header.ColumnHeader;
 import pro.taskana.monitor.api.reports.item.QueryItem;
 
 /**
- * Representation of a row in a {@link Report}. It contains an array of cells whose index
+ * Representation of a row in a {@linkplain Report}. It contains an array of cells whose index
- * corresponds to the {@link ColumnHeader} index in the {@link Report}.
+ * corresponds to the {@linkplain ColumnHeader} index in the {@linkplain Report}.
  *
- * @param <I> {@link QueryItem} on which the {@link Report} is based on.
+ * @param <I> {@linkplain QueryItem} on which the {@linkplain Report} is based on.
  */
 public interface Row<I extends QueryItem> {
 

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/row/SingleRow.java

@@ -7,10 +7,10 @@ import pro.taskana.monitor.api.reports.header.ColumnHeader;
 import pro.taskana.monitor.api.reports.item.QueryItem;
 
 /**
- * A SingleRow represents a single row in a {@link Report}. It contains an array of cells whose
+ * A SingleRow represents a single row in a {@linkplain Report}. It contains an array of cells whose
- * index corresponds to the {@link ColumnHeader} index in the {@link Report}.
+ * index corresponds to the {@linkplain ColumnHeader} index in the {@linkplain Report}.
  *
- * @param <I> {@link QueryItem} on which the {@link Report} is based on.
+ * @param <I> {@linkplain QueryItem} on which the {@linkplain Report} is based on.
  */
 public class SingleRow<I extends QueryItem> implements Row<I> {
 

lib/taskana-core/src/main/java/pro/taskana/monitor/api/reports/row/TimestampRow.java

@@ -4,7 +4,7 @@ import pro.taskana.monitor.api.reports.TimestampReport;
 import pro.taskana.monitor.api.reports.item.TimestampQueryItem;
 
 /**
- * A single Row inside the {@link TimestampReport}. It contains 4 sub-rows for each org level
+ * A single Row inside the {@linkplain TimestampReport}. It contains 4 sub-rows for each org level
  * respectively.
  */
 public class TimestampRow extends FoldableRow<TimestampQueryItem> {
@@ -24,7 +24,7 @@ public class TimestampRow extends FoldableRow<TimestampQueryItem> {
   }
 
   /**
-   * Row inside the {@link TimestampReport} containing the information regarding a specific org
+   * Row inside the {@linkplain TimestampReport} containing the information regarding a specific org
    * level 1.
    */
   public static final class OrgLevel1Row extends FoldableRow<TimestampQueryItem> {
@@ -45,7 +45,7 @@ public class TimestampRow extends FoldableRow<TimestampQueryItem> {
   }
 
   /**
-   * Row inside the {@link TimestampReport} containing the information regarding a specific org
+   * Row inside the {@linkplain TimestampReport} containing the information regarding a specific org
    * level 2.
    */
   public static final class OrgLevel2Row extends FoldableRow<TimestampQueryItem> {
@@ -66,7 +66,7 @@ public class TimestampRow extends FoldableRow<TimestampQueryItem> {
   }
 
   /**
-   * Row inside the {@link TimestampReport} containing the information regarding a specific org
+   * Row inside the {@linkplain TimestampReport} containing the information regarding a specific org
    * level 3.
    */
   public static final class OrgLevel3Row extends FoldableRow<TimestampQueryItem> {

lib/taskana-core/src/main/java/pro/taskana/monitor/internal/preprocessor/DaysToWorkingDaysReportPreProcessor.java

@@ -9,7 +9,7 @@ import pro.taskana.monitor.api.reports.item.AgeQueryItem;
 import pro.taskana.monitor.api.reports.item.QueryItemPreprocessor;
 
 /**
- * Uses {@link WorkingDaysToDaysConverter} to convert an <I>s age to working days.
+ * Uses {@linkplain WorkingDaysToDaysConverter} to convert an <I>s age to working days.
  *
  * @param <I> QueryItem which is being processed
  */

lib/taskana-core/src/main/java/pro/taskana/monitor/internal/preprocessor/WorkingDaysToDaysReportConverter.java

@@ -18,10 +18,11 @@ import pro.taskana.monitor.api.reports.header.TimeIntervalColumnHeader;
 /**
  * The DaysToWorkingDaysReportConverter provides a method to convert an age in days into an age in
  * working days. Before the method convertDaysToWorkingDays() can be used, the
- * WorkingDaysToDaysConverter has to be initialized. For a list of {@link TimeIntervalColumnHeader}s
+ * WorkingDaysToDaysConverter has to be initialized. For a list of {@linkplain
- * the converter creates a "table" with integer that represents the age in days from the largest
+ * TimeIntervalColumnHeader}s the converter creates a "table" with integer that represents the age
- * lower limit until the smallest upper limit of the timeIntervalColumnHeaders. This table is valid
+ * in days from the largest lower limit until the smallest upper limit of the
- * for a whole day until the converter is initialized with bigger limits.
+ * timeIntervalColumnHeaders. This table is valid for a whole day until the converter is initialized
+ * with bigger limits.
  */
 public class WorkingDaysToDaysReportConverter {
 
@@ -46,14 +47,14 @@ public class WorkingDaysToDaysReportConverter {
   }
 
   /**
-   * Initializes the WorkingDaysToDaysConverter for a list of {@link TimeIntervalColumnHeader}s and
+   * Initializes the WorkingDaysToDaysConverter for a list of {@linkplain TimeIntervalColumnHeader}s
-   * a referenceDate. A new table is only created if there are bigger limits or the date has
+   * and a referenceDate. A new table is only created if there are bigger limits or the date has
    * changed.
    *
-   * @param columnHeaders a list of {@link TimeIntervalColumnHeader}s that determines the size of
+   * @param columnHeaders a list of {@linkplain TimeIntervalColumnHeader}s that determines the size
-   *     the table
+   *     of the table
    * @param converter the converter used by taskana to determine if a specific day is a working day.
-   * @param referenceDate a {@link Instant} that represents the current day of the table
+   * @param referenceDate a {@linkplain Instant} that represents the current day of the table
    * @return an instance of the WorkingDaysToDaysConverter
    * @throws InvalidArgumentException thrown if columnHeaders or referenceDate is null
    */

lib/taskana-core/src/main/java/pro/taskana/monitor/internal/reports/TimeIntervalReportBuilderImpl.java

@@ -24,7 +24,7 @@ import pro.taskana.task.api.TaskCustomField;
 import pro.taskana.task.api.TaskState;
 
 /**
- * Implementation of {@link TimeIntervalReportBuilder}.
+ * Implementation of {@linkplain TimeIntervalReportBuilder}.
  *
  * @param <B> the true Builder behind this Interface
  * @param <I> the true AgeQueryItem inside the Report

lib/taskana-core/src/main/java/pro/taskana/monitor/internal/reports/TimestampReportBuilderImpl.java

@@ -22,7 +22,7 @@ import pro.taskana.monitor.internal.MonitorMapper;
 import pro.taskana.monitor.internal.preprocessor.DaysToWorkingDaysReportPreProcessor;
 import pro.taskana.task.api.TaskState;
 
-/** The implementation of {@link TimestampReport.Builder}. */
+/** The implementation of {@linkplain TimestampReport.Builder}. */
 public class TimestampReportBuilderImpl
     extends TimeIntervalReportBuilderImpl<Builder, TimestampQueryItem, TimeIntervalColumnHeader>
     implements TimestampReport.Builder {

lib/taskana-core/src/main/java/pro/taskana/spi/history/api/TaskanaHistory.java

@@ -15,28 +15,28 @@ public interface TaskanaHistory {
   /**
    * Initialize TaskanaHistory service.
    *
-   * @param taskanaEngine {@link TaskanaEngine} The Taskana engine for needed initialization.
+   * @param taskanaEngine {@linkplain TaskanaEngine} The Taskana engine for needed initialization.
    */
   void initialize(TaskanaEngine taskanaEngine);
 
   /**
-   * Create a new task history event.
+   * Create a new {@linkplain TaskHistoryEvent}.
    *
-   * @param event {@link TaskHistoryEvent} The event to be created.
+   * @param event {@linkplain TaskHistoryEvent} The event to be created.
    */
   void create(TaskHistoryEvent event);
 
   /**
-   * Create a new workbasket history event.
+   * Create a new {@linkplain WorkbasketHistoryEvent}.
    *
-   * @param event {@link WorkbasketHistoryEvent} The event to be created.
+   * @param event {@linkplain WorkbasketHistoryEvent} The event to be created.
    */
   void create(WorkbasketHistoryEvent event);
 
   /**
-   * Create a new classification history event.
+   * Create a new {@linkplain ClassificationHistoryEvent}.
    *
-   * @param event {@link ClassificationHistoryEvent} The event to be created.
+   * @param event {@linkplain ClassificationHistoryEvent} The event to be created.
    */
   void create(ClassificationHistoryEvent event);
 

lib/taskana-core/src/main/java/pro/taskana/spi/routing/api/TaskRoutingProvider.java

@@ -9,14 +9,14 @@ public interface TaskRoutingProvider {
   /**
    * Initialize TaskRoutingProvider service.
    *
-   * @param taskanaEngine {@link TaskanaEngine} The Taskana engine needed for initialization.
+   * @param taskanaEngine {@linkplain TaskanaEngine} The Taskana engine needed for initialization.
    */
   void initialize(TaskanaEngine taskanaEngine);
 
   /**
    * Determines a WorkbasketId for a given task.
    *
-   * @param task {@link Task} The task for which a workbasket must be determined.
+   * @param task {@linkplain Task} The task for which a workbasket must be determined.
    * @return the id of the workbasket in which the task is to be created.
    */
   String determineWorkbasketId(Task task);

lib/taskana-core/src/main/java/pro/taskana/spi/task/api/CreateTaskPreprocessor.java

@@ -5,9 +5,9 @@ import pro.taskana.task.api.models.Task;
 public interface CreateTaskPreprocessor {
 
   /**
-   * Processes a task before its creation.
+   * Processes a {@linkplain Task} before its creation.
    *
-   * @param taskToProcess {@link Task} The Task to preprocess.
+   * @param taskToProcess {@linkplain Task} The Task to preprocess.
    */
   void processTaskBeforeCreation(Task taskToProcess);
 }

lib/taskana-core/src/main/java/pro/taskana/task/api/TaskQuery.java

@@ -5,6 +5,7 @@ import pro.taskana.common.api.KeyDomain;
 import pro.taskana.common.api.TimeInterval;
 import pro.taskana.common.api.exceptions.InvalidArgumentException;
 import pro.taskana.task.api.models.ObjectReference;
+import pro.taskana.task.api.models.Task;
 import pro.taskana.task.api.models.TaskSummary;
 
 /** TaskQuery for generating dynamic sql. */
@@ -493,7 +494,7 @@ public interface TaskQuery extends BaseQuery<TaskSummary, TaskQueryColumnName> {
   /**
    * Add your state to your query.
    *
-   * @param states the states as {@link TaskState}
+   * @param states the states as {@linkplain TaskState}
    * @return the query
    */
   TaskQuery stateIn(TaskState... states);
@@ -501,7 +502,7 @@ public interface TaskQuery extends BaseQuery<TaskSummary, TaskQueryColumnName> {
   /**
    * Exclude these states from your query.
    *
-   * @param states the states as {@link TaskState}
+   * @param states the states as {@linkplain TaskState}
    * @return the query
    */
   TaskQuery stateNotIn(TaskState... states);
@@ -905,7 +906,7 @@ public interface TaskQuery extends BaseQuery<TaskSummary, TaskQueryColumnName> {
   // region primaryObjectReference
 
   /**
-   * Add the {@link ObjectReference} to exact match to your query. Each individual value has to
+   * Add the {@linkplain ObjectReference} to exact match to your query. Each individual value has to
    * match. Fields with the value 'null' will be ignored. The id of each ObjectReference will be
    * ignored
    *
@@ -1474,32 +1475,136 @@ public interface TaskQuery extends BaseQuery<TaskSummary, TaskQueryColumnName> {
 
   // endregion
   // region secondaryObjectReferenceCompany
+
+  /**
+   * Add the values of the {@linkplain ObjectReference#getCompany() company} of at least one of the
+   * {@linkplain Task#getSecondaryObjectReferences() secondaryObjectReferences} for exact matching
+   * to your query.
+   *
+   * @param companyIn the {@linkplain ObjectReference#getCompany() company} values of the searched
+   *     for {@linkplain Task Tasks}
+   * @return the {@linkplain TaskQuery}
+   */
   TaskQuery sorCompanyIn(String... companyIn);
 
+  /**
+   * Add the values of {@linkplain ObjectReference#getCompany() company} of at least one of the
+   * {@linkplain Task#getSecondaryObjectReferences() secondaryobjectReferences} for pattern matching
+   * to your query. They will be compared in SQL with the LIKE operator. You may use a wildcard like
+   * % to specify the pattern. If you specify multiple arguments they are combined with the OR
+   * keyword.
+   *
+   * @param companyLike the {@linkplain ObjectReference#getCompany() company} values of the
+   *     searched-for {@linkplain Task Tasks}
+   * @return the {@linkplain TaskQuery}
+   */
   TaskQuery sorCompanyLike(String... companyLike);
 
   // endregion
   // region secondaryObjectReferenceSystem
+
+  /**
+   * Add the values of the {@linkplain ObjectReference#getSystem() system} of at least one of the
+   * {@linkplain Task#getSecondaryObjectReferences() secondaryObjectReferences} for exact matching
+   * to your query.
+   *
+   * @param systemIn the {@linkplain ObjectReference#getSystem() system} values of the searched for
+   *     {@linkplain Task Tasks}
+   * @return the {@linkplain TaskQuery}
+   */
   TaskQuery sorSystemIn(String... systemIn);
 
+  /**
+   * Add the values of {@linkplain ObjectReference#getSystem system} of at least one of the
+   * {@linkplain Task#getSecondaryObjectReferences() secondaryobjectReferences} for pattern matching
+   * to your query. They will be compared in SQL with the LIKE operator. You may use a wildcard like
+   * % to specify the pattern. If you specify multiple arguments they are combined with the OR
+   * keyword.
+   *
+   * @param systemLike the {@linkplain ObjectReference#getSystem system} values of the searched-for
+   *     {@linkplain Task Tasks}
+   * @return the {@linkplain TaskQuery}
+   */
   TaskQuery sorSystemLike(String... systemLike);
 
   // endregion
   // region secondaryObjectReferenceSystemInstance
+
+  /**
+   * Add the values of the {@linkplain ObjectReference#getSystemInstance() systemInstance} of at
+   * least one of the {@linkplain Task#getSecondaryObjectReferences() secondaryObjectReferences} for
+   * exact matching to your query.
+   *
+   * @param systemInstanceIn the {@linkplain ObjectReference#getSystemInstance() systemInstance}
+   *     values of the searched for {@linkplain Task Tasks}
+   * @return the {@linkplain TaskQuery}
+   */
   TaskQuery sorSystemInstanceIn(String... systemInstanceIn);
 
+  /**
+   * Add the values of {@linkplain ObjectReference#getSystemInstance() systemInstance} of at least
+   * one of the {@linkplain Task#getSecondaryObjectReferences() secondaryobjectReferences} for
+   * pattern matching to your query. They will be compared in SQL with the LIKE operator. You may
+   * use a wildcard like % to specify the pattern. If you specify multiple arguments they are
+   * combined with the OR keyword.
+   *
+   * @param systemInstanceLike the {@linkplain ObjectReference#getSystemInstance() systemInstance}
+   *     values of the searched-for {@linkplain Task Tasks}
+   * @return the {@linkplain TaskQuery}
+   */
   TaskQuery sorSystemInstanceLike(String... systemInstanceLike);
 
   // endregion
   // region secondaryObjectReferenceType
+
+  /**
+   * Add the values of the {@linkplain ObjectReference#getType() type} of at least one of the
+   * {@linkplain Task#getSecondaryObjectReferences() secondaryObjectReferences} for exact matching
+   * to your query.
+   *
+   * @param typeIn the {@linkplain ObjectReference#getType() type} values of the searched for
+   *     {@linkplain Task Tasks}
+   * @return the {@linkplain TaskQuery}
+   */
   TaskQuery sorTypeIn(String... typeIn);
 
+  /**
+   * Add the values of {@linkplain ObjectReference#getType type} of at least one of the {@linkplain
+   * Task#getSecondaryObjectReferences() secondaryobjectReferences} for pattern matching to your
+   * query. They will be compared in SQL with the LIKE operator. You may use a wildcard like % to
+   * specify the pattern. If you specify multiple arguments they are combined with the OR keyword.
+   *
+   * @param typeLike the {@linkplain ObjectReference#getType type} values of the searched-for
+   *     {@linkplain Task Tasks}
+   * @return the {@linkplain TaskQuery}
+   */
   TaskQuery sorTypeLike(String... typeLike);
 
   // endregion
   // region secondaryObjectReferenceValue
+
+  /**
+   * Add the values of the {@linkplain ObjectReference#getValue() value} of at least one of the
+   * {@linkplain Task#getSecondaryObjectReferences() secondaryObjectReferences} for exact matching
+   * to your query.
+   *
+   * @param valueIn the {@linkplain ObjectReference#getValue() value} values of the searched for
+   *     {@linkplain Task Tasks}
+   * @return the {@linkplain TaskQuery}
+   */
   TaskQuery sorValueIn(String... valueIn);
 
+  /**
+   * Add the values of {@linkplain ObjectReference#getValue() value} of at least one of the
+   * {@linkplain Task#getSecondaryObjectReferences() secondaryobjectReferences} for pattern matching
+   * to your query. They will be compared in SQL with the LIKE operator. You may use a wildcard like
+   * % to specify the pattern. If you specify multiple arguments they are combined with the OR
+   * keyword.
+   *
+   * @param valueLike the {@linkplain ObjectReference#getValue() value} values of the searched-for
+   *     {@linkplain Task Tasks}
+   * @return the {@linkplain TaskQuery}
+   */
   TaskQuery sorValueLike(String... valueLike);
 
   // region customAttributes

lib/taskana-core/src/main/java/pro/taskana/task/api/TaskService.java

@@ -5,11 +5,14 @@ import java.util.List;
 import java.util.Map;
 
 import pro.taskana.classification.api.exceptions.ClassificationNotFoundException;
+import pro.taskana.classification.api.models.Classification;
 import pro.taskana.common.api.BulkOperationResults;
+import pro.taskana.common.api.TaskanaRole;
 import pro.taskana.common.api.exceptions.ConcurrencyException;
 import pro.taskana.common.api.exceptions.InvalidArgumentException;
 import pro.taskana.common.api.exceptions.NotAuthorizedException;
 import pro.taskana.common.api.exceptions.TaskanaException;
+import pro.taskana.common.internal.util.IdGenerator;
 import pro.taskana.task.api.exceptions.AttachmentPersistenceException;
 import pro.taskana.task.api.exceptions.InvalidOwnerException;
 import pro.taskana.task.api.exceptions.InvalidStateException;
@@ -21,128 +24,141 @@ import pro.taskana.task.api.models.Attachment;
 import pro.taskana.task.api.models.ObjectReference;
 import pro.taskana.task.api.models.Task;
 import pro.taskana.task.api.models.TaskComment;
+import pro.taskana.workbasket.api.WorkbasketPermission;
 import pro.taskana.workbasket.api.exceptions.WorkbasketNotFoundException;
+import pro.taskana.workbasket.api.models.Workbasket;
 
 /** The Task Service manages all operations on tasks. */
 public interface TaskService {
 
   /**
-   * Claim an existing task for the current user.
+   * Claim an existing {@linkplain Task} for the current user.
    *
-   * @param taskId the id of the task to be claimed
+   * @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} to be claimed
-   * @return claimed Task
+   * @return claimed {@linkplain Task}
-   * @throws TaskNotFoundException if the task with taskId was not found
+   * @throws TaskNotFoundException if the {@linkplain Task} with taskId was not found
-   * @throws InvalidStateException if the state of the task with taskId is not READY
+   * @throws InvalidStateException if the {@linkplain Task#getState() state} of the {@linkplain
-   * @throws InvalidOwnerException if the task with taskId is claimed by some else
+   *     Task} with taskId is not {@linkplain TaskState#READY READY}
-   * @throws NotAuthorizedException if the current user has no read permission for the workbasket
+   * @throws InvalidOwnerException if the {@linkplain Task} with taskId is claimed by some else
-   *     the task is in
+   * @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
+   *     READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in
    */
   Task claim(String taskId)
       throws TaskNotFoundException, InvalidStateException, InvalidOwnerException,
           NotAuthorizedException;
 
   /**
-   * Claim an existing task for the current user even if it is already claimed by someone else.
+   * Claim an existing {@linkplain Task} for the current user even if it is already claimed by
+   * someone else.
    *
-   * @param taskId the id of the task to be claimed
+   * @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} to be claimed
-   * @return claimed Task
+   * @return claimed {@linkplain Task}
-   * @throws TaskNotFoundException if the task with taskId was not found
+   * @throws TaskNotFoundException if the {@linkplain Task} with taskId was not found
-   * @throws InvalidStateException if the state of the task with taskId is not READY
+   * @throws InvalidStateException if the {@linkplain Task#getState() state} of the {@linkplain
-   * @throws InvalidOwnerException if the task with taskId is claimed by someone else
+   *     Task} with taskId is not READY
-   * @throws NotAuthorizedException if the current user has no read permission for the workbasket
+   * @throws InvalidOwnerException if the {@linkplain Task} with taskId is claimed by someone else
-   *     the task is in
+   * @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
+   *     READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in
    */
   Task forceClaim(String taskId)
       throws TaskNotFoundException, InvalidStateException, InvalidOwnerException,
           NotAuthorizedException;
 
   /**
-   * Cancel the claim of an existing task if it was claimed by the current user before.
+   * Cancel the claim of an existing {@linkplain Task} if it was claimed by the current user before.
    *
-   * @param taskId id of the task which should be unclaimed.
+   * @param taskId {@linkplain Task#getId() id} of the task which should be unclaimed.
    * @return updated unclaimed task
-   * @throws TaskNotFoundException if the task can't be found or does not exist
+   * @throws TaskNotFoundException if the {@linkplain Task} can't be found or does not exist
-   * @throws InvalidStateException if the task is already in an end state.
+   * @throws InvalidStateException if the {@linkplain Task} is already in an end {@linkplain
-   * @throws InvalidOwnerException if the task is claimed by another user.
+   *     Task#getState() state}.
-   * @throws NotAuthorizedException if the current user has no read permission for the workbasket
+   * @throws InvalidOwnerException if the {@linkplain Task} is claimed by another user.
-   *     the task is in
+   * @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
+   *     READ} permission for the {@linkplain Workbasket} the task is in
    */
   Task cancelClaim(String taskId)
       throws TaskNotFoundException, InvalidStateException, InvalidOwnerException,
           NotAuthorizedException;
 
   /**
-   * Cancel the claim of an existing task even if it was claimed by another user.
+   * Cancel the claim of an existing {@linkplain Task} even if it was claimed by another user.
    *
-   * @param taskId id of the task which should be unclaimed.
+   * @param taskId id of the {@linkplain Task} which should be unclaimed.
-   * @return updated unclaimed task
+   * @return updated unclaimed {@linkplain Task}
-   * @throws TaskNotFoundException if the task can't be found or does not exist
+   * @throws TaskNotFoundException if the {@linkplain Task} can't be found or does not exist
-   * @throws InvalidStateException if the task is already in an end state.
+   * @throws InvalidStateException if the {@linkplain Task} is already in an end {@linkplain
-   * @throws InvalidOwnerException if forceCancel is false and the task is claimed by another user.
+   *     Task#getState() state}
-   * @throws NotAuthorizedException if the current user has no read permission for the workbasket
+   * @throws InvalidOwnerException if forceCancel is false and the {@linkplain Task} is claimed by
-   *     the task is in
+   *     another user.
+   * @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
+   *     READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in
    */
   Task forceCancelClaim(String taskId)
       throws TaskNotFoundException, InvalidStateException, InvalidOwnerException,
           NotAuthorizedException;
 
   /**
-   * Complete a claimed Task as owner/admin and update State and Timestamps. If task is already
+   * Complete a claimed {@linkplain Task} as owner/admin and update {@linkplain Task#getState()
-   * completed, the task is returned as itself.
+   * state} and Timestamps. If {@linkplain Task} is already completed, the {@linkplain Task} is
+   * returned as itself.
    *
-   * @param taskId - Id of the Task which should be completed.
+   * @param taskId - {@linkplain Task#getId() id} of the {@linkplain Task} which should be
-   * @return Task - updated task after completion.
+   *     completed.
-   * @throws InvalidStateException if Task wasn't claimed before.
+   * @return Task - updated {@linkplain Task} after completion.
-   * @throws TaskNotFoundException if the given Task can't be found in DB.
+   * @throws InvalidStateException if {@linkplain Task} wasn't claimed before.
+   * @throws TaskNotFoundException if the given {@linkplain Task} can't be found in DB.
    * @throws InvalidOwnerException if current user is not the task-owner or administrator.
-   * @throws NotAuthorizedException if the current user has no read permission for the workbasket
+   * @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
-   *     the task is in
+   *     READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in
    */
   Task completeTask(String taskId)
       throws TaskNotFoundException, InvalidOwnerException, InvalidStateException,
           NotAuthorizedException;
 
   /**
-   * Completes a Task and updates State and Timestamps in every case if the Task exists. If task is
+   * Completes a {@linkplain Task} and updates {@linkplain Task#getState() state} and Timestamps in
-   * already completed, the task is returned as itself.
+   * every case if the {@linkplain Task} exists. If {@linkplain Task} is already completed, the
+   * {@linkplain Task} is returned as itself.
    *
-   * @param taskId - Id of the Task which should be completed.
+   * @param taskId - {@linkplain Task#getId() id} of the {@linkplain Task} which should be
-   * @return Task - updated task after completion.
+   *     completed.
-   * @throws InvalidStateException if Task wasn't claimed before.
+   * @return Task - updated {@linkplain Task} after completion.
-   * @throws TaskNotFoundException if the given Task can't be found in DB.
+   * @throws InvalidStateException if {@linkplain Task} wasn't claimed before.
+   * @throws TaskNotFoundException if the given {@linkplain Task} can't be found in DB.
    * @throws InvalidOwnerException if current user is not the task-owner or administrator.
-   * @throws NotAuthorizedException if the current user has no read permission for the workbasket
+   * @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
-   *     the task is in
+   *     READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in
    */
   Task forceCompleteTask(String taskId)
       throws TaskNotFoundException, InvalidOwnerException, InvalidStateException,
           NotAuthorizedException;
 
   /**
-   * Inserts a not existing Task. <br>
+   * Inserts a not existing {@linkplain Task}. <br>
-   * The default values of the created Task are:
+   * The default values of the created {@linkplain Task} are:
    *
    * <ul>
-   *   <li><b>id</b> - generated by {@linkplain pro.taskana.common.internal.util.IdGenerator
+   *   <li><b>{@linkplain Task#getId() id}</b> - generated by {@linkplain IdGenerator}
-   *       IdGenerator}
+   *   <li><b>{@linkplain Task#getExternalId() externalId}</b> - generated by IdGenerator
-   *   <li><b>externalId</b> - generated by IdGenerator
+   *   <li><b>{@linkplain Task#getBusinessProcessId() businessProcessId}</b> - generated by
-   *   <li><b>businessProcessId</b> - generated by IdGenerator
+   *       IdGenerator
-   *   <li><b>name</b> - name of its Classification
+   *   <li><b>{@linkplain Task#getName() name}</b> - name of its Classification
-   *   <li><b>description</b> - description of its Classification
+   *   <li><b>{@linkplain Task#getDescription() description}</b> - description of its Classification
-   *   <li><b>creator</b> - id of current user
+   *   <li><b>{@linkplain Task#getCreator() creator}</b> - id of current user
-   *   <li><b>state</b> - 'READY'
+   *   <li><b>{@linkplain Task#getState() state}</b> - 'READY'
-   *   <li><b>isRead</b> - {@code false}
+   *   <li><b>{@linkplain Task#isRead() isRead}</b> - {@code false}
-   *   <li><b>isTransferred</b> - {@code false}
+   *   <li><b>{@linkplain Task#isTransferred() isTransferred}</b> - {@code false}
    * </ul>
    *
-   * @param taskToCreate the transient task object to be inserted
+   * @param taskToCreate the transient {@linkplain Task} object to be inserted
-   * @return the created and inserted task
+   * @return the created and inserted {@linkplain Task}
-   * @throws TaskAlreadyExistException if the Task does already exist.
+   * @throws TaskAlreadyExistException if the {@linkplain Task} does already exist.
-   * @throws NotAuthorizedException thrown if the current user is not authorized to create that task
+   * @throws NotAuthorizedException thrown if the current user is not authorized to create that
-   * @throws WorkbasketNotFoundException thrown if the workbasket referenced by the task is not
+   *     {@linkplain Task}
-   *     found
+   * @throws WorkbasketNotFoundException thrown if the workbasket referenced by the {@linkplain
-   * @throws ClassificationNotFoundException thrown if the Classification referenced by the task is
+   *     Task} is not found
-   *     not found
+   * @throws ClassificationNotFoundException thrown if the Classification referenced by the
+   *     {@linkplain Task} is not found
    * @throws InvalidArgumentException thrown if the primary ObjectReference is invalid
    * @throws AttachmentPersistenceException if an Attachment with ID will be added multiple times
    *     without using the task-methods
@@ -155,20 +171,20 @@ public interface TaskService {
           ObjectReferencePersistenceException;
 
   /**
-   * Gets the details of a task by Id without checking permissions.
+   * Gets the details of a {@linkplain Task} by {@linkplain Task#getId() id} without checking
+   * permissions.
    *
-   * @param taskId the id of the task
+   * @param taskId the {@linkplain Task#getId()} of the {@linkplain Task}
-   * @return the Task
+   * @return the {@linkplain Task}
-   * @throws TaskNotFoundException thrown of the {@link Task} with taskId is not found
+   * @throws TaskNotFoundException thrown of the {@linkplain Task} with taskId is not found
-   * @throws NotAuthorizedException if the current user has no READ permission for the workbasket
+   * @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
-   *     the task is in.
+   *     READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in.
    */
   Task getTask(String taskId) throws TaskNotFoundException, NotAuthorizedException;
 
   /**
-   * Transfers a {@linkplain Task} to another {@linkplain
+   * Transfers a {@linkplain Task} to another {@linkplain Workbasket} while always setting the
-   * pro.taskana.workbasket.api.models.Workbasket Workbasket} while always setting the {@linkplain
+   * {@linkplain Task#isTransferred transfer} flag.
-   * Task#isTransferred transfer} flag.
    *
    * @see #transfer(String, String, boolean)
    */
@@ -180,35 +196,32 @@ public interface TaskService {
   }
 
   /**
-   * Transfers a {@linkplain Task} to another {@linkplain
+   * Transfers a {@linkplain Task} to another {@linkplain Workbasket}.
-   * pro.taskana.workbasket.api.models.Workbasket Workbasket}.
    *
-   * <p>The transfer resets the read flag and sets the transfer flag if {@code setTransferFlag} is
+   * <p>The transfer resets the {@linkplain Task#isRead() read} flag and sets the {@linkplain
-   * {@code true}.
+   * Task#isTransferred() transfer} flag if {@code setTransferFlag} is {@code true}.
    *
-   * @param taskId the id of the {@linkplain Task} which should be transferred
+   * @param taskId the {@linkplain Task#getId()} of the {@linkplain Task} which should be
-   * @param destinationWorkbasketId the id of the target {@linkplain
+   *     transferred
-   *     pro.taskana.workbasket.api.models.Workbasket Workbasket}
+   * @param destinationWorkbasketId the {@linkplain Workbasket#getId() id} of the target {@linkplain
+   *     Workbasket}
    * @param setTransferFlag the control about whether to set the {@linkplain Task#isTransferred()}
    *     flag or not
    * @return the transferred {@linkplain Task}
    * @throws TaskNotFoundException Thrown if the {@linkplain Task} with taskId was not found.
-   * @throws WorkbasketNotFoundException Thrown if the target {@linkplain
+   * @throws WorkbasketNotFoundException Thrown if the target {@linkplain Workbasket} was not found.
-   *     pro.taskana.workbasket.api.models.Workbasket Workbasket} was not found.
    * @throws NotAuthorizedException Thrown if the current user is not authorized to transfer this
-   *     {@linkplain Task} to the target {@linkplain pro.taskana.workbasket.api.models.Workbasket
+   *     {@linkplain Task} to the target {@linkplain Workbasket}
-   *     Workbasket}
+   * @throws InvalidStateException Thrown if the {@linkplain Task} is in a {@linkplain
-   * @throws InvalidStateException Thrown if the {@linkplain Task} is in a state which does not
+   *     Task#getState() state} which does not allow transferring
-   *     allow transferring
    */
   Task transfer(String taskId, String destinationWorkbasketId, boolean setTransferFlag)
       throws TaskNotFoundException, WorkbasketNotFoundException, NotAuthorizedException,
           InvalidStateException;
 
   /**
-   * Transfers a {@linkplain Task} to another {@linkplain
+   * Transfers a {@linkplain Task} to another {@linkplain Workbasket} while always setting the
-   * pro.taskana.workbasket.api.models.Workbasket Workbasket} while always setting the {@linkplain
+   * {@linkplain Task#isTransferred transfer} flag.
-   * Task#isTransferred transfer} flag.
    *
    * @see #transfer(String, String, String, boolean)
    */
@@ -220,106 +233,106 @@ public interface TaskService {
   }
 
   /**
-   * Transfers a {@linkplain Task} to another {@linkplain
+   * Transfers a {@linkplain Task} to another {@linkplain Workbasket}.
-   * pro.taskana.workbasket.api.models.Workbasket Workbasket}.
    *
-   * <p>The transfer resets the read flag and sets the transfer flag if {@code setTransferFlag} is
+   * <p>The transfer resets the {@linkplain Task#isRead() read} flag and sets the transfer flag if
-   * {@code true}.
+   * {@code setTransferFlag} is {@code true}.
    *
    * @param taskId the id of the {@linkplain Task} which should be transferred
-   * @param workbasketKey the key of the target {@linkplain
+   * @param workbasketKey the key of the target {@linkplain Workbasket}
-   *     pro.taskana.workbasket.api.models.Workbasket Workbasket}
+   * @param domain the domain of the target {@linkplain Workbasket}
-   * @param domain the domain of the target {@linkplain pro.taskana.workbasket.api.models.Workbasket
-   *     Workbasket}
    * @param setTransferFlag the control about whether to set the {@linkplain Task#isTransferred()}
    *     flag or not
    * @return the transferred {@linkplain Task}
-   * @throws TaskNotFoundException Thrown if the {@link Task} with taskId was not found.
+   * @throws TaskNotFoundException Thrown if the {@linkplain Task} with taskId was not found.
-   * @throws WorkbasketNotFoundException Thrown if the target {@linkplain
+   * @throws WorkbasketNotFoundException Thrown if the target {@linkplain Workbasket} was not found.
-   *     pro.taskana.workbasket.api.models.Workbasket Workbasket} was not found.
    * @throws NotAuthorizedException Thrown if the current user is not authorized to transfer this
-   *     {@linkplain Task} to the target Workbasket
+   *     {@linkplain Task} to the target {@linkplain Workbasket}
-   * @throws InvalidStateException Thrown if the {@linkplain Task} is in a state which does not
+   * @throws InvalidStateException Thrown if the {@linkplain Task} is in a {@linkplain
-   *     allow transferring
+   *     Task#getState()} which does not allow transferring
    */
   Task transfer(String taskId, String workbasketKey, String domain, boolean setTransferFlag)
       throws TaskNotFoundException, WorkbasketNotFoundException, NotAuthorizedException,
           InvalidStateException;
 
   /**
-   * Marks a task as read.
+   * Marks a {@linkplain Task} as read.
    *
-   * @param taskId the id of the task to be updated
+   * @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} to be updated
-   * @param isRead the new status of the read flag.
+   * @param isRead the new status of the {@linkplain Task#isRead() read} flag
-   * @return the updated Task
+   * @return the updated {@linkplain Task}
-   * @throws TaskNotFoundException Thrown if the {@link Task} with taskId was not found
+   * @throws TaskNotFoundException Thrown if the {@linkplain Task} with taskId was not found
-   * @throws NotAuthorizedException if the current user has no read permission for the workbasket
+   * @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission
-   *     the task is in
+   *     READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in
    */
   Task setTaskRead(String taskId, boolean isRead)
       throws TaskNotFoundException, NotAuthorizedException;
 
   /**
-   * This method provides a query builder for querying the database.
+   * Provides a query builder for querying the database.
    *
-   * @return a {@link TaskQuery}
+   * @return a {@linkplain TaskQuery}
    */
   TaskQuery createTaskQuery();
 
   /**
    * This method provides a query builder for querying the database.
    *
-   * @return a {@link TaskCommentQuery}
+   * @return a {@linkplain TaskCommentQuery}
    */
   TaskCommentQuery createTaskCommentQuery();
 
   /**
-   * Returns a not inserted instance of {@link Task}. The returned task has no workbasket Id set.
+   * Returns a not inserted instance of {@linkplain Task}. The returned {@linkplain Task} has no
-   * When createTask() is invoked for this task, TaskService will call the TaskRouting SPI to
+   * {@linkplain Task#getWorkbasketSummary() w} set. When createTask() is invoked for this task,
-   * determine a workbasket for the task. If the TaskRouting API is not active, e.g. because no
+   * TaskService will call the TaskRouting SPI to determine a workbasket for the task. If the
-   * TaskRouter is registered, or the TaskRouter(s) don't find a workbasket, the task will not be
+   * TaskRouting API is not active, e.g. because no TaskRouter is registered, or the TaskRouter(s)
-   * inserted.
+   * don't find a workbasket, the task will not be inserted.
    *
    * @return an empty new Task
    */
   Task newTask();
 
   /**
-   * Returns a not inserted instance of {@link Task}.
+   * Returns a not inserted instance of {@linkplain Task}.
    *
-   * @param workbasketId the id of the workbasket to which the task belongs
+   * @param workbasketId the {@linkplain Workbasket#getId() id} of the {@linkplain Workbasket} to
-   * @return an empty new Task
+   *     which the task belongs
+   * @return an empty new {@linkplain Task}
    */
   Task newTask(String workbasketId);
 
   /**
-   * Returns a not inserted instance of {@link Task}.
+   * Returns a not inserted instance of {@linkplain Task}.
    *
-   * @param workbasketKey the key of the workbasket to which the task belongs
+   * @param workbasketKey the {@linkplain Workbasket#getKey() key} of the {@linkplain Workbasket} to
-   * @param domain the domain of the workbasket to which the task belongs
+   *     which the {@linkplain Task} belongs
-   * @return an empty new Task
+   * @param domain the {@linkplain Workbasket#getDomain() domain} of the {@linkplain Workbasket} to
+   *     which the {@linkplain Task} belongs
+   * @return an empty new {@linkplain Task}
    */
   Task newTask(String workbasketKey, String domain);
 
   /**
-   * Returns a not inserted instance of {@link TaskComment}.
+   * Returns a not inserted instance of {@linkplain TaskComment}.
    *
-   * @param taskId The id of the task to which the task comment belongs
+   * @param taskId The {@linkplain Task#getId() id} of the {@linkplain Task} to which the task
-   * @return an empty new TaskComment
+   *     comment belongs
+   * @return an empty new {@linkplain TaskComment}
    */
   TaskComment newTaskComment(String taskId);
 
   /**
-   * Returns a not inserted instance of {@link Attachment}.
+   * Returns a not inserted instance of {@linkplain Attachment}.
    *
-   * @return an empty new Attachment
+   * @return an empty new {@linkplain Attachment}
    */
   Attachment newAttachment();
 
   /**
-   * Returns a not inserted instance of {@link ObjectReference}.
+   * Returns a not inserted instance of {@linkplain ObjectReference}.
    *
-   * @return an empty new ObjectReference
+   * @return an empty new {@linkplain ObjectReference}
    */
   ObjectReference newObjectReference();
 
@@ -327,23 +340,26 @@ public interface TaskService {
       String company, String system, String systemInstance, String type, String value);
 
   /**
-   * Update a task.
+   * Update a {@linkplain Task}.
    *
-   * @param task the task to be updated in the database
+   * @param task the {@linkplain Task} to be updated in the database
-   * @return the updated task
+   * @return the updated {@linkplain Task}
-   * @throws InvalidArgumentException if the task to be updated contains invalid properties like
+   * @throws InvalidArgumentException if the {@linkplain Task} to be updated contains invalid
-   *     e.g. invalid object references
+   *     properties like e.g. invalid {@linkplain ObjectReference}s
-   * @throws TaskNotFoundException if the id of the task is not found in the database
+   * @throws TaskNotFoundException if the id of the {@linkplain Task} is not found in the database
-   * @throws ConcurrencyException if the task has already been updated by another user
+   * @throws ConcurrencyException if the {@linkplain Task} has been updated by another user in the
-   * @throws ClassificationNotFoundException if the updated task refers to a classification that
+   *     meantime; that's the case if the given modified timestamp differs from the one in the
-   *     cannot be found
+   *     database
-   * @throws NotAuthorizedException if the current user is not authorized to update the task
+   * @throws ClassificationNotFoundException if the updated {@linkplain Task} refers to a {@link
-   * @throws AttachmentPersistenceException if an Attachment with ID will be added multiple times
+   *     Classification} that cannot be found
-   *     without using the task-methods
+   * @throws NotAuthorizedException if the current user is not authorized to update the {@linkplain
-   * @throws ObjectReferencePersistenceException if an ObjectReference with ID will be added
+   *     Task}
-   *     multiple times without using the task-methods
+   * @throws AttachmentPersistenceException if an {@linkplain Attachment} with ID will be added
-   * @throws InvalidStateException if an attempt is made to change the owner of the task and the
+   *     multiple times without using the Task-methods
-   *     task is not in state READY .
+   * @throws ObjectReferencePersistenceException if an {@linkplain ObjectReference} with ID will be
+   *     added multiple times without using the Task-methods
+   * @throws InvalidStateException if an attempt is made to change the owner of the {@linkplain
+   *     Task} that state isn't READY.
    */
   Task updateTask(Task task)
       throws InvalidArgumentException, TaskNotFoundException, ConcurrencyException,
@@ -351,9 +367,8 @@ public interface TaskService {
           ObjectReferencePersistenceException, InvalidStateException;
 
   /**
-   * Transfers a list of {@linkplain Task Tasks} to another {@linkplain
+   * Transfers a list of {@linkplain Task Tasks} to another {@linkplain Workbasket} while always
-   * pro.taskana.workbasket.api.models.Workbasket Workbasket} while always setting the {@linkplain
+   * setting the {@linkplain Task#isTransferred transfer} flag.
-   * Task#isTransferred transfer} flag.
    *
    * @see #transferTasks(String, List, boolean)
    */
@@ -365,33 +380,32 @@ public interface TaskService {
   }
 
   /**
-   * Transfers a list of {@linkplain Task Tasks} to another {@linkplain
+   * Transfers a list of {@linkplain Task Tasks} to another {@linkplain Workbasket}.
-   * pro.taskana.workbasket.api.models.Workbasket Workbasket}.
    *
-   * <p>The transfer resets the read flag and sets the transfer flag if {@code setTransferFlag} is
+   * <p>The transfer resets the {@linkplain Task#isRead() read flag} and sets the {@linkplain
-   * {@code true}. Exceptions will be thrown if the caller got no permissions on the target or it
+   * Task#isTransferred() transfer flag} if {@code setTransferFlag} is {@code true}. Exceptions will
-   * does not exist. Other Exceptions will be stored and returned in the end.
+   * be thrown if the caller got no {@linkplain WorkbasketPermission} on the target or if the target
+   * {@linkplain Workbasket} does not exist. Other Exceptions will be stored and returned in the
+   * end.
    *
-   * @param destinationWorkbasketId target {@linkplain pro.taskana.workbasket.api.models.Workbasket
+   * @param destinationWorkbasketId {@linkplain Workbasket#getId() id} of the target {@linkplain
-   *     Workbasket} id
+   *     Workbasket}
    * @param taskIds list of source {@linkplain Task Tasks} which will be moved
    * @param setTransferFlag the control about whether to set the {@linkplain Task#isTransferred()}
    *     flag or not
-   * @return Bulkresult with ID and Error in it for failed transactions.
+   * @return Bulkresult with {@linkplain Task#getId() ids} and Error in it for failed transactions
    * @throws NotAuthorizedException if the caller has no permissions on target {@linkplain
-   *     pro.taskana.workbasket.api.models.Workbasket Workbasket}.
+   *     Workbasket}
-   * @throws InvalidArgumentException if the method parameters are EMPTY or NULL.
+   * @throws InvalidArgumentException if the method parameters are EMPTY or NULL
-   * @throws WorkbasketNotFoundException if the target {@linkplain
+   * @throws WorkbasketNotFoundException if the target {@linkplain Workbasket} can not be found
-   *     pro.taskana.workbasket.api.models.Workbasket Workbasket} can not be found.
    */
   BulkOperationResults<String, TaskanaException> transferTasks(
       String destinationWorkbasketId, List<String> taskIds, boolean setTransferFlag)
       throws NotAuthorizedException, InvalidArgumentException, WorkbasketNotFoundException;
 
   /**
-   * Transfers a list of {@linkplain Task Tasks} to another {@linkplain
+   * Transfers a list of {@linkplain Task Tasks} to another {@linkplain Workbasket} while always
-   * pro.taskana.workbasket.api.models.Workbasket Workbasket} while always setting the {@linkplain
+   * setting the {@linkplain Task#isTransferred} flag.
-   * Task#isTransferred} flag.
    *
    * @see #transferTasks(String, String, List, boolean)
    */
@@ -403,26 +417,24 @@ public interface TaskService {
   }
 
   /**
-   * Transfers a list of {@linkplain Task Tasks} to another {@linkplain
+   * Transfers a list of {@linkplain Task Tasks} to another {@linkplain Workbasket}.
-   * pro.taskana.workbasket.api.models.Workbasket Workbasket}.
    *
-   * <p>The transfer resets the read flag and sets the transfer flag if {@code setTransferFlag} is
+   * <p>The transfer resets the {@linkplain Task#isRead() read flag} and sets the {@linkplain
-   * {@code true}. Exceptions will be thrown if the caller got no permissions on the target or it
+   * Task#isTransferred() transfer flag} if {@code setTransferFlag} is {@code true}. Exceptions will
-   * does not exist. Other Exceptions will be stored and returned in the end.
+   * be thrown if the caller got no {@linkplain WorkbasketPermission Permission} on the target
+   * {@linkplain Workbasket} or if it does not exist. Other Exceptions will be stored and returned
+   * in the end.
    *
-   * @param destinationWorkbasketKey target {@linkplain pro.taskana.workbasket.api.models.Workbasket
+   * @param destinationWorkbasketKey target {@linkplain Workbasket#getKey()} Workbasket}
-   *     Workbasket} key
+   * @param destinationWorkbasketDomain target {@linkplain Workbasket#getDomain() domain}
-   * @param destinationWorkbasketDomain target {@linkplain
+   * @param taskIds List of source {@linkplain Task Tasks} which will be moved
-   *     pro.taskana.workbasket.api.models.Workbasket Workbasket} domain
-   * @param taskIds list of source {@linkplain Task Tasks} which will be moved
    * @param setTransferFlag the control about whether to set the {@linkplain Task#isTransferred()}
    *     flag or not
-   * @return BulkResult with ID and Error in it for failed transactions.
+   * @return BulkResult with {@linkplain Task#getId() id} and Error in it for failed transactions.
-   * @throws NotAuthorizedException if the caller has no permissions on target {@linkplain
+   * @throws NotAuthorizedException if the caller has no {@linkplain WorkbasketPermission} on target
-   *     pro.taskana.workbasket.api.models.Workbasket Workbasket}.
+   *     {@linkplain Workbasket}.
    * @throws InvalidArgumentException if the method parameters are EMPTY or NULL.
-   * @throws WorkbasketNotFoundException if the target {@linkplain
+   * @throws WorkbasketNotFoundException if the target {@linkplain Workbasket} can not be found.
-   *     pro.taskana.workbasket.api.models.Workbasket Workbasket} can not be found.
    */
   BulkOperationResults<String, TaskanaException> transferTasks(
       String destinationWorkbasketKey,
@@ -432,44 +444,51 @@ public interface TaskService {
       throws NotAuthorizedException, InvalidArgumentException, WorkbasketNotFoundException;
 
   /**
-   * Deletes the task with the given Id.
+   * Deletes the {@linkplain Task} with the given {@linkplain Task#getId() id}.
    *
-   * @param taskId The Id of the task to delete.
+   * @param taskId The {@linkplain Task#getId() id} of the {@linkplain Task} to delete.
-   * @throws TaskNotFoundException If the given Id does not refer to an existing task.
+   * @throws TaskNotFoundException If the given {@linkplain Task#getId() id} does not refer to an
-   * @throws InvalidStateException If the state of the referenced task is not an end state.
+   *     existing {@linkplain Task}.
-   * @throws NotAuthorizedException if the current user is not member of role ADMIN
+   * @throws InvalidStateException If the {@linkplain Task#getState() state} of the referenced
+   *     {@linkplain Task} is not an end state.
+   * @throws NotAuthorizedException if the current user is not member of role {@linkplain
+   *     TaskanaRole#ADMIN}
    */
   void deleteTask(String taskId)
       throws TaskNotFoundException, InvalidStateException, NotAuthorizedException;
 
   /**
-   * Deletes the task with the given Id even if it is not completed.
+   * Deletes the {@linkplain Task} with the given {@linkplain Task#getId() id} even if it is not
+   * completed.
    *
-   * @param taskId The Id of the task to delete.
+   * @param taskId The {@linkplain Task#getId() id} of the {@linkplain Task} to delete.
-   * @throws TaskNotFoundException If the given Id does not refer to an existing task.
+   * @throws TaskNotFoundException If the given {@linkplain Task#getId() id} does not refer to an
-   * @throws InvalidStateException If the state of the referenced task is not an end state and
+   *     existing {@linkplain Task}.
-   *     forceDelete is false.
+   * @throws InvalidStateException If the state of the referenced {@linkplain Task} is not an end
-   * @throws NotAuthorizedException if the current user is not member of role ADMIN
+   *     state and forceDelete is false.
+   * @throws NotAuthorizedException if the current user is not member of role {@linkplain
+   *     TaskanaRole#ADMIN}
    */
   void forceDeleteTask(String taskId)
       throws TaskNotFoundException, InvalidStateException, NotAuthorizedException;
 
   /**
-   * Selects and claims the first task which is returned by the task query.
+   * Selects and claims the first {@linkplain Task} which is returned by the {@linkplain TaskQuery}.
    *
-   * @param taskQuery the task query.
+   * @param taskQuery the {@linkplain TaskQuery}.
-   * @return the task that got selected and claimed
+   * @return the {@linkplain Task} that got selected and claimed
-   * @throws InvalidOwnerException if the task is claimed by someone else
+   * @throws InvalidOwnerException if the {@linkplain Task} is claimed by someone else
-   * @throws NotAuthorizedException if the current user has no read permission for the workbasket
+   * @throws NotAuthorizedException if the current user has no read permission for the Workbasket
-   *     the task is in
+   *     the {@linkplain Task} is in
    */
   Task selectAndClaim(TaskQuery taskQuery) throws NotAuthorizedException, InvalidOwnerException;
 
   /**
-   * Deletes a list of tasks.
+   * Deletes a list of {@linkplain Task Tasks}.
    *
-   * @param tasks the ids of the tasks to delete.
+   * @param tasks the {@linkplain Task#getId() ids} of the tasks to delete.
-   * @return the result of the operations with Id and Exception for each failed task deletion.
+   * @return the result of the operations with each {@linkplain Task#getId() id} and Exception for
+   *     each failed task deletion.
    * @throws InvalidArgumentException if the TaskIds parameter is NULL
    * @throws NotAuthorizedException if the current user is not member of role ADMIN
    */
@@ -477,189 +496,223 @@ public interface TaskService {
       throws InvalidArgumentException, NotAuthorizedException;
 
   /**
-   * Completes a list of tasks.
+   * Completes a list of {@linkplain Task Tasks}.
    *
-   * @param taskIds of the tasks which should be completed.
+   * @param taskIds {@linkplain Task#getId() ids} of the {@linkplain Task Tasks} which should be
-   * @return the result of the operations with Id and Exception for each failed task completion.
+   *     completed
-   * @throws InvalidArgumentException If the taskId parameter is NULL.
+   * @return the result of the operations with each {@linkplain Task#getId() id} and Exception for
+   *     each failed completion
+   * @throws InvalidArgumentException If the taskIds parameter is NULL
    */
   BulkOperationResults<String, TaskanaException> completeTasks(List<String> taskIds)
       throws InvalidArgumentException;
 
   /**
-   * Completes a list of tasks.
+   * Completes each existing {@linkplain Task} in the given List in every case, independent of the
+   * {@linkplain Task#getOwner() owner} or {@linkplain Task#getState() state} of the {@linkplain
+   * Task}. If the {@linkplain Task} is already {@linkplain TaskState#COMPLETED completed}, the
+   * {@linkplain Task} stays unchanged.
    *
    * @see TaskService#forceCompleteTask
-   * @param taskIds of the tasks which should be completed.
+   * @param taskIds {@linkplain Task#getId() id} of the {@linkplain Task Tasks} which should be
-   * @return the result of the operations with Id and Exception for each failed task completion.
+   *     completed
-   * @throws InvalidArgumentException If the taskId parameter is NULL.
+   * @return the result of the operations with {@linkplain Task#getId() id} and Exception for each
+   *     failed completion
+   * @throws InvalidArgumentException If the taskIds parameter is NULL
    */
   BulkOperationResults<String, TaskanaException> forceCompleteTasks(List<String> taskIds)
       throws InvalidArgumentException;
 
   /**
-   * Updates tasks with a matching {@link ObjectReference}.
+   * Updates specified {@linkplain TaskCustomField TaskCustomFields} of {@linkplain Task Tasks}
+   * associated with the given {@linkplain ObjectReference}.
    *
-   * @param selectionCriteria the {@link ObjectReference} that is used to select the tasks.
+   * @param selectionCriteria the {@linkplain ObjectReference} that is used to select the tasks
-   * @param customFieldsToUpdate a {@link Map} that contains as key the identification of the custom
+   * @param customFieldsToUpdate a Map that contains as key the identification of the {@linkplain
-   *     field and as value the corresponding new value of that custom field.
+   *     TaskCustomField} and as value the corresponding new value of that field
-   * @return a list of the Ids of all modified tasks
+   * @return a list of the {@linkplain Task#getId() ids} of all modified {@linkplain Task Tasks}
    * @throws InvalidArgumentException if the given selectionCriteria is invalid or the given
-   *     customFieldsToUpdate are null or empty.
+   *     customFieldsToUpdate are NULL or empty
    */
   List<String> updateTasks(
       ObjectReference selectionCriteria, Map<TaskCustomField, String> customFieldsToUpdate)
       throws InvalidArgumentException;
 
   /**
-   * Updates tasks with matching taskIds.
+   * Updates specified {@linkplain TaskCustomField TaskCustomFields} for all given {@linkplain Task
+   * Tasks}.
    *
-   * @param taskIds the taskIds that are used to select the tasks.
+   * @param taskIds the {@linkplain Task#getId() taskIds} that are used to select the {@linkplain
-   * @param customFieldsToUpdate a {@link Map} that contains as key the identification of the custom
+   *     Task Tasks}.
-   *     field and as value the corresponding new value of that custom field.
+   * @param customFieldsToUpdate a Map that contains as key the identification of the {@linkplain
-   * @return a list of the Ids of all modified tasks
+   *     TaskCustomField} and as value the corresponding new value of that {@linkplain
-   * @throws InvalidArgumentException if the given customFieldsToUpdate are null or empty.
+   *     TaskCustomField}.
+   * @return a list of the {@linkplain Task#getId() ids} of all modified {@linkplain Task Tasks}
+   * @throws InvalidArgumentException if the given customFieldsToUpdate are NULL or empty.
    */
   List<String> updateTasks(List<String> taskIds, Map<TaskCustomField, String> customFieldsToUpdate)
       throws InvalidArgumentException;
 
   /**
-   * Create a task comment.
+   * Inserts the specified {@linkplain TaskComment} into the database.
    *
-   * @param taskComment the task comment to be created.
+   * @param taskComment the {@linkplain TaskComment} to be created
-   * @return the created task comment.
+   * @return the created {@linkplain TaskComment}
-   * @throws NotAuthorizedException If the current user has no authorization to create a task
+   * @throws NotAuthorizedException if the current user has no authorization to create a {@link
-   *     comment for the given taskId in the TaskComment or is not authorized to access the task.
+   *     TaskComment} for the given taskId or is not authorized to access the {@linkplain Task}
-   * @throws TaskNotFoundException If the given taskId in the TaskComment does not refer to an
+   * @throws TaskNotFoundException if the given {@linkplain TaskComment#getTaskId() taskId} does not
-   *     existing task.
+   *     refer to an existing {@linkplain Task}
-   * @throws InvalidArgumentException If the given taskCommentId from the provided task comment is
+   * @throws InvalidArgumentException if the {@linkplain TaskComment#getId() id} of the provided
-   *     not null or empty
+   *     {@link TaskComment} is not NULL or empty
    */
   TaskComment createTaskComment(TaskComment taskComment)
       throws NotAuthorizedException, TaskNotFoundException, InvalidArgumentException;
 
   /**
-   * Update a task comment.
+   * Updates the specified {@linkplain TaskComment}.
    *
-   * @param taskComment the task comment to be updated in the database.
+   * @param taskComment the {@linkplain TaskComment} to be updated in the database
-   * @return the updated task comment.
+   * @return the updated {@linkplain TaskComment}
-   * @throws NotAuthorizedException If the current user has no authorization to update a task
+   * @throws NotAuthorizedException if the current user has no authorization to update the
-   *     comment or is not authorized to access the task.
+   *     {@linkplain TaskComment} or is not authorized to access the {@linkplain Task}
-   * @throws ConcurrencyException if an attempt is made to update the task comment and another user.
+   * @throws ConcurrencyException if an attempt is made to update the {@linkplain TaskComment} and
-   *     updated it already.
+   *     another user updated it already; that's the case if the given {} timestamp differs from the
-   * @throws TaskCommentNotFoundException If the given taskCommentId in the TaskComment does not
+   *     one in the database
-   *     refer to an existing taskComment.
+   * @throws TaskCommentNotFoundException if the {@linkplain TaskComment#getId() is} of the
-   * @throws TaskNotFoundException If the given taskId in the TaskComment does not refer to an
+   *     specified {@linkplain TaskComment}does not refer to an existing {@linkplain TaskComment}
-   *     existing task.
+   * @throws TaskNotFoundException if the {@linkplain TaskComment#getTaskId() taskId} does not refer
-   * @throws InvalidArgumentException If the given taskCommentId from the provided task comment is
+   *     to an existing {@linkplain Task}
-   *     null or empty
+   * @throws InvalidArgumentException if the given {@linkplain TaskComment#getId() id} is NULL or
+   *     empty
    */
   TaskComment updateTaskComment(TaskComment taskComment)
       throws NotAuthorizedException, ConcurrencyException, TaskCommentNotFoundException,
           TaskNotFoundException, InvalidArgumentException;
 
   /**
-   * Deletes the task comment with the given Id.
+   * Deletes the {@linkplain TaskComment} with the given {@linkplain TaskComment#getId() id}.
    *
-   * @param taskCommentId The id of the task comment to delete.
+   * @param taskCommentId the {@linkplain TaskComment#getId() id} of the {@linkplain TaskComment} to
-   * @throws NotAuthorizedException If the current user has no authorization to delete a task
+   *     delete
+   * @throws NotAuthorizedException if the current user has no authorization to delete a task
    *     comment or is not authorized to access the task.
-   * @throws InvalidArgumentException If the taskCommentId is null/empty
+   * @throws InvalidArgumentException if the taskCommentId is NULL or empty
-   * @throws TaskCommentNotFoundException If the given taskCommentId in the TaskComment does not
+   * @throws TaskCommentNotFoundException if the given taskCommentId in the TaskComment does not
    *     refer to an existing taskComment.
-   * @throws TaskNotFoundException If the given taskId in the TaskComment does not refer to an
+   * @throws TaskNotFoundException if the {@linkplain TaskComment#getTaskId() taskId} of the
-   *     existing task.
+   *     TaskComment does not refer to an existing {@linkplain Task}.
-   * @throws InvalidArgumentException If the given taskCommentId is null or empty
+   * @throws InvalidArgumentException if the given taskCommentId is NULL or empty
    */
   void deleteTaskComment(String taskCommentId)
       throws NotAuthorizedException, TaskCommentNotFoundException, TaskNotFoundException,
           InvalidArgumentException;
 
   /**
-   * Retrieves a task comment for a given taskCommentId.
+   * Retrieves the {@linkplain TaskComment} with the given {@linkplain TaskComment#getId() id}.
    *
-   * @param taskCommentId The id of the task comment which should be retrieved
+   * @param taskCommentId the {@linkplain TaskComment#getId() id} of the {@linkplain TaskComment}
-   * @return the task comment identified by taskCommentId
+   *     which should be retrieved
-   * @throws TaskCommentNotFoundException If the given taskCommentId in the TaskComment does not
+   * @return the {@linkplain TaskComment} identified by taskCommentId
-   *     refer to an existing taskComment.
+   * @throws TaskCommentNotFoundException if the given taskCommentId does not refer to an existing
-   * @throws NotAuthorizedException If the current user has no authorization to retrieve a
+   *     {@linkplain TaskComment}
-   *     taskComment from a certain task or is not authorized to access the task.
+   * @throws NotAuthorizedException if the current user has no authorization to retrieve a
-   * @throws TaskNotFoundException If the given taskId in the TaskComment does not refer to an
+   *     {@linkplain TaskComment} from a certain {@linkplain Task} or is not authorized to access
-   *     existing task.
+   *     the {@linkplain Task}
-   * @throws InvalidArgumentException If the given taskCommentId is null or empty
+   * @throws TaskNotFoundException if the {@linkplain TaskComment#getTaskId() taskId} of the
+   *     TaskComment does not refer to an existing {@linkplain Task}
+   * @throws InvalidArgumentException if the given taskCommentId is NULL or empty
    */
   TaskComment getTaskComment(String taskCommentId)
       throws TaskCommentNotFoundException, NotAuthorizedException, TaskNotFoundException,
           InvalidArgumentException;
 
   /**
-   * Retrieves a list of task comments for a given taskId.
+   * Retrieves the List of {@linkplain TaskComment TaskComments} for the Task with given {@linkplain
+   * Task#getId() id}.
    *
-   * @param taskId The id of the task for which all task comments should be retrieved
+   * @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} for which all task
-   * @return the list of task comments attached to task with id taskId
+   *     comments should be retrieved
-   * @throws NotAuthorizedException If the current user has no authorization to retrieve a
+   * @return the List of task comments attached to the specified {@linkplain Task}
-   *     taskComment from a certain task or is not authorized to access the task.
+   * @throws NotAuthorizedException if the current user has no authorization to retrieve a
-   * @throws TaskNotFoundException If the given taskId in the TaskComment does not refer to an
+   *     taskComment from the {@linkplain Task} or is not authorized to access the {@linkplain Task}
-   *     existing task.
+   * @throws TaskNotFoundException if the given taskId does not refer to an existing {@linkplain
+   *     Task}
    */
   List<TaskComment> getTaskComments(String taskId)
       throws NotAuthorizedException, TaskNotFoundException;
 
   /**
-   * Sets the callback state on a list of tasks. Note: this method is primarily intended to be used
+   * Sets the specified {@linkplain CallbackState} on a list of {@linkplain Task Tasks}. Note: this
-   * by the TaskanaAdapter
+   * method is primarily intended to be used by the TaskanaAdapter
    *
-   * @param externalIds the EXTERNAL_IDs of the tasks on which the callback state is set.
+   * @param externalIds the {@linkplain Task#getExternalId() externalIds} of the {@linkplain Task
-   * @param state the callback state that is to be set on the tasks
+   *     Tasks} on which the {@linkplain CallbackState} is set
-   * @return the result of the operations with Id and Exception for each failed task deletion.
+   * @param state the {@linkplain CallbackState} that is to be set on the {@linkplain Task Tasks}
+   * @return the result of the operations with {@linkplain Task#getId() id} and Exception for each
+   *     failed operation
    */
   BulkOperationResults<String, TaskanaException> setCallbackStateForTasks(
       List<String> externalIds, CallbackState state);
 
   /**
-   * Sets the owner on a list of tasks. The owner will only be set on tasks that are in state READY.
+   * Sets the {@linkplain Task#getOwner() owner} on a List of {@linkplain Task Tasks}. The
+   * {@linkplain Task#getOwner() owner} will only be set on {@linkplain Task Tasks} that are in
+   * state {@linkplain TaskState#READY}.
    *
-   * @param owner the new owner of the tasks
+   * @param owner the new {@linkplain Task#getOwner() owner} of the {@linkplain Task Tasks}
-   * @param taskIds the IDs of the tasks on which the owner is to be set.
+   * @param taskIds the {@linkplain Task#getId() ids} of the {@linkplain Task Tasks} on which the
-   * @return the result of the operations with Id and Exception for each failed task update.
+   *     {@linkplain Task#getOwner() owner} is to be set
+   * @return the result of the operations with {@linkplain Task#getId() id} and Exception for each
+   *     failed {@linkplain Task}-update
    */
   BulkOperationResults<String, TaskanaException> setOwnerOfTasks(
       String owner, List<String> taskIds);
 
   /**
-   * Sets the planned property on a list of tasks. Only tasks in state READY and CLAIMED will be
+   * Sets the {@linkplain Task#getPlanned() planned} Instant on a List of {@linkplain Task Tasks}.
-   * affected by this method. On each task, the corresponding due date is set according to the
+   * Only {@linkplain Task Tasks} in state {@linkplain TaskState#READY} and {@linkplain
-   * shortest service level in the classifications of the task and the task's attachments.
+   * TaskState#CLAIMED} will be affected by this method. On each {@linkplain Task}, the
+   * corresponding {@linkplain Task#getDue() due date} is set according to the shortest serviceLevel
+   * in the {@linkplain Task#getClassificationSummary() Classification} of the {@linkplain Task} and
+   * its {@linkplain Task#getAttachments() Attachments}.
    *
-   * @param planned the new 'PLANNED" property of the tasks
+   * @param planned the new {@linkplain Task#getPlanned() planned} Instant of the {@linkplain Task
-   * @param taskIds the IDs of the tasks on which the new planned property is to be set.
+   *     Tasks}
-   * @return the result of the operations with Id and Exception for each failed task update.
+   * @param taskIds the {@linkplain Task#getId() ids} of the {@linkplain Task Tasks} on which the
+   *     new {@linkplain Task#getPlanned() planned} Instant is to be set
+   * @return the result of the operations with {@linkplain Task#getId() id} and Exception for each
+   *     failed {@linkplain Task Task} update.
    */
   BulkOperationResults<String, TaskanaException> setPlannedPropertyOfTasks(
       Instant planned, List<String> taskIds);
 
   /**
-   * Cancels a task. Cancellation means a task is obsolete from a business perspective an does not
+   * Cancels the {@linkplain Task} with the given {@linkplain Task#getId() id}. Cancellation means a
-   * need to be completed anymore.
+   * {@linkplain Task} is obsolete from a business perspective and does not need to be completed
+   * anymore.
    *
-   * @param taskId the id of the task to cancel.
+   * @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} to cancel
-   * @return the updated task.
+   * @return the updated {@linkplain Task}
-   * @throws TaskNotFoundException if the Task with Id TaskId is not found
+   * @throws TaskNotFoundException if the {@linkplain Task} with taskId is not found
-   * @throws InvalidStateException if the task is not in state READY or CLAIMED
+   * @throws InvalidStateException if the {@linkplain Task} is not in state {@linkplain
-   * @throws NotAuthorizedException if the current user is not authorized to see the task
+   *     TaskState#READY} or {@linkplain TaskState#CLAIMED}
+   * @throws NotAuthorizedException if the current user is not authorized to see the {@linkplain
+   *     Task}
    */
   Task cancelTask(String taskId)
       throws TaskNotFoundException, InvalidStateException, NotAuthorizedException;
 
   /**
-   * Terminates a task. Termination is a administrative action to complete a task. This is typically
+   * Terminates a {@linkplain Task}. Termination is an administrative action to complete a
-   * done by an administration to correct any technical issue.
+   * {@linkplain Task}. This is typically done by administration to correct any technical issue.
    *
-   * @param taskId the id of the task to cancel.
+   * @param taskId the id of the {@linkplain Task} to cancel
-   * @return the updated task.
+   * @return the updated {@linkplain Task}
-   * @throws TaskNotFoundException if the Task with Id TaskId is not found
+   * @throws TaskNotFoundException if the {@linkplain Task} with taskId is not found
-   * @throws InvalidStateException if the task is not in state READY or CLAIMED
+   * @throws InvalidStateException if the {@linkplain Task} is not in state {@linkplain
-   * @throws NotAuthorizedException if the current user is not authorized to see the task
+   *     TaskState#READY} or {@linkplain TaskState#CLAIMED}
+   * @throws NotAuthorizedException if the current user is not authorized to see the {@linkplain
+   *     Task}
    */
   Task terminateTask(String taskId)
       throws TaskNotFoundException, InvalidStateException, NotAuthorizedException;

lib/taskana-core/src/main/java/pro/taskana/task/api/models/Attachment.java

@@ -5,56 +5,57 @@ import java.util.Map;
 
 import pro.taskana.classification.api.models.ClassificationSummary;
 
-/** Attachment-Interface to specify Attachment Attributes. */
+/** Attachment-Interface to specify attributes of an Attachment. */
 public interface Attachment extends AttachmentSummary {
 
   /**
-   * Sets the {@link ObjectReference primaryObjectReference} of the attachment.
+   * Sets the {@linkplain ObjectReference primaryObjectReference} of the Attachment.
    *
-   * @param objectReference the {@link ObjectReference primaryObjectReference} of the attachment
+   * @param objectReference the {@linkplain ObjectReference primaryObjectReference} of the
+   *     Attachment
    */
   void setObjectReference(ObjectReference objectReference);
 
   /**
-   * Set the classification summary for this attachment.
+   * Set the {@linkplain ClassificationSummary classificationSummary} for this Attachment.
    *
-   * @param classificationSummary the {@link ClassificationSummary} for this attachment
+   * @param classificationSummary the {@linkplain ClassificationSummary} for this Attachment
    */
   void setClassificationSummary(ClassificationSummary classificationSummary);
 
   /**
-   * Sets the time when the attachment was received.
+   * Sets the time when the Attachment was received.
    *
-   * @param received the time as {@link Instant} when the attachment was received
+   * @param received the time when the Attachment was received as Instant
    */
   void setReceived(Instant received);
 
   /**
-   * Sets the Channel on which the attachment was received.
+   * Sets the channel on which the Attachment was received.
    *
-   * @param channel the channel on which the attachment was received
+   * @param channel the channel on which the Attachment was received
    */
   void setChannel(String channel);
 
   /**
-   * Returns the custom attributes of this attachment.
+   * Returns the custom attributes of this Attachment.
    *
-   * @return customAttributes as {@link Map}
+   * @return customAttributes as {@linkplain Map}
    */
   Map<String, String> getCustomAttributeMap();
 
   /**
-   * Sets the custom attribute Map of the attachment.
+   * Sets the custom attribute Map of the Attachment.
    *
-   * @param customAttributes a {@link Map} that contains the custom attributes of the attachment as
+   * @param customAttributes a {@linkplain Map} that contains the custom attributes of the
-   *     key, value pairs
+   *     Attachment as key, value pairs
    */
   void setCustomAttributeMap(Map<String, String> customAttributes);
 
   /**
-   * Return a summary of the current Attachment.
+   * Returns a summary of the current Attachment.
    *
-   * @return the AttachmentSummary object for the current attachment
+   * @return the {@linkplain AttachmentSummary} object for the current Attachment
    */
   AttachmentSummary asSummary();
 

lib/taskana-core/src/main/java/pro/taskana/task/api/models/AttachmentSummary.java

@@ -11,58 +11,59 @@ import pro.taskana.classification.api.models.ClassificationSummary;
 public interface AttachmentSummary {
 
   /**
-   * Gets the id of the attachment.
+   * Returns the id of the {@linkplain Attachment}.
    *
    * @return attachmentId
    */
   String getId();
 
   /**
-   * Gets the id of the associated task.
+   * Returns the id of the associated {@linkplain Task}.
    *
    * @return taskId
    */
   String getTaskId();
 
   /**
-   * Gets the time when the attachment was created.
+   * Returns the time when the {@linkplain Attachment} was created.
    *
    * @return the created Instant
    */
   Instant getCreated();
 
   /**
-   * Gets the time when the attachment was last modified.
+   * Returns the time when the {@linkplain Attachment} was last modified.
    *
    * @return the last modified Instant
    */
   Instant getModified();
 
   /**
-   * Gets the {@link ObjectReference primaryObjectReference} of the attachment.
+   * Returns the {@linkplain ObjectReference primaryObjectReference} of the {@linkplain Attachment}.
    *
-   * @return {@link ObjectReference primaryObjectReference} of the attachment
+   * @return {@linkplain ObjectReference primaryObjectReference} of the {@linkplain Attachment}
    */
   ObjectReference getObjectReference();
 
   /**
-   * Gets the Channel on which the attachment was received.
+   * Returns the channel on which the {@linkplain Attachment} was received.
    *
    * @return the channel
    */
   String getChannel();
 
   /**
-   * Gets the classificationSummary of the attachment.
+   * Returns the {@linkplain ClassificationSummary classificationSummary} of the {@linkplain
+   * Attachment}.
    *
-   * @return the classification summary
+   * @return {@linkplain ClassificationSummary classificationSummary}
    */
   ClassificationSummary getClassificationSummary();
 
   /**
-   * Gets the time when the attachment was received.
+   * Returns the time when the {@linkplain Attachment} was received.
    *
-   * @return received Instant
+   * @return the received Instant
    */
   Instant getReceived();
 

lib/taskana-core/src/main/java/pro/taskana/task/api/models/ObjectReference.java

@@ -4,37 +4,37 @@ package pro.taskana.task.api.models;
 public interface ObjectReference {
 
   /**
-   * Gets the id of the ObjectReference.
+   * Returns the id of the ObjectReference.
    *
    * @return the id of the ObjectReference.
    */
   String getId();
 
   /**
-   * Gets the id of the associated task.
+   * Returns the id of the associated {@linkplain Task}.
    *
-   * @return the taskId
+   * @return taskId
    */
   String getTaskId();
 
   /**
-   * Gets the company of the ObjectReference.
+   * Returns the company of the ObjectReference.
    *
-   * @return the company
+   * @return company
    */
   String getCompany();
 
   /**
    * Sets the company of the ObjectReference.
    *
-   * @param company the company of the object reference
+   * @param company the company of the ObjectReference
    */
   void setCompany(String company);
 
   /**
-   * Gets the system of the ObjectReference.
+   * Returns the system of the ObjectReference.
    *
-   * @return the system
+   * @return system
    */
   String getSystem();
 
@@ -46,23 +46,23 @@ public interface ObjectReference {
   void setSystem(String system);
 
   /**
-   * Gets the systemInstance of the ObjectReference.
+   * Returns the systemInstance of the ObjectReference.
    *
-   * @return the systemInstance
+   * @return systemInstance
    */
   String getSystemInstance();
 
   /**
    * Sets the system instance of the ObjectReference.
    *
-   * @param systemInstance the system instance of the ObjectReference
+   * @param systemInstance the systemInstance of the ObjectReference
    */
   void setSystemInstance(String systemInstance);
 
   /**
-   * Gets the type of the ObjectReference.
+   * Returns the type of the ObjectReference.
    *
-   * @return the type
+   * @return type
    */
   String getType();
 
@@ -74,9 +74,9 @@ public interface ObjectReference {
   void setType(String type);
 
   /**
-   * Gets the value of the ObjectReference.
+   * Returns the value of the ObjectReference.
    *
-   * @return the value
+   * @return value
    */
   String getValue();
 

lib/taskana-core/src/main/java/pro/taskana/task/api/models/Task.java

@@ -7,8 +7,10 @@ import java.util.Map;
 import pro.taskana.classification.api.models.Classification;
 import pro.taskana.task.api.TaskCustomField;
 import pro.taskana.task.api.TaskService;
+import pro.taskana.user.api.models.User;
+import pro.taskana.workbasket.api.models.WorkbasketSummary;
 
-/** task-Interface to specify attribute interactions. */
+/** Task-Interface to specify the model of a Task. */
 public interface Task extends TaskSummary {
 
   /**
@@ -25,28 +27,28 @@ public interface Task extends TaskSummary {
    * externalId can only be set before the Task is inserted. Taskana rejects attempts to modify
    * externalId.
    *
-   * @param externalId the external Id
+   * @param externalId the externalId
    */
   void setExternalId(String externalId);
 
   /**
    * Sets the time when the work on this Task should be started.
    *
-   * @param planned as exact {@link Instant}
+   * @param planned as exact {@linkplain Instant}
    */
   void setPlanned(Instant planned);
 
   /**
-   * Sets the time when when the surrounding process started.
+   * Sets the time when the surrounding process started.
    *
-   * @param received as exact {@link Instant}
+   * @param received as exact {@linkplain Instant}
    */
   void setReceived(Instant received);
 
   /**
    * Sets the time when the work on this Task should be finished.
    *
-   * @param due as exact {@link Instant}
+   * @param due as exact {@linkplain Instant}
    */
   void setDue(Instant due);
 
@@ -65,10 +67,13 @@ public interface Task extends TaskSummary {
   void setDescription(String description);
 
   /**
-   * Sets the Classification key that - together with the Domain from this Task's work basket -
+   * Sets the {@linkplain Classification#getKey() key} of the {@linkplain Classification} that -
-   * selects the appropriate {@link Classification} for this Task.
+   * together with the {@linkplain WorkbasketSummary#getDomain() domain} from the {@linkplain
+   * pro.taskana.workbasket.api.models.Workbasket Workbasket} of the Task - selects the appropriate
+   * {@linkplain Classification} for this Task.
    *
-   * @param classificationKey the classification key for the Task
+   * @param classificationKey the {@linkplain Classification#getKey() key} of the {@linkplain
+   *     Classification} for the Task
    */
   void setClassificationKey(String classificationKey);
 
@@ -82,110 +87,113 @@ public interface Task extends TaskSummary {
   void setManualPriority(int manualPriority);
 
   /**
-   * Returns the key of the Workbasket where the Task is stored in.
+   * Returns the {@linkplain WorkbasketSummary#getKey() key} of the {@linkplain
+   * pro.taskana.workbasket.api.models.Workbasket Workbasket} where the Task is stored in.
    *
    * @return workbasketKey
    */
   String getWorkbasketKey();
 
   /**
-   * Returns a Map of custom Attributes.
+   * Returns a Map of customAttributes.
    *
-   * @return customAttributes as {@link Map}
+   * @return customAttributes as Map
    */
   Map<String, String> getCustomAttributeMap();
 
   /**
-   * Sets a Map of custom Attributes.
+   * Sets a Map of custom attributes.
    *
-   * @param customAttributes a {@link Map} that contains the custom attributes
+   * @param customAttributes a Map that contains the custom attributes
    */
   void setCustomAttributeMap(Map<String, String> customAttributes);
 
   /**
-   * Returns a Map of Callback info.
+   * Returns the callbackInfo.
    *
-   * @return callbackInfo as {@link Map}
+   * @return callbackInfo as Map
    */
   Map<String, String> getCallbackInfo();
 
   /**
-   * Sets a Map of callback info.
+   * Sets the callbackInfo.
    *
-   * @param callbackInfo a {@link Map} that contains the callback info
+   * @param callbackInfo a {@linkplain Map} that contains the callback information
    */
   void setCallbackInfo(Map<String, String> callbackInfo);
 
   /**
-   * Sets the value for custom Attribute.
+   * Sets the value for the specified {@linkplain TaskCustomField customField}.
    *
-   * @param customField identifies which custom attribute is to be set.
+   * @param customField identifies which {@linkplain TaskCustomField customField} is to be set
-   * @param value the value of the custom attribute to be set
+   * @param value the value of the {@linkplain TaskCustomField customField} to be set
-   * @deprecated Use {@link #setCustomField(TaskCustomField, String)} instead
+   * @deprecated Use {@linkplain #setCustomField(TaskCustomField, String)} instead
    */
   void setCustomAttribute(TaskCustomField customField, String value);
 
   /**
-   * Sets the value for custom field.
+   * Sets the value for the specified {@linkplain TaskCustomField customField}.
    *
-   * @param customField identifies which custom field is to be set.
+   * @param customField identifies which {@linkplain TaskCustomField customField} is to be set.
-   * @param value the value of the custom field to be set
+   * @param value the value of the {@linkplain TaskCustomField customField} to be set
    */
   void setCustomField(TaskCustomField customField, String value);
 
   /**
-   * Add an attachment.<br>
+   * Add an {@linkplain Attachment}.<br>
-   * NULL will be ignored and an attachment with the same ID will be replaced by the newer one.<br>
+   * NULL will be ignored and an {@linkplain Attachment} with the same id will be replaced by the
+   * newer one.<br>
    *
-   * @param attachment the {@link Attachment attachment} to be added to the Task
+   * @param attachment the {@linkplain Attachment attachment} to be added to the Task
    */
   void addAttachment(Attachment attachment);
 
   /**
-   * Return the attachments for this Task. <br>
+   * Return the {@linkplain Attachment attachment} for the Task. <br>
-   * Do not use List.add()/addAll() for adding Elements, because it can cause redundant data. Use
+   * Do not use List.add()/addAll() for adding elements, because it can cause redundant data. Use
    * addAttachment(). Clear() and remove() can be used, because it's a controllable change.
    *
-   * @return the {@link List list} of {@link Attachment attachments} for this Task
+   * @return the List of {@linkplain Attachment attachments} for this Task
    */
   List<Attachment> getAttachments();
 
   /**
-   * Sets the external business process id.
+   * Sets the associated businessProcessId.
    *
-   * @param businessProcessId Sets the business process id the Task belongs to.
+   * @param businessProcessId Sets the businessProcessId the Task belongs to.
    */
   void setBusinessProcessId(String businessProcessId);
 
   /**
-   * Sets the parent business process id to group associated processes.
+   * Sets the parentBusinessProcessId. ParentBusinessProcessId is needed to group associated
+   * processes and to identify the main process.
    *
-   * @param parentBusinessProcessId Sets the parent business process id the Task belongs to
+   * @param parentBusinessProcessId the business process id of the parent the Task belongs to
    */
   void setParentBusinessProcessId(String parentBusinessProcessId);
 
   /**
-   * Sets the ownerId of this Task.
+   * Sets the id of the owner of the Task.
    *
-   * @param taskOwnerId the user id of the Task's owner
+   * @param taskOwnerId the {@linkplain User#getId() id} of the owner of the Task
    */
   void setOwner(String taskOwnerId);
 
   /**
-   * Sets the {@link ObjectReference primaryObjectReference} of the Task.
+   * Sets the {@linkplain ObjectReference primaryObjectReference} of the Task.
    *
    * @param primaryObjRef to Task main-subject
    */
   void setPrimaryObjRef(ObjectReference primaryObjRef);
 
   /**
-   * Initializes and sets the {@link ObjectReference primaryObjectReference} of the Task.
+   * Initializes and sets the {@linkplain ObjectReference primaryObjectReference} of the Task.
    *
-   * @param company of the {@link ObjectReference primaryObjectReference} to be set
+   * @param company of the {@linkplain ObjectReference primaryObjectReference} to be set
-   * @param system of the {@link ObjectReference primaryObjectReference} to be set
+   * @param system of the {@linkplain ObjectReference primaryObjectReference} to be set
-   * @param systemInstance of the {@link ObjectReference primaryObjectReference} to be set
+   * @param systemInstance of the {@linkplain ObjectReference primaryObjectReference} to be set
-   * @param type of the {@link ObjectReference primaryObjectReference} to be set
+   * @param type of the {@linkplain ObjectReference primaryObjectReference} to be set
-   * @param value of the {@link ObjectReference primaryObjectReference} to be set
+   * @param value of the {@linkplain ObjectReference primaryObjectReference} to be set
    */
   void setPrimaryObjRef(
       String company, String system, String systemInstance, String type, String value);
@@ -198,33 +206,34 @@ public interface Task extends TaskSummary {
   void setNote(String note);
 
   /**
-   * Return a summary of the current Task.
+   * Returns a summary of the current Task.
    *
-   * @return the TaskSummary object for the current Task
+   * @return the {@linkplain TaskSummary} object for the current Task
    */
   TaskSummary asSummary();
 
   /**
-   * Removes an attachment of the current Task locally, when the ID is represented and does return
+   * Removes an {@linkplain Attachment attachment} of the current Task locally, when the ID is
-   * the removed attachment or null if there was no match.<br>
+   * represented and does return the removed {@linkplain Attachment attachment} or null if there was
-   * The changed Task need to be updated calling the {@link TaskService#updateTask(Task)}.
+   * no match.<br>
+   * The changed Task need to be updated calling the {@linkplain TaskService#updateTask(Task)}.
    *
-   * @param attachmentID ID of the attachment which should be removed.
+   * @param attachmentID ID of the {@linkplain Attachment attachment} which should be removed.
-   * @return attachment which will be removed after updating OR null if there was no matching
+   * @return {@linkplain Attachment attachment} which will be removed after updating OR null if
-   *     attachment
+   *     there was no match.
    */
   Attachment removeAttachment(String attachmentID);
 
   /**
-   * Returns the category of the current classification.
+   * Returns the category of the current {@linkplain Classification}.
    *
    * @return classificationCategory
    */
   String getClassificationCategory();
 
   /**
-   * Duplicates this Task without the internal and external id. All referenced {@link Attachment}s
+   * Duplicates this Task without the internal and external id. All referenced {@linkplain
-   * and {@link ObjectReference}s are copied as well.
+   * Attachment}s and {@linkplain ObjectReference}s are copied as well.
    *
    * @return a copy of this Task
    */

lib/taskana-core/src/main/java/pro/taskana/task/api/models/TaskComment.java

@@ -2,60 +2,60 @@ package pro.taskana.task.api.models;
 
 import java.time.Instant;
 
-/** TaskComment-Interface to specify TaskComment Attributes. */
+/** TaskComment-Interface to specify attributes of the TaskComment. */
 public interface TaskComment {
 
   /**
-   * Gets the id of the task comment.
+   * Returns the id of the TaskComment.
    *
    * @return taskId
    */
   String getId();
 
   /**
-   * Gets the id of the associated task.
+   * Returns the id of the associated Task.
    *
    * @return taskId
    */
   String getTaskId();
 
   /**
-   * Gets the name of the task comment-creator.
+   * Returns the id of the creator of the TaskComment.
    *
    * @return creator
    */
   String getCreator();
 
   /**
-   * Gets the long name of the task comment creator.
+   * Returns the long name of the creator of the TaskComment.
    *
-   * @return the long Name of the creator
+   * @return the long name of the creator
    */
   String getCreatorFullName();
 
   /**
-   * Gets the text field of the task comment.
+   * Returns the content of the TaskComment.
    *
    * @return textField
    */
   String getTextField();
 
   /**
-   * Sets the text field of the task comment.
+   * Sets the content of the TaskComment.
    *
-   * @param textField the text field
+   * @param textField the textField
    */
   void setTextField(String textField);
 
   /**
-   * Gets the time when the task comment was created.
+   * Returns the time when the TaskComment was created.
    *
    * @return the created Instant
    */
   Instant getCreated();
 
   /**
-   * Gets the time when the task comment was last modified.
+   * Returns the time when the TaskComment was last modified.
    *
    * @return the last modified Instant
    */

lib/taskana-core/src/main/java/pro/taskana/task/api/models/TaskSummary.java

@@ -16,261 +16,265 @@ import pro.taskana.workbasket.api.models.WorkbasketSummary;
 public interface TaskSummary {
 
   /**
-   * Gets the id of the Task.
+   * Returns the id of the {@linkplain Task}.
    *
    * @return taskId
    */
   String getId();
 
   /**
-   * Gets the external id of the Task.
+   * Returns the externalId of the {@linkplain Task}.
    *
-   * @return the external Id
+   * @return externalId
    */
   String getExternalId();
 
   /**
-   * Gets the name of the creator of the Task.
+   * Returns the name of the creator of the {@linkplain Task}.
    *
    * @return creator
    */
   String getCreator();
 
   /**
-   * Gets the time when the task was created.
+   * Returns the time when the {@linkplain Task} was created.
    *
-   * @return the created {@link Instant}
+   * @return the created Instant
    */
   Instant getCreated();
 
   /**
-   * Gets the time when the Task was claimed.
+   * Returns the time when the {@linkplain Task} was claimed.
    *
-   * @return the claimed {@link Instant}
+   * @return the claimed Instant
    */
   Instant getClaimed();
 
   /**
-   * Gets the time when the Task was completed.
+   * Returns the time when the {@linkplain Task} was completed.
    *
-   * @return the completed {@link Instant}
+   * @return the completed Instant
    */
   Instant getCompleted();
 
   /**
-   * Gets the time when the Task was last modified.
+   * Returns the time when the {@linkplain Task} was last modified.
    *
-   * @return the last modified {@link Instant}
+   * @return the last modified Instant
    */
   Instant getModified();
 
   /**
-   * Gets the time when the Task is planned to be executed.
+   * Returns the time when the {@linkplain Task} is planned to be executed.
    *
-   * @return the planned {@link Instant}
+   * @return the planned Instant
    */
   Instant getPlanned();
 
   /**
-   * Gets the time when the surrounding process was started.
+   * Returns the time when the surrounding process was started.
    *
-   * @return the received {@link Instant}
+   * @return the received Instant
    */
   Instant getReceived();
 
   /**
-   * Gets the time when the Task is due.
+   * Returns the time when the {@linkplain Task} is due.
    *
-   * @return the due {@link Instant}
+   * @return the due Instant
    */
   Instant getDue();
 
   /**
-   * Gets the name of the Task.
+   * Returns the name of the {@linkplain Task}.
    *
-   * @return the Task's name
+   * @return name
    */
   String getName();
 
   /**
-   * Gets the note attached to the Task.
+   * Returns the note attached to the {@linkplain Task}.
    *
-   * @return the Task's note
+   * @return note
    */
   String getNote();
 
   /**
-   * Gets the description of the Task.
+   * Returns the description of the {@linkplain Task}.
    *
-   * @return the Task's description
+   * @return description
    */
   String getDescription();
 
   /**
-   * Gets the priority of the Task.
+   * Returns the priority of the {@linkplain Task}.
    *
-   * @return the Task's priority
+   * @return priority
    */
   int getPriority();
 
   /**
-   * Gets the manualPriority of the Task. If the value of manualPriority is zero or greater, the
+   * Gets the manualPriority of the {@linkplain Task}. If the value of manualPriority is zero or
-   * priority is automatically set to manualPriority. In this case, all computations of priority are
+   * greater, the priority is automatically set to manualPriority. In this case, all computations of
-   * disabled. If the value of manualPriority is negative, Tasks are not prioritized manually.
+   * priority are disabled. If the value of manualPriority is negative, Tasks are not prioritized
+   * manually.
    *
    * @return the manualPriority of the Task
    */
   int getManualPriority();
 
   /**
-   * Gets the state of the Task.
+   * Returns the state of the {@linkplain Task}.
    *
-   * @return the Task's state
+   * @return state
    */
   TaskState getState();
 
   /**
-   * Gets the {@link ClassificationSummary} of the Task.
+   * Returns the {@linkplain ClassificationSummary} of the {@linkplain Task}.
    *
-   * @return the Task's {@link ClassificationSummary}
+   * @return {@linkplain ClassificationSummary}
    */
   ClassificationSummary getClassificationSummary();
 
   /**
-   * Gets the {@link WorkbasketSummary} of the Task.
+   * Returns the {@linkplain WorkbasketSummary} of the {@linkplain Task}.
    *
-   * @return the Task's {@link WorkbasketSummary}
+   * @return {@linkplain WorkbasketSummary}
    */
   WorkbasketSummary getWorkbasketSummary();
 
   /**
-   * Gets the {@link AttachmentSummary attachmentSummaries} of the Task.
+   * Returns the {@linkplain AttachmentSummary attachmentSummaries} of the {@linkplain Task}.
    *
-   * @return the Task's {@link AttachmentSummary attachmentSummaries}
+   * @return {@linkplain AttachmentSummary attachmentSummaries}
    */
   List<AttachmentSummary> getAttachmentSummaries();
 
   /**
-   * Gets the secondary {@link ObjectReference}s of the Task.
+   * Returns the {@linkplain ObjectReference secondaryObjectReferences} of the {@linkplain Task}.
    *
-   * @return the Task's secondary {@link ObjectReference}s
+   * @return {@linkplain ObjectReference secondaryObjectReferences}
    */
   List<ObjectReference> getSecondaryObjectReferences();
 
   /**
-   * Add an {@link ObjectReference} to the list of secondary {@link ObjectReference}s.<br>
+   * Add an {@linkplain ObjectReference} to the List of secondary {@linkplain ObjectReference
-   * NULL will be ignored and an ObjectReference with the same ID will be replaced by the newer one.
+   * objectReferences}.<br>
-   * <br>
+   * NULL will be ignored and an {@linkplain ObjectReference} with the same {@linkplain
+   * ObjectReference#getId() id} will be replaced by the newer one. <br>
    *
-   * @param objectReference the secondary {@link ObjectReference objectReference} to be added to the
+   * @param objectReference the secondary {@linkplain ObjectReference objectReference} to be added
-   *     Task
+   *     to the {@linkplain Task}
    */
   void addSecondaryObjectReference(ObjectReference objectReference);
 
   /**
-   * Add an {@link ObjectReference} to the list of secondary {@link ObjectReference}s.<br>
+   * Add an {@linkplain ObjectReference} to the List of secondary {@linkplain ObjectReference}s.<br>
-   * NULL will be ignored and an ObjectReference with the same ID will be replaced by the newer one.
+   * NULL will be ignored and an ObjectReference with the same {@linkplain ObjectReference#getId()
-   * <br>
+   * id} will be replaced by the newer one. <br>
    *
-   * @param company of the {@link ObjectReference objectReference} to be added to the Task
+   * @param company of the {@linkplain ObjectReference objectReference} to be added to the Task
-   * @param system of the {@link ObjectReference objectReference} to be added to the Task
+   * @param system of the {@linkplain ObjectReference objectReference} to be added to the Task
-   * @param systemInstance of the {@link ObjectReference objectReference} to be added to the Task
+   * @param systemInstance of the {@linkplain ObjectReference objectReference} to be added to the
-   * @param type of the {@link ObjectReference objectReference} to be added to the Task
+   *     Task
-   * @param value of the {@link ObjectReference objectReference} to be added to the Task
+   * @param type of the {@linkplain ObjectReference objectReference} to be added to the Task
+   * @param value of the {@linkplain ObjectReference objectReference} to be added to the Task
    */
   void addSecondaryObjectReference(
       String company, String system, String systemInstance, String type, String value);
 
   /**
-   * Removes a secondary {@link ObjectReference} of the current Task locally, when the ID is
+   * Removes a secondary {@linkplain ObjectReference} of the current Task locally, when the ID is
-   * represented and does return the removed {@link ObjectReference} or null if there was no match.
+   * represented and does return the removed {@linkplain ObjectReference} or null if there was no
-   * <br>
+   * match. <br>
-   * The changed Task need to be updated calling the {@link TaskService#updateTask(Task)}.
+   * The changed Task need to be updated calling the {@linkplain TaskService#updateTask(Task)}.
    *
-   * @param objectReferenceID ID of the {@link ObjectReference} which should be removed.
+   * @param objectReferenceID {@linkplain ObjectReference#getId() id} of the {@linkplain
-   * @return the {@link ObjectReference} which will be removed after updating OR null if there was
+   *     ObjectReference} which should be removed
-   *     no matching {@link ObjectReference}
+   * @return the {@linkplain ObjectReference} which will be removed after updating or null if there
+   *     was no matching {@linkplain ObjectReference}
    */
   ObjectReference removeSecondaryObjectReference(String objectReferenceID);
 
   /**
-   * Gets the domain of the Task.
+   * Returns the domain of the {@linkplain Task}.
    *
-   * @return the Task's domain
+   * @return domain
    */
   String getDomain();
 
   /**
-   * Gets the businessProcessId of the Task.
+   * Returns the businessProcessId of the {@linkplain Task}.
    *
-   * @return the Task's businessProcessId
+   * @return businessProcessId
    */
   String getBusinessProcessId();
 
   /**
-   * Gets the parentBusinessProcessId of the Task.
+   * Returns the parentBusinessProcessId of the {@linkplain Task}.
    *
-   * @return the Task's parentBusinessProcessId
+   * @return parentBusinessProcessId
    */
   String getParentBusinessProcessId();
 
   /**
-   * Gets the owner of the Task.
+   * Returns the owner of the {@linkplain Task}.
    *
-   * @return the Task's owner
+   * @return owner
    */
   String getOwner();
 
   /**
-   * Gets the owner's long name of the Task.
+   * Returns long name of the owner of the {@linkplain Task}.
    *
-   * @return the long name of the Task owner
+   * @return the long name of the owner
    */
   String getOwnerLongName();
 
   /**
-   * Gets the primary {@link ObjectReference} of the Task.
+   * Returns the primary {@linkplain ObjectReference} of the {@linkplain Task}.
    *
-   * @return the Task's primary {@link ObjectReference}
+   * @return the Tasks primary {@linkplain ObjectReference}
    */
   ObjectReference getPrimaryObjRef();
 
   /**
-   * Gets the isRead flag of the Task.
+   * Returns the isRead flag of the {@linkplain Task}.
    *
-   * @return the Task's isRead flag
+   * @return the Tasks isRead flag
    */
   boolean isRead();
 
   /**
-   * Gets the isTransferred flag of the Task.
+   * Returns the isTransferred flag of the {@linkplain Task}.
    *
-   * @return the Task's isTransferred flag.
+   * @return the Tasks isTransferred flag
    */
   boolean isTransferred();
 
   /**
-   * Returns whether the Task is prioritized manually. That means that the priority is set to the
+   * Returns whether the {@linkplain Task} is prioritized manually. That means that the priority is
-   * value of the manualPriority of the Task.
+   * set to the value of the manualPriority of the {@linkplain Task}.
    *
    * @return true, if Tasks are prioritized manually; false otherwise
    */
   boolean isManualPriorityActive();
 
   /**
-   * Gets the custom attribute of the Task.
+   * Returns the value of the specified {@linkplain TaskCustomField} of the {@linkplain Task}.
    *
-   * @param customField identifies which custom attribute is requested.
+   * @param customField identifies which {@linkplain TaskCustomField} is requested
    * @return the value for the given customField
-   * @deprecated Use {@link #getCustomField(TaskCustomField)} instead
+   * @deprecated Use {@linkplain #getCustomField(TaskCustomField)} instead
    */
   String getCustomAttribute(TaskCustomField customField);
 
   /**
-   * Gets the custom attribute of the task.
+   * Returns the value of the specified {@linkplain TaskCustomField} of the {@linkplain Task}.
    *
-   * @param customField identifies which custom attribute is requested.
+   * @param customField identifies which {@linkplain TaskCustomField} is requested
-   * @return the value for the given customField
+   * @return the value for the given {@linkplain TaskCustomField}
    */
   String getCustomField(TaskCustomField customField);
 

lib/taskana-core/src/main/java/pro/taskana/task/internal/jobs/TaskRefreshJob.java

@@ -14,7 +14,7 @@ import pro.taskana.common.internal.jobs.AbstractTaskanaJob;
 import pro.taskana.common.internal.transaction.TaskanaTransactionProvider;
 import pro.taskana.task.internal.TaskServiceImpl;
 
-/** This class executes a job of type {@linkplain pro.taskana.task.internal.jobs.TaskRefreshJob}. */
+/** This class executes a job of type {@linkplain TaskRefreshJob}. */
 public class TaskRefreshJob extends AbstractTaskanaJob {
 
   public static final String TASK_IDS = "taskIds";

lib/taskana-core/src/main/java/pro/taskana/user/api/UserService.java

@@ -51,7 +51,9 @@ public interface UserService {
    * @param userToCreate the {@linkplain User} which should be inserted
    * @return the inserted {@linkplain User}
    * @throws InvalidArgumentException if some fields are not set properly
-   * @throws NotAuthorizedException if the current user is not admin or business-admin
+   * @throws NotAuthorizedException if the current user is not {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#ADMIN admin} or {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN business-admin}
    * @throws UserAlreadyExistException if there already exists a {@linkplain User} with the
    *     specified {@linkplain User#getId() id} inside the database
    */
@@ -67,7 +69,9 @@ public interface UserService {
    *
    * @param userToUpdate the {@linkplain User} which should be updated
    * @return the updated {@linkplain User}
-   * @throws NotAuthorizedException if the current user is not admin or business-admin
+   * @throws NotAuthorizedException if the current user is not {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#ADMIN admin} or {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN business-admin}
    * @throws UserNotFoundException if there does not exist a {@linkplain User} with the specified
    *     {@linkplain User#getId() id} inside the database
    */
@@ -81,7 +85,9 @@ public interface UserService {
    * gets deleted.
    *
    * @param id the {@linkplain User#getId() id} of the {@linkplain User} which should be deleted
-   * @throws NotAuthorizedException if the current user is not admin or business-admin
+   * @throws NotAuthorizedException if the current user is not {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#ADMIN admin} or {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN business-admin}
    * @throws UserNotFoundException if there does not exist a {@linkplain User} with the specified
    *     {@linkplain User#getId() id} inside the database
    */

lib/taskana-core/src/main/java/pro/taskana/user/api/models/User.java

@@ -4,7 +4,7 @@ package pro.taskana.user.api.models;
 public interface User {
 
   /**
-   * Gets the id of the User.
+   * Returns the id of the User.
    *
    * @return userId
    */
@@ -18,7 +18,7 @@ public interface User {
   void setId(String id);
 
   /**
-   * Gets the first name of the User.
+   * Returns the first name of the User.
    *
    * @return firstName
    */
@@ -32,7 +32,7 @@ public interface User {
   void setFirstName(String firstName);
 
   /**
-   * Gets the last name of the User.
+   * Returns the last name of the User.
    *
    * @return lastName
    */
@@ -46,7 +46,7 @@ public interface User {
   void setLastName(String lastName);
 
   /**
-   * Gets the full name of the User.
+   * Returns the full name of the User.
    *
    * @return fullName
    */
@@ -60,7 +60,7 @@ public interface User {
   void setFullName(String fullName);
 
   /**
-   * Gets the long name of the User.
+   * Returns the long name of the User.
    *
    * @return longName
    */
@@ -74,7 +74,7 @@ public interface User {
   void setLongName(String longName);
 
   /**
-   * Gets the email address of the User.
+   * Returns the email address of the User.
    *
    * @return email
    */
@@ -88,7 +88,7 @@ public interface User {
   void setEmail(String email);
 
   /**
-   * Gets the phone number of the User.
+   * Returns the phone number of the User.
    *
    * @return phone
    */
@@ -102,7 +102,7 @@ public interface User {
   void setPhone(String phone);
 
   /**
-   * Gets the mobile phone number of the User.
+   * Returns the mobile phone number of the User.
    *
    * @return mobilePhone
    */
@@ -116,63 +116,63 @@ public interface User {
   void setMobilePhone(String mobilePhone);
 
   /**
-   * Gets the orgLevel4 of the User.
+   * Returns the orgLevel4 of the User.
    *
    * @return orgLevel4
    */
   String getOrgLevel4();
 
   /**
-   * Sets the fourth organization level of the User.
+   * Sets the orgLevel4 of the User.
    *
    * @param orgLevel4 the fourth organization level of the User
    */
   void setOrgLevel4(String orgLevel4);
 
   /**
-   * Gets the orgLevel3 of the User.
+   * Returns the orgLevel3 of the User.
    *
    * @return orgLevel3
    */
   String getOrgLevel3();
 
   /**
-   * Sets the third organization level of the User.
+   * Sets the orgLevel3 of the User.
    *
    * @param orgLevel3 the third organization level of the User
    */
   void setOrgLevel3(String orgLevel3);
 
   /**
-   * Gets the orgLevel2 of the User.
+   * Returns the orgLevel2 of the User.
    *
    * @return orgLevel2
    */
   String getOrgLevel2();
 
   /**
-   * Sets the second organization level of the User.
+   * Sets the orgLevel2 of the User.
    *
    * @param orgLevel2 the second organization level of the User
    */
   void setOrgLevel2(String orgLevel2);
 
   /**
-   * Gets the orgLevel1 of the User.
+   * Returns the orgLevel1 of the User.
    *
    * @return orgLevel1
    */
   String getOrgLevel1();
 
   /**
-   * Sets the first organization level of the User.
+   * Sets the orgLevel1 of the User.
    *
    * @param orgLevel1 the first organization level of the User
    */
   void setOrgLevel1(String orgLevel1);
 
   /**
-   * Gets the data of the User.
+   * Returns the data of the User.
    *
    * @return data
    */
@@ -185,5 +185,10 @@ public interface User {
    */
   void setData(String data);
 
+  /**
+   * Duplicates this User.
+   *
+   * @return a copy of this User
+   */
   User copy();
 }

lib/taskana-core/src/main/java/pro/taskana/workbasket/api/AbstractWorkbasketAccessItemQuery.java

@@ -1,6 +1,7 @@
 package pro.taskana.workbasket.api;
 
 import pro.taskana.common.api.BaseQuery;
+import pro.taskana.workbasket.api.models.Workbasket;
 import pro.taskana.workbasket.api.models.WorkbasketAccessItem;
 
 /**
@@ -22,9 +23,9 @@ public interface AbstractWorkbasketAccessItemQuery<
   Q idIn(String... ids);
 
   /**
-   * Add your workbasket id to your query.
+   * Add the {@linkplain Workbasket#getId() id} to your query.
    *
-   * @param workbasketId the workbasket Id
+   * @param workbasketId the {@linkplain Workbasket#getId() id} of the Workbasket
    * @return the query
    */
   Q workbasketIdIn(String... workbasketId);

lib/taskana-core/src/main/java/pro/taskana/workbasket/api/WorkbasketPermission.java

@@ -1,6 +1,8 @@
 package pro.taskana.workbasket.api;
 
-/** This enum contains all permission values for the workbaskets. */
+import pro.taskana.workbasket.api.models.Workbasket;
+
+/** This enum contains all permission values for the {@linkplain Workbasket Workbaskets}. */
 public enum WorkbasketPermission {
   READ,
   OPEN,

lib/taskana-core/src/main/java/pro/taskana/workbasket/api/WorkbasketService.java

@@ -8,6 +8,7 @@ import pro.taskana.common.api.exceptions.DomainNotFoundException;
 import pro.taskana.common.api.exceptions.InvalidArgumentException;
 import pro.taskana.common.api.exceptions.NotAuthorizedException;
 import pro.taskana.common.api.exceptions.TaskanaException;
+import pro.taskana.user.api.models.User;
 import pro.taskana.workbasket.api.exceptions.WorkbasketAccessItemAlreadyExistException;
 import pro.taskana.workbasket.api.exceptions.WorkbasketAlreadyExistException;
 import pro.taskana.workbasket.api.exceptions.WorkbasketInUseException;
@@ -20,32 +21,39 @@ import pro.taskana.workbasket.api.models.WorkbasketSummary;
 public interface WorkbasketService {
 
   /**
-   * Get Workbasket for a given id.
+   * Get the {@linkplain Workbasket} specified by the given {@linkplain WorkbasketSummary#getId()
+   * id}.
    *
-   * @param workbasketId the Id of the Workbasket requested
+   * @param workbasketId the {@linkplain WorkbasketSummary#getId() id} of the {@linkplain
+   *     Workbasket} requested
    * @return the requested Workbasket
-   * @throws WorkbasketNotFoundException If the Workbasket with workbasketId is not found
+   * @throws WorkbasketNotFoundException If the {@linkplain Workbasket} with workbasketId is not
-   * @throws NotAuthorizedException If the current user or group does not have the permissions for
+   *     found
-   *     interactions.
+   * @throws NotAuthorizedException If the current user or group does not have the {@linkplain
+   *     WorkbasketPermission permissions} for interactions.
    */
   Workbasket getWorkbasket(String workbasketId)
       throws WorkbasketNotFoundException, NotAuthorizedException;
 
   /**
-   * Get Workbasket for a given key.
+   * Get the {@linkplain Workbasket} specified by the given {@linkplain WorkbasketSummary#getKey()
+   * key} and {@linkplain WorkbasketSummary#getDomain() domain}.
    *
-   * @param workbasketKey the Key of the Workbasket requested
+   * @param workbasketKey the {@linkplain WorkbasketSummary#getKey() key} of the {@linkplain
-   * @param domain the domain of the workbasket
+   *     Workbasket} requested
-   * @return the requested Workbasket
+   * @param domain the {@linkplain WorkbasketSummary#getDomain() domain} of the {@linkplain
-   * @throws WorkbasketNotFoundException If the Workbasket with workbasketId is not found
+   *     Workbasket}
-   * @throws NotAuthorizedException If the current user or group does not have the permissions for
+   * @return the requested {@linkplain Workbasket}
-   *     interactions.
+   * @throws WorkbasketNotFoundException If the {@linkplain Workbasket} with workbasketId is not
+   *     found
+   * @throws NotAuthorizedException If the current user or group does not have the {@linkplain
+   *     WorkbasketPermission permissions} for interactions.
    */
   Workbasket getWorkbasket(String workbasketKey, String domain)
       throws WorkbasketNotFoundException, NotAuthorizedException;
 
   /**
-   * Creates a new Workbasket. <br>
+   * Creates a new {@linkplain Workbasket}. <br>
    * The default values are:
    *
    * <ul>
@@ -53,91 +61,106 @@ public interface WorkbasketService {
    *       IdGenerator}
    * </ul>
    *
-   * @param workbasket The Workbasket to create
+   * @param workbasket The {@linkplain Workbasket} to create
-   * @return the created and inserted Workbasket
+   * @return the created and inserted {@linkplain Workbasket}
-   * @throws InvalidArgumentException If a required property of the Workbasket is not set.
+   * @throws InvalidArgumentException If a required property of the {@linkplain Workbasket} is not
-   * @throws NotAuthorizedException if the current user is not member of role BUSINESS_ADMIN or
+   *     set.
-   *     ADMIN
+   * @throws NotAuthorizedException if the current user is not member of role {@linkplain
-   * @throws WorkbasketAlreadyExistException if the Workbasket exists already
+   *     pro.taskana.common.api.TaskanaRole#ADMIN admin} or {@linkplain
-   * @throws DomainNotFoundException if the domain does not exist in the configuration.
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN business-admin}
+   * @throws WorkbasketAlreadyExistException if the {@linkplain Workbasket} exists already
+   * @throws DomainNotFoundException if the {@linkplain Workbasket#getDomain() domain} does not
+   *     exist in the configuration.
    */
   Workbasket createWorkbasket(Workbasket workbasket)
       throws InvalidArgumentException, NotAuthorizedException, WorkbasketAlreadyExistException,
           DomainNotFoundException;
 
   /**
-   * Update a Workbasket.
+   * Update the given {@linkplain Workbasket}.
    *
-   * @param workbasket The Workbasket to update
+   * @param workbasket The {@linkplain Workbasket} to update
-   * @return the updated Workbasket
+   * @return the updated {@linkplain Workbasket}
-   * @throws InvalidArgumentException if workbasket name or type is invalid
+   * @throws InvalidArgumentException if {@linkplain Workbasket#getName() name} or {@linkplain
+   *     Workbasket#getType() type} of the {@linkplain Workbasket} is invalid
    * @throws NotAuthorizedException if the current user is not authorized to update the {@linkplain
    *     Workbasket}
    * @throws WorkbasketNotFoundException if the {@linkplain Workbasket} cannot be found.
    * @throws ConcurrencyException if an attempt is made to update the {@linkplain Workbasket} and
-   *     another user updated it already
+   *     another user updated it already; that's the case if the given modified timestamp differs
+   *     from the one in the database
    */
   Workbasket updateWorkbasket(Workbasket workbasket)
       throws InvalidArgumentException, NotAuthorizedException, WorkbasketNotFoundException,
           ConcurrencyException;
 
   /**
-   * Returns a new WorkbasketAccessItem which is not inserted.
+   * Returns a new {@linkplain WorkbasketAccessItem} which is not inserted.
    *
-   * @param workbasketId the workbasket id used to identify the referenced {@linkplain Workbasket}
+   * @param workbasketId the {@linkplain Workbasket#getId() id} used to identify the referenced
+   *     {@linkplain Workbasket}
    * @param accessId the group id or user id for which access is controlled
-   * @return new WorkbasketAccessItem
+   * @return new {@linkplain WorkbasketAccessItem}
    */
   WorkbasketAccessItem newWorkbasketAccessItem(String workbasketId, String accessId);
 
   /**
-   * Create and insert a new {@link WorkbasketAccessItem} with a WorkbasketId, an accessId and
+   * Create and insert a new {@linkplain WorkbasketAccessItem} with a {@linkplain
-   * permissions.
+   * WorkbasketAccessItem#getWorkbasketId() workbasketId}, an {@linkplain
+   * WorkbasketAccessItem#getAccessId() accessId} and {@linkplain
+   * WorkbasketAccessItem#getPermission(WorkbasketPermission) permissions}.
    *
-   * @param workbasketAccessItem the new workbasketAccessItem
+   * @param workbasketAccessItem the new {@linkplain WorkbasketAccessItem}
-   * @return the created WorkbasketAccessItem
+   * @return the created {@linkplain WorkbasketAccessItem}
-   * @throws InvalidArgumentException if the preconditions dont match the required ones.
+   * @throws InvalidArgumentException if the preconditions don't match the required ones.
-   * @throws NotAuthorizedException if the current user is not member of role BUSINESS_ADMIN or
+   * @throws NotAuthorizedException if the current user is not member of role {@linkplain
-   *     ADMIN
+   *     pro.taskana.common.api.TaskanaRole#ADMIN admin} or {@linkplain
-   * @throws WorkbasketNotFoundException if the workbasketAccessItem refers to a not existing
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN business-admin}
-   *     workbasket *
+   * @throws WorkbasketNotFoundException if the {@linkplain WorkbasketAccessItem} refers to a not
-   * @throws WorkbasketAccessItemAlreadyExistException if there exists already a
+   *     existing workbasket
-   *     WorkbasketAccessItem for the same access id and workbasket
+   * @throws WorkbasketAccessItemAlreadyExistException if there exists already a {@linkplain
+   *     WorkbasketAccessItem} for the same {@linkplain WorkbasketAccessItem#getAccessId() accessId}
+   *     and {@linkplain Workbasket}
    */
   WorkbasketAccessItem createWorkbasketAccessItem(WorkbasketAccessItem workbasketAccessItem)
       throws InvalidArgumentException, NotAuthorizedException, WorkbasketNotFoundException,
           WorkbasketAccessItemAlreadyExistException;
 
   /**
-   * This method updates a {@link WorkbasketAccessItem}.
+   * This method updates a {@linkplain WorkbasketAccessItem}.
    *
-   * @param workbasketAccessItem the {@link WorkbasketAccessItem}
+   * @param workbasketAccessItem the {@linkplain WorkbasketAccessItem}
    * @return the updated entity
-   * @throws InvalidArgumentException if accessid or workbasketId is changed in the
+   * @throws InvalidArgumentException if {@linkplain WorkbasketAccessItem#getAccessId() accessId} or
-   *     workbasketAccessItem
+   *     {@linkplain WorkbasketAccessItem#getWorkbasketId() workbasketId} is changed in the
-   * @throws NotAuthorizedException if the current user is not member of role BUSINESS_ADMIN or
+   *     {@linkplain WorkbasketAccessItem}
-   *     ADMIN
+   * @throws NotAuthorizedException if the current user is not member of role {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#ADMIN admin} or {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN business-admin}
    */
   WorkbasketAccessItem updateWorkbasketAccessItem(WorkbasketAccessItem workbasketAccessItem)
       throws InvalidArgumentException, NotAuthorizedException;
 
   /**
-   * Deletes a specific {@link WorkbasketAccessItem}.
+   * Deletes a specific {@linkplain WorkbasketAccessItem}.
    *
-   * @param id the id of the WorbasketAccessItem to be deleted
+   * @param id the {@linkplain WorkbasketAccessItem#getId() id} of the {@linkplain
-   * @throws NotAuthorizedException if the current user is not member of role BUSINESS_ADMIN or
+   *     WorkbasketAccessItem} to be deleted
-   *     ADMIN
+   * @throws NotAuthorizedException if the current user is not member of role {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#ADMIN admin} or {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN business-admin}
    */
   void deleteWorkbasketAccessItem(String id) throws NotAuthorizedException;
 
   /**
    * This method checks the authorization for the actual User.
    *
-   * @param workbasketId the id of the workbasket we want to access
+   * @param workbasketId the {@linkplain Workbasket#getId() id} of the {@linkplain Workbasket} we
-   * @param permission the needed {@link WorkbasketPermission} If more than one permission is
+   *     want to access
-   *     specified, the current user needs all of them.
+   * @param permission the needed {@linkplain WorkbasketPermission}; if more than one {@linkplain
+   *     WorkbasketPermission permission} is specified, the current user needs all of them
    * @throws NotAuthorizedException if the current user has not the requested authorization for the
-   *     specified workbasket
+   *     specified {@linkplain Workbasket}
    * @throws WorkbasketNotFoundException if the {@linkplain Workbasket} cannot be found for the
    *     given {@linkplain Workbasket#getId() id}.
    */
@@ -147,20 +170,22 @@ public interface WorkbasketService {
   /**
    * This method checks the authorization for the actual User.
    *
-   * @param workbasketKey the key of the workbasket we want to access
+   * @param workbasketKey the {@linkplain Workbasket#getKey() key} of the {@linkplain Workbasket} we
-   * @param domain the domain of the workbasket we want to access
+   *     want to access
-   * @param permission the needed {@link WorkbasketPermission}. If more than one permission is
+   * @param domain the {@linkplain Workbasket#getDomain() domain} of the {@linkplain Workbasket} we
-   *     specified, the current user needs all of them.
+   *     want to access
-   * @throws NotAuthorizedException if the current user has not the requested permission for the
+   * @param permission the needed {@linkplain WorkbasketPermission}; if more than one {@linkplain
-   *     specified workbasket
+   *     WorkbasketPermission permission} is specified, the current user needs all of them.
-   * @throws WorkbasketNotFoundException if no workbasket can be found for the given key+domain
+   * @throws NotAuthorizedException if the current user has not the requested {@linkplain
-   *     values.
+   *     WorkbasketPermission permission} for the specified {@linkplain Workbasket}
+   * @throws WorkbasketNotFoundException if no {@linkplain Workbasket} can be found for the given
+   *     {@linkplain Workbasket#getKey() key} and {@linkplain Workbasket#getDomain() domain} values.
    */
   void checkAuthorization(String workbasketKey, String domain, WorkbasketPermission... permission)
       throws NotAuthorizedException, WorkbasketNotFoundException;
 
   /**
-   * Get all {@link WorkbasketAccessItem s} for a {@linkplain Workbasket}.
+   * Get all {@linkplain WorkbasketAccessItem}s for a {@linkplain Workbasket}.
    *
    * @param workbasketId the {@linkplain Workbasket#getId() id} of the {@linkplain Workbasket}
    * @return List of {@linkplain WorkbasketAccessItem}s for the {@linkplain Workbasket}
@@ -172,25 +197,29 @@ public interface WorkbasketService {
       throws NotAuthorizedException;
 
   /**
-   * Setting up the new WorkbasketAccessItems for a Workbasket. Already stored values will be
+   * Setting up the new {@linkplain WorkbasketAccessItem}s for a {@linkplain Workbasket}. Already
-   * completely replaced by the current ones.
+   * stored values will be completely replaced by the current ones.
    *
-   * <p>Preconditions for each {@link WorkbasketAccessItem} then {@code wbAccessItems}:
+   * <p>Preconditions for each {@linkplain WorkbasketAccessItem} then {@code wbAccessItems}:
    *
    * <ul>
-   *   <li>{@link WorkbasketAccessItem#getWorkbasketId()} is not null
+   *   <li>{@linkplain WorkbasketAccessItem#getWorkbasketId()} is not null
-   *   <li>{@link WorkbasketAccessItem#getWorkbasketId()} is equal to {@code workbasketId}
+   *   <li>{@linkplain WorkbasketAccessItem#getWorkbasketId()} is equal to {@code workbasketId}
-   *   <li>{@link WorkbasketAccessItem#getAccessId()} is unique
+   *   <li>{@linkplain WorkbasketAccessItem#getAccessId()} is unique
    * </ul>
    *
-   * @param workbasketId ID of the access-target workbasket.
+   * @param workbasketId {@linkplain Workbasket#getId() id} of the access-target {@linkplain
-   * @param wbAccessItems List of WorkbasketAccessItems which does replace all current stored ones.
+   *     Workbasket}.
+   * @param wbAccessItems List of {@linkplain WorkbasketAccessItem}s which does replace all current
+   *     stored ones.
    * @throws InvalidArgumentException will be thrown when the parameter {@code wbAccessItems} is
    *     NULL or member doesn't match the preconditions
-   * @throws NotAuthorizedException if the current user is not member of role BUSINESS_ADMIN or
+   * @throws NotAuthorizedException if the current user is not member of role {@linkplain
-   *     ADMIN
+   *     pro.taskana.common.api.TaskanaRole#ADMIN admin} or {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN business-admin}
    * @throws WorkbasketAccessItemAlreadyExistException if {@code wbAccessItems} contains multiple
-   *     accessItems with the same accessId.
+   *     {@linkplain WorkbasketAccessItem} with the same {@linkplain
+   *     WorkbasketAccessItem#getAccessId() accessId}.
    * @throws WorkbasketNotFoundException if the {@linkplain Workbasket} cannot be found for the
    *     given {@linkplain Workbasket#getId() id}.
    */
@@ -201,114 +230,128 @@ public interface WorkbasketService {
   /**
    * This method provides a query builder for querying the database.
    *
-   * @return a {@link WorkbasketQuery}
+   * @return a {@linkplain WorkbasketQuery}
    */
   WorkbasketQuery createWorkbasketQuery();
 
   /**
    * This method provides a query builder for querying the database.
    *
-   * @return a {@link WorkbasketAccessItemQuery}
+   * @return a {@linkplain WorkbasketAccessItemQuery}
-   * @throws NotAuthorizedException if the current user is not member of role BUSINESS_ADMIN or
+   * @throws NotAuthorizedException if the current user is not member of role {@linkplain
-   *     ADMIN
+   *     pro.taskana.common.api.TaskanaRole#ADMIN admin} or {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN business-admin}
    */
   WorkbasketAccessItemQuery createWorkbasketAccessItemQuery() throws NotAuthorizedException;
 
   /**
-   * Returns a new workbasket which is not inserted.
+   * Returns a new {@linkplain Workbasket} which is not inserted.
    *
-   * @param key the workbasket key used to identify the workbasket
+   * @param key the {@linkplain Workbasket#getKey() key} used to identify the {@linkplain
-   * @param domain the domain of the new workbasket
+   *     Workbasket}
-   * @return new Workbasket
+   * @param domain the {@linkplain Workbasket#getDomain() domain} of the new {@linkplain Workbasket}
+   * @return new {@linkplain Workbasket}
    */
   Workbasket newWorkbasket(String key, String domain);
 
   /**
-   * Returns a set with all permissions of the current user at this workbasket.<br>
+   * Returns a set with all {@linkplain WorkbasketPermission permissions} of the current user at
-   * If the workbasketId is invalid, an empty list of permissions is returned since there is no
+   * this {@linkplain Workbasket}.<br>
-   * distinction made between the situation that the workbasket is not found and the caller has no
+   * If the workbasketId is invalid, an empty List of {@linkplain WorkbasketPermission}s is returned
-   * permissions on the workbasket.
+   * since there is no distinction made between the situation that the {@linkplain Workbasket} is
+   * not found and the caller has no {@linkplain WorkbasketPermission permissions} on the
+   * {@linkplain Workbasket}.
    *
-   * @param workbasketId the id of the referenced workbasket
+   * @param workbasketId the {@linkplain Workbasket#getId() id} of the referenced {@linkplain
+   *     Workbasket}
    * @return a {@link List} with all {@link WorkbasketPermission}s of the caller on the requested
-   *     workbasket.
+   *     {@linkplain Workbasket}.
    */
   List<WorkbasketPermission> getPermissionsForWorkbasket(String workbasketId);
 
   /**
-   * Returns the distribution targets for a given workbasket.
+   * Returns the distribution targets for a given {@linkplain Workbasket}.
    *
-   * @param workbasketId the id of the referenced workbasket
+   * @param workbasketId the {@linkplain Workbasket#getId() id} of the referenced {@linkplain
-   * @return the distribution targets of the specified workbasket
+   *     Workbasket}
-   * @throws NotAuthorizedException if the current user has no read permission for the specified
+   * @return the distribution targets of the specified {@linkplain Workbasket}
-   *     workbasket
+   * @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
-   * @throws WorkbasketNotFoundException if the workbasket doesn't exist
+   *     READ permission} for the specified {@linkplain Workbasket}
+   * @throws WorkbasketNotFoundException if the {@linkplain Workbasket} doesn't exist
    */
   List<WorkbasketSummary> getDistributionTargets(String workbasketId)
       throws NotAuthorizedException, WorkbasketNotFoundException;
 
   /**
-   * Returns the distribution targets for a given workbasket.
+   * Returns the distribution targets for a given {@linkplain Workbasket}.
    *
-   * @param workbasketKey the key of the referenced workbasket
+   * @param workbasketKey the {@linkplain Workbasket#getKey() key} of the referenced {@linkplain
-   * @param domain the domain of the referenced workbasket
+   *     Workbasket}
-   * @return the distribution targets of the specified workbasket
+   * @param domain the {@linkplain Workbasket#getDomain() domain} of the referenced {@linkplain
-   * @throws NotAuthorizedException if the current user has no read permission for the specified
+   *     Workbasket}
-   *     workbasket
+   * @return the distribution targets of the specified {@linkplain Workbasket}
-   * @throws WorkbasketNotFoundException if the workbasket doesn't exist
+   * @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
+   *     READ permission} for the specified {@linkplain Workbasket}
+   * @throws WorkbasketNotFoundException if the {@linkplain Workbasket} doesn't exist
    */
   List<WorkbasketSummary> getDistributionTargets(String workbasketKey, String domain)
       throws NotAuthorizedException, WorkbasketNotFoundException;
 
   /**
-   * Set the distribution targets for a workbasket.
+   * Set the distribution targets for a {@linkplain Workbasket}.
    *
-   * @param sourceWorkbasketId the id of the source workbasket for which the distribution targets
+   * @param sourceWorkbasketId the {@linkplain Workbasket#getId() id} of the source {@linkplain
-   *     are to be set
+   *     Workbasket} for which the distribution targets are to be set
-   * @param targetWorkbasketIds a list of the ids of the target workbaskets
+   * @param targetWorkbasketIds a list of the ids of the target {@linkplain Workbasket}s
-   * @throws NotAuthorizedException if the current used doesn't have READ permission for the source
+   * @throws NotAuthorizedException if the current used doesn't have {@linkplain
-   *     workbasket
+   *     WorkbasketPermission#READ READ permission} for the source {@linkplain Workbasket}
-   * @throws WorkbasketNotFoundException if either the source workbasket or any of the target
+   * @throws WorkbasketNotFoundException if either the source {@linkplain Workbasket} or any of the
-   *     workbaskets don't exist
+   *     target {@linkplain Workbasket}s don't exist
    */
   void setDistributionTargets(String sourceWorkbasketId, List<String> targetWorkbasketIds)
       throws NotAuthorizedException, WorkbasketNotFoundException;
 
   /**
-   * Add a distribution target to a workbasket. If the specified distribution target exists already,
+   * Add a distribution target to a {@linkplain Workbasket}. If the specified distribution target
-   * the method silently returns without doing anything.
+   * exists already, the method silently returns without doing anything.
    *
-   * @param sourceWorkbasketId the id of the source workbasket
+   * @param sourceWorkbasketId the {@linkplain Workbasket#getId() id} of the source {@linkplain
-   * @param targetWorkbasketId the id of the target workbasket
+   *     Workbasket}
-   * @throws NotAuthorizedException if the current user doesn't have READ permission for the source
+   * @param targetWorkbasketId the {@linkplain Workbasket#getId() id} of the target {@linkplain
-   *     workbasket
+   *     Workbasket}
-   * @throws WorkbasketNotFoundException if either the source workbasket or the target workbasket
+   * @throws NotAuthorizedException if the current user doesn't have {@linkplain
-   *     doesn't exist
+   *     WorkbasketPermission#READ READ permission} for the source {@linkplain Workbasket}s
+   * @throws WorkbasketNotFoundException if either the source {@linkplain Workbasket} or the target
+   *     {@linkplain Workbasket} doesn't exist
    */
   void addDistributionTarget(String sourceWorkbasketId, String targetWorkbasketId)
       throws NotAuthorizedException, WorkbasketNotFoundException;
 
   /**
-   * Remove a distribution target from a workbasket. If the specified distribution target doesn't
+   * Remove a distribution target from a {@linkplain Workbasket}. If the specified distribution
-   * exist, the method silently returns without doing anything.
+   * target doesn't exist, the method silently returns without doing anything.
    *
-   * @param sourceWorkbasketId The id of the source workbasket
+   * @param sourceWorkbasketId The {@linkplain Workbasket#getId() id} of the source {@linkplain
-   * @param targetWorkbasketId The id of the target workbasket
+   *     Workbasket}
-   * @throws NotAuthorizedException If the current user doesn't have READ permission for the source
+   * @param targetWorkbasketId The {@linkplain Workbasket#getId() id} of the target {@linkplain
-   *     workbasket
+   *     Workbasket}
+   * @throws NotAuthorizedException If the current user doesn't have {@linkplain
+   *     WorkbasketPermission#READ READ permission} for the source {@linkplain Workbasket}
    */
   void removeDistributionTarget(String sourceWorkbasketId, String targetWorkbasketId)
       throws NotAuthorizedException;
 
   /**
-   * Deletes the workbasket by the given ID of it.
+   * Deletes the {@linkplain Workbasket} by the given {@linkplain Workbasket#getId() id}.
    *
-   * @param workbasketId Id of the workbasket which should be deleted.
+   * @param workbasketId {@linkplain Workbasket#getId() id} of the {@linkplain Workbasket} which
-   * @return true if the workbasket was deleted successfully. false if the workbasket is marked for
+   *     should be deleted.
-   *     deletion.
+   * @return true if the {@linkplain Workbasket} was deleted successfully; false if the {@linkplain
-   * @throws NotAuthorizedException if the current user got no permissions for this interaction.
+   *     Workbasket} is marked for deletion
-   * @throws WorkbasketNotFoundException if the workbasket does not exist.
+   * @throws NotAuthorizedException if the current user got no {@linkplain WorkbasketPermission}s
-   * @throws WorkbasketInUseException if the workbasket does contain task-content.
+   *     for this interaction
+   * @throws WorkbasketNotFoundException if the {@linkplain Workbasket} does not exist
+   * @throws WorkbasketInUseException if the {@linkplain Workbasket} does contain task-content
    * @throws InvalidArgumentException if the workbasketId is NULL or EMPTY
    */
   boolean deleteWorkbasket(String workbasketId)
@@ -316,47 +359,54 @@ public interface WorkbasketService {
           InvalidArgumentException;
 
   /**
-   * Deletes a list of workbaskets.
+   * Deletes the list of {@linkplain Workbasket}s specified via {@linkplain Workbasket#getId() ids}.
    *
-   * @param workbasketsIds the ids of the workbaskets to delete.
+   * @param workbasketsIds the {@linkplain Workbasket#getId() ids} of the {@linkplain Workbasket}s
-   * @return the result of the operations with Id and Exception for each failed workbasket deletion.
+   *     to delete.
-   * @throws InvalidArgumentException if the WorkbasketIds parameter list is NULL or empty
+   * @return the result of the operations and an Exception for each failed workbasket deletion
-   * @throws NotAuthorizedException if the current user got no permission for this interaction.
+   * @throws InvalidArgumentException if the WorkbasketIds parameter List is NULL or empty
+   * @throws NotAuthorizedException if the current user got no {@linkplain WorkbasketPermission} for
+   *     this interaction
    */
   BulkOperationResults<String, TaskanaException> deleteWorkbaskets(List<String> workbasketsIds)
       throws NotAuthorizedException, InvalidArgumentException;
 
   /**
-   * Returns the distribution sources for a given workbasket.
+   * Returns the distribution sources for a given {@linkplain Workbasket}.
    *
-   * @param workbasketId the id of the referenced workbasket
+   * @param workbasketId the {@linkplain Workbasket#getId() id} of the referenced {@linkplain
-   * @return the workbaskets that are distribution sources of the specified workbasket.
+   *     Workbasket}
-   * @throws NotAuthorizedException if the current user has no read permission for the specified
+   * @return the workbaskets that are distribution sources of the specified {@linkplain Workbasket}.
-   *     workbasket
+   * @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
-   * @throws WorkbasketNotFoundException if the workbasket doesn't exist
+   *     READ permission} for the specified {@linkplain Workbasket}
+   * @throws WorkbasketNotFoundException if the {@linkplain Workbasket} doesn't exist
    */
   List<WorkbasketSummary> getDistributionSources(String workbasketId)
       throws NotAuthorizedException, WorkbasketNotFoundException;
 
   /**
-   * Returns the distribution sources for a given workbasket.
+   * Returns the distribution sources for a given {@linkplain Workbasket}.
    *
-   * @param workbasketKey the key of the referenced workbasket
+   * @param workbasketKey the {@linkplain Workbasket#getKey() key} of the referenced {@linkplain
-   * @param domain the domain of the referenced workbasket
+   *     Workbasket}
-   * @return the workbaskets that are distribution sources of the specified workbasket.
+   * @param domain the {@linkplain Workbasket#getDomain() domain} of the referenced {@linkplain
-   * @throws NotAuthorizedException if the current user has no read permission for the specified
+   *     Workbasket}
-   *     workbasket
+   * @return the workbaskets that are distribution sources of the specified {@linkplain Workbasket}.
-   * @throws WorkbasketNotFoundException if the workbasket doesn't exist
+   * @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
+   *     READ permission} for the specified {@linkplain Workbasket}
+   * @throws WorkbasketNotFoundException if the {@linkplain Workbasket} doesn't exist
    */
   List<WorkbasketSummary> getDistributionSources(String workbasketKey, String domain)
       throws NotAuthorizedException, WorkbasketNotFoundException;
 
   /**
-   * Deletes all WorkbasketAccessItems using the given AccessId of a user.
+   * Deletes all {@linkplain WorkbasketAccessItem}s using the given {@linkplain
+   * WorkbasketAccessItem#getAccessId()}.
    *
-   * @param accessId of a taskana-user.
+   * @param accessId {@linkplain User#getId() id} of a taskana-{@linkplain User}.
-   * @throws NotAuthorizedException if the current user is not member of role BUSINESS_ADMIN or
+   * @throws NotAuthorizedException if the current user is not member of role {@linkplain
-   *     ADMIN
+   *     pro.taskana.common.api.TaskanaRole#ADMIN admin} or {@linkplain
+   *     pro.taskana.common.api.TaskanaRole#BUSINESS_ADMIN business-admin}
    */
   void deleteWorkbasketAccessItemsForAccessId(String accessId) throws NotAuthorizedException;
 }

lib/taskana-core/src/main/java/pro/taskana/workbasket/api/models/Workbasket.java

@@ -9,87 +9,87 @@ import pro.taskana.workbasket.api.WorkbasketType;
 public interface Workbasket extends WorkbasketSummary {
 
   /**
-   * Sets the name of the workbasket.
+   * Sets the name of the Workbasket.
    *
-   * @param workbasketName the name of the workbasket
+   * @param workbasketName the name of the Workbasket
    */
   void setName(String workbasketName);
 
   /**
-   * Sets the workbasket-descriptions.
+   * Sets the description of the Workbasket.
    *
-   * @param description the description of the workbasket
+   * @param description the description of the Workbasket
    */
   void setDescription(String description);
 
   /**
-   * Sets the type of the workbasket.
+   * Sets the type of the Workbasket.
    *
-   * @param type the type of the workbasket
+   * @param type the type of the Workbasket
    */
   void setType(WorkbasketType type);
 
   /**
-   * Sets the value for custom Attribute.
+   * Sets the value of the specified {@linkplain WorkbasketCustomField}.
    *
-   * @param customField identifies which custom attribute is to be set.
+   * @param customField identifies which {@linkplain WorkbasketCustomField} is to be set
-   * @param value the value of the custom attribute to be set
+   * @param value the value of the {@linkplain WorkbasketCustomField} to be set
-   * @deprecated Use {@link #setCustomField(WorkbasketCustomField, String)} instead
+   * @deprecated Use {@linkplain #setCustomField(WorkbasketCustomField, String)} instead
    */
   void setCustomAttribute(WorkbasketCustomField customField, String value);
 
   /**
-   * Sets the value for custom field.
+   * Sets the value for the specified {@linkplain WorkbasketCustomField}.
    *
-   * @param customField identifies which custom field is to be set.
+   * @param customField identifies which {@linkplain WorkbasketCustomField} is to be set.
-   * @param value the value of the custom field to be set
+   * @param value the value of the {@linkplain WorkbasketCustomField} to be set
    */
   void setCustomField(WorkbasketCustomField customField, String value);
 
   /**
    * Sets the value for orgLevel1 attribute.
    *
-   * @param orgLevel1 the orgLevel1 property of the workbasket
+   * @param orgLevel1 the orgLevel1 property of the Workbasket
    */
   void setOrgLevel1(String orgLevel1);
 
   /**
    * Sets the value for orgLevel2 attribute.
    *
-   * @param orgLevel2 the orgLevel2 property of the workbasket
+   * @param orgLevel2 the orgLevel2 property of the Workbasket
    */
   void setOrgLevel2(String orgLevel2);
 
   /**
    * Sets the value for orgLevel3 attribute.
    *
-   * @param orgLevel3 the orgLevel3 property of the workbasket
+   * @param orgLevel3 the orgLevel3 property of the Workbasket
    */
   void setOrgLevel3(String orgLevel3);
 
   /**
    * Sets the value for orgLevel4 attribute.
    *
-   * @param orgLevel4 the orgLevel4 property of the workbasket
+   * @param orgLevel4 the orgLevel4 of the Workbasket
    */
   void setOrgLevel4(String orgLevel4);
 
   /**
-   * Return the value for the markedForDeletion attribute.
+   * Checks if the Workbasket is marked for deletion.
    *
-   * @return markedForDeletion
+   * @return the markedForDeletion flag
    */
   boolean isMarkedForDeletion();
 
   /**
-   * Sets the value for markedForDeletion attribute.
+   * Sets the value for markedForDeletion flag.
    *
-   * @param markedForDeletion the markedForDeletion property of the workbasket
+   * @param markedForDeletion the markedForDeletion flag of the Workbasket
    */
   void setMarkedForDeletion(boolean markedForDeletion);
 
   /**
-   * Duplicates this Workbasket without the id.
+   * Duplicates the Workbasket without the id.
    *
    * @param key for the new Workbasket
    * @return a copy of this Workbasket
@@ -97,30 +97,30 @@ public interface Workbasket extends WorkbasketSummary {
   Workbasket copy(String key);
 
   /**
-   * Sets the owner-ID of the workbasket.
+   * Sets the owner of the Workbasket.
    *
-   * @param owner of the current workbasket
+   * @param owner the id of the owner of the current Workbasket
    */
   void setOwner(String owner);
 
   /**
-   * Returns the date when the workbasket was created.
+   * Returns the time when the Workbasket was created.
    *
-   * @return created as Instant
+   * @return the created Instant
    */
   Instant getCreated();
 
   /**
-   * Returns the date when the workbasket was modified the last time.
+   * Returns the time when the Workbasket was modified last time.
    *
-   * @return modified as Instant
+   * @return the modified Instant
    */
   Instant getModified();
 
   /**
-   * Return a summary of the current workbasket.
+   * Returns a summary of the current Workbasket.
    *
-   * @return the WorkbasketSummary object for the current work basket
+   * @return the {@linkplain WorkbasketSummary} object for the current Workbasket
    */
   WorkbasketSummary asSummary();
 }

lib/taskana-core/src/main/java/pro/taskana/workbasket/api/models/WorkbasketAccessItem.java

@@ -4,69 +4,73 @@ import pro.taskana.workbasket.api.WorkbasketPermission;
 
 /**
  * Interface for WorkbasketAccessItem. This interface is used to control access of users to
- * workbaskets.
+ * {@linkplain Workbasket Workbaskets}.
  */
 public interface WorkbasketAccessItem {
 
   /**
    * Returns the current id of the WorkbasketAccessItem.
    *
-   * @return Id
+   * @return id
    */
   String getId();
 
   /**
-   * Returns the Id of the referenced workbasket.
+   * Returns the {@linkplain WorkbasketSummary#getId() id} of the referenced {@linkplain
+   * Workbasket}.
    *
-   * @return the workbasket Id
+   * @return {@linkplain WorkbasketSummary#getId() workbasketId}
    */
   String getWorkbasketId();
 
   /**
-   * Returns the Key of the referenced workbasket.
+   * Returns the {@linkplain WorkbasketSummary#getKey() key} of the referenced {@linkplain
+   * Workbasket}.
    *
-   * @return the workbasket Key
+   * @return {@linkplain WorkbasketSummary#getKey() key}
    */
   String getWorkbasketKey();
 
   /**
-   * Returns the group id or user id for which this WorkbasketAccessItem controls access
+   * Returns the id of the group or the user for which this WorkbasketAccessItem controls access
    * permissions.
    *
-   * @return access id, this is the group id or user id
+   * @return the accessId, this is the group id or user id
    */
   String getAccessId();
 
   /**
    * Returns the name of the group or user for which this WorkbasketAccessItem controls access
-   * permissions.
+   * {@linkplain WorkbasketPermission permissions}.
    *
-   * @return access name, this is the name of the group or user
+   * @return the accessName, this is the name of the group or user
    */
   String getAccessName();
 
   /**
    * Set the name of the group or user for which this WorkbasketAccessItem controls access
-   * permissions.
+   * {@linkplain WorkbasketPermission permissions}.
    *
    * @param name the name of the group or user for which this WorkbasketAccessItem controls access
-   *     permissions.
+   *     {@linkplain WorkbasketPermission permissions}
    */
   void setAccessName(String name);
 
   /**
-   * Sets a given permission for the referenced workbasket.
+   * Sets a given {@linkplain WorkbasketPermission permissions} for the referenced {@link
+   * Workbasket}.
    *
-   * @param permission the permission which is set.
+   * @param permission the {@linkplain WorkbasketPermission permissions} which is set
-   * @param value the value for the permission.
+   * @param value the value for the {@linkplain WorkbasketPermission permissions}
    */
   void setPermission(WorkbasketPermission permission, boolean value);
 
   /**
-   * Returns weather the given permission is permitted or not.
+   * Returns whether the given {@linkplain WorkbasketPermission permissions} is permitted or not.
    *
-   * @param permission the permission in question.
+   * @param permission the {@linkplain WorkbasketPermission permissions} in question
-   * @return True, when the given permission is permitted. Otherwise false.
+   * @return True, if the given {@linkplain WorkbasketPermission permissions} is permitted;
+   *     otherwise false
    */
   boolean getPermission(WorkbasketPermission permission);
 

lib/taskana-core/src/main/java/pro/taskana/workbasket/api/models/WorkbasketSummary.java

@@ -10,103 +10,107 @@ import pro.taskana.workbasket.api.WorkbasketType;
 public interface WorkbasketSummary {
 
   /**
-   * Gets the id of the workbasket.
+   * Returns the id of the {@linkplain Workbasket}.
    *
-   * @return workbasketId
+   * @return id
    */
   String getId();
 
   /**
-   * Gets the key of the workbasket.
+   * Returns the key of the {@linkplain Workbasket}.
    *
-   * @return workbasketKey
+   * @return key
    */
   String getKey();
 
   /**
-   * Gets the name of the workbasket.
+   * Returns the name of the {@linkplain Workbasket}.
    *
-   * @return workbasket's name
+   * @return name
    */
   String getName();
 
   /**
-   * Gets the description of the workbasket.
+   * Returns the description of the {@linkplain Workbasket}.
    *
-   * @return workbasket's description
+   * @return description
    */
   String getDescription();
 
   /**
-   * Gets the owner of the workbasket.
+   * Returns the owner of the {@linkplain Workbasket}.
    *
-   * @return workbasket's owner
+   * @return owner
    */
   String getOwner();
 
   /**
-   * Gets the domain of the workbasket.
+   * Returns the domain of the {@linkplain Workbasket}.
    *
-   * @return workbasket's domain
+   * @return domain
    */
   String getDomain();
 
   /**
-   * Gets the type of the workbasket.
+   * Returns the type of the {@linkplain Workbasket}.
    *
-   * @return workbasket's type
+   * @return type
    */
   WorkbasketType getType();
 
   /**
-   * Gets the custom attribute of the workbasket.
+   * Returns the value of the specified {@linkplain WorkbasketCustomField} of the {@linkplain
+   * Workbasket}.
    *
-   * @param customField identifies which custom attribute is requested.
+   * @param customField identifies which {@linkplain WorkbasketCustomField} is requested
-   * @return the value for the given customField
+   * @return the value for the given {@linkplain WorkbasketCustomField}
-   * @deprecated Use {@link #getCustomField(WorkbasketCustomField)} instead
+   * @deprecated Use {@linkplain #getCustomField(WorkbasketCustomField)} instead
    */
   String getCustomAttribute(WorkbasketCustomField customField);
 
   /**
-   * Gets the custom attribute of the workbasket.
+   * Returns the value of the specified {@linkplain WorkbasketCustomField} of the {@linkplain
+   * Workbasket}.
    *
-   * @param customField identifies which custom attribute is requested.
+   * @param customField identifies which the value of the specified {@linkplain
-   * @return the value for the given customField
+   *     WorkbasketCustomField} of the {@linkplain Workbasket} is requested
+   * @return the value for the given the value of the specified {@linkplain WorkbasketCustomField}
+   *     of the {@linkplain Workbasket}
    */
   String getCustomField(WorkbasketCustomField customField);
 
   /**
-   * Gets the orglevel1 property of the workbasket.
+   * Returns the orglevel1 of the {@linkplain Workbasket}.
    *
-   * @return the workbasket's orglevel1 property
+   * @return orglevel1
    */
   String getOrgLevel1();
 
   /**
-   * Gets the orglevel2 property of the workbasket.
+   * Returns the orglevel2 of the {@linkplain Workbasket}.
    *
-   * @return the workbasket's orglevel2 property
+   * @return orglevel2
    */
   String getOrgLevel2();
 
   /**
-   * Gets the orglevel3 property of the workbasket.
+   * Returns the orglevel3 of the {@linkplain Workbasket}.
    *
-   * @return the workbasket's orglevel3 property
+   * @return orglevel3
    */
   String getOrgLevel3();
 
   /**
-   * Gets the orglevel4 property of the workbasket.
+   * Returns the orglevel4 of the {@linkplain Workbasket}.
    *
-   * @return the workbasket's orglevel4 property
+   * @return orglevel4
    */
   String getOrgLevel4();
 
   /**
-   * Gets the markedForDeletion property of the workbasket.
+   * Checks if the {@linkplain Workbasket} is marked for deletion.
    *
-   * @return the workbasket's markedForDeletion property
+   * @return the markedForDeletion flag
    */
   boolean isMarkedForDeletion();
 

lib/taskana-core/src/main/java/pro/taskana/workbasket/internal/WorkbasketServiceImpl.java

@@ -946,7 +946,8 @@ public class WorkbasketServiceImpl implements WorkbasketService {
    *
    * @param oldWorkbasket the old workbasket in the system
    * @param workbasketImplToUpdate the workbasket to update
-   * @throws ConcurrencyException if the workbasket has been modified by some other process.
+   * @throws ConcurrencyException if the workbasket has been modified by some other process; that's
+   *     the case if the given modified timestamp differs from the one in the database
    */
   public void checkModifiedHasNotChanged(
       Workbasket oldWorkbasket, WorkbasketImpl workbasketImplToUpdate) throws ConcurrencyException {

lib/taskana-core/src/test/java/acceptance/report/ProvideTimestampReportAccTest.java

@@ -20,7 +20,7 @@ import pro.taskana.monitor.api.reports.item.TimestampQueryItem;
 import pro.taskana.monitor.api.reports.row.SingleRow;
 import pro.taskana.monitor.api.reports.row.TimestampRow;
 
-/** Test class for {@link TimestampReport}. */
+/** Test class for {@linkplain TimestampReport}. */
 @ExtendWith(JaasExtension.class)
 class ProvideTimestampReportAccTest extends AbstractReportAccTest {
 

lib/taskana-core/src/test/java/acceptance/report/ReportTest.java

@@ -18,7 +18,7 @@ import pro.taskana.monitor.api.reports.row.FoldableRow;
 import pro.taskana.monitor.api.reports.row.Row;
 import pro.taskana.monitor.api.reports.row.SingleRow;
 
-/** Tests for {@link Report}. */
+/** Tests for {@linkplain Report}. */
 class ReportTest {
 
   private static final List<TimeIntervalColumnHeader> HEADERS =

rest/taskana-rest-spring/src/main/java/pro/taskana/classification/rest/ClassificationQueryFilterParameter.java

@@ -15,31 +15,31 @@ import pro.taskana.common.rest.QueryParameter;
 public class ClassificationQueryFilterParameter
     implements QueryParameter<ClassificationQuery, Void> {
 
-  /** Filter by the name of the classification. This is an exact match. */
+  /** Filter by the name of the Classification. This is an exact match. */
   @JsonProperty("name")
   private final String[] name;
 
   /**
-   * Filter by the name of the classification. This results in a substring search. (% is appended to
+   * Filter by the name of the Classification. This results in a substring search. (% is appended to
    * the beginning and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("name-like")
   private final String[] nameLike;
 
-  /** Filter by the key of the classification. This is an exact match. */
+  /** Filter by the key of the Classification. This is an exact match. */
   @JsonProperty("key")
   private final String[] key;
 
-  /** Filter by the category of the classification. This is an exact match. */
+  /** Filter by the category of the Classification. This is an exact match. */
   @JsonProperty("category")
   private final String[] category;
 
-  /** Filter by the domain of the classification. This is an exact match. */
+  /** Filter by the domain of the Classification. This is an exact match. */
   @JsonProperty("domain")
   private final String[] domain;
 
-  /** Filter by the type of the classification. This is an exact match. */
+  /** Filter by the type of the Classification. This is an exact match. */
   @JsonProperty("type")
   private final String[] type;
 

rest/taskana-rest-spring/src/main/java/pro/taskana/monitor/rest/ReportFilterParameter.java

@@ -7,11 +7,11 @@ import pro.taskana.task.api.TaskState;
 
 public class ReportFilterParameter {
 
-  /** Determine weather the report should convert the age of the tasks into working days. */
+  /** Determine weather the report should convert the age of the Tasks into working days. */
   @JsonProperty("in-working-days")
   protected final Boolean inWorkingDays;
 
-  /** Filter by workbasket id of the task. This is an exact match. */
+  /** Filter by workbasket id of the Task. This is an exact match. */
   @JsonProperty("workbasket-id")
   protected final String[] workbasketId;
 
@@ -19,275 +19,275 @@ public class ReportFilterParameter {
   @JsonProperty("state")
   protected final TaskState[] state;
 
-  /** Filter by the classification category of the task. This is an exact match. */
+  /** Filter by the classification category of the Task. This is an exact match. */
   @JsonProperty("classification-category")
   protected final String[] classificationCategory;
 
-  /** Filter by domain of the task. This is an exact match. */
+  /** Filter by domain of the Task. This is an exact match. */
   @JsonProperty("domain")
   protected final String[] domain;
 
-  /** Filter by the classification id of the task. This is an exact match. */
+  /** Filter by the classification id of the Task. This is an exact match. */
   @JsonProperty("classification-id")
   protected final String[] classificationId;
 
-  /** Filter by the classification id of the task. This is an exact match. */
+  /** Filter by the classification id of the Task. This is an exact match. */
   @JsonProperty("excluded-classification-id")
   protected final String[] excludedClassificationId;
 
-  /** Filter by the value of the field custom1 of the task. This is an exact match. */
+  /** Filter by the value of the field custom1 of the Task. This is an exact match. */
   @JsonProperty("custom-1")
   protected final String[] custom1;
 
   /**
-   * Filter by the custom1 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom1 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-1-like")
   protected final String[] custom1Like;
 
-  /** Filter out by values of the field custom1 of the task. This is an exact match. */
+  /** Filter out by values of the field custom1 of the Task. This is an exact match. */
   @JsonProperty("custom-1-not-in")
   protected final String[] custom1NotIn;
 
-  /** Filter by the value of the field custom2 of the task. This is an exact match. */
+  /** Filter by the value of the field custom2 of the Task. This is an exact match. */
   @JsonProperty("custom-2")
   protected final String[] custom2;
 
   /**
-   * Filter by the custom2 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom2 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-2-like")
   protected final String[] custom2Like;
 
-  /** Filter out by values of the field custom2 of the task. This is an exact match. */
+  /** Filter out by values of the field custom2 of the Task. This is an exact match. */
   @JsonProperty("custom-2-not-in")
   protected final String[] custom2NotIn;
 
-  /** Filter by the value of the field custom3 of the task. This is an exact match. */
+  /** Filter by the value of the field custom3 of the Task. This is an exact match. */
   @JsonProperty("custom-3")
   protected final String[] custom3;
 
   /**
-   * Filter by the custom3 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom3 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-3-like")
   protected final String[] custom3Like;
 
-  /** Filter out by values of the field custom3 of the task. This is an exact match. */
+  /** Filter out by values of the field custom3 of the Task. This is an exact match. */
   @JsonProperty("custom-3-not-in")
   protected final String[] custom3NotIn;
 
-  /** Filter by the value of the field custom4 of the task. This is an exact match. */
+  /** Filter by the value of the field custom4 of the Task. This is an exact match. */
   @JsonProperty("custom-4")
   protected final String[] custom4;
 
   /**
-   * Filter by the custom4 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom4 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-4-like")
   protected final String[] custom4Like;
 
-  /** Filter out by values of the field custom4 of the task. This is an exact match. */
+  /** Filter out by values of the field custom4 of the Task. This is an exact match. */
   @JsonProperty("custom-4-not-in")
   protected final String[] custom4NotIn;
 
-  /** Filter by the value of the field custom5 of the task. This is an exact match. */
+  /** Filter by the value of the field custom5 of the Task. This is an exact match. */
   @JsonProperty("custom-5")
   protected final String[] custom5;
 
   /**
-   * Filter by the custom5 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom5 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-5-like")
   protected final String[] custom5Like;
 
-  /** Filter out by values of the field custom5 of the task. This is an exact match. */
+  /** Filter out by values of the field custom5 of the Task. This is an exact match. */
   @JsonProperty("custom-5-not-in")
   protected final String[] custom5NotIn;
 
-  /** Filter by the value of the field custom6 of the task. This is an exact match. */
+  /** Filter by the value of the field custom6 of the Task. This is an exact match. */
   @JsonProperty("custom-6")
   protected final String[] custom6;
 
   /**
-   * Filter by the custom6 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom6 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-6-like")
   protected final String[] custom6Like;
 
-  /** Filter out by values of the field custom6 of the task. This is an exact match. */
+  /** Filter out by values of the field custom6 of the Task. This is an exact match. */
   @JsonProperty("custom-6-not-in")
   protected final String[] custom6NotIn;
 
-  /** Filter by the value of the field custom7 of the task. This is an exact match. */
+  /** Filter by the value of the field custom7 of the Task. This is an exact match. */
   @JsonProperty("custom-7")
   protected final String[] custom7;
 
   /**
-   * Filter by the custom7 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom7 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-7-like")
   protected final String[] custom7Like;
 
-  /** Filter out by values of the field custom7 of the task. This is an exact match. */
+  /** Filter out by values of the field custom7 of the Task. This is an exact match. */
   @JsonProperty("custom-7-not-in")
   protected final String[] custom7NotIn;
 
-  /** Filter by the value of the field custom8 of the task. This is an exact match. */
+  /** Filter by the value of the field custom8 of the Task. This is an exact match. */
   @JsonProperty("custom-8")
   protected final String[] custom8;
 
   /**
-   * Filter by the custom8 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom8 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-8-like")
   protected final String[] custom8Like;
 
-  /** Filter out by values of the field custom8 of the task. This is an exact match. */
+  /** Filter out by values of the field custom8 of the Task. This is an exact match. */
   @JsonProperty("custom-8-not-in")
   protected final String[] custom8NotIn;
 
-  /** Filter by the value of the field custom9 of the task. This is an exact match. */
+  /** Filter by the value of the field custom9 of the Task. This is an exact match. */
   @JsonProperty("custom-9")
   protected final String[] custom9;
 
   /**
-   * Filter by the custom9 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom9 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-9-like")
   protected final String[] custom9Like;
 
-  /** Filter out by values of the field custom9 of the task. This is an exact match. */
+  /** Filter out by values of the field custom9 of the Task. This is an exact match. */
   @JsonProperty("custom-9-not-in")
   protected final String[] custom9NotIn;
 
-  /** Filter by the value of the field custom10 of the task. This is an exact match. */
+  /** Filter by the value of the field custom10 of the Task. This is an exact match. */
   @JsonProperty("custom-10")
   protected final String[] custom10;
 
   /**
-   * Filter by the custom10 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom10 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-10-like")
   protected final String[] custom10Like;
 
-  /** Filter out by values of the field custom10 of the task. This is an exact match. */
+  /** Filter out by values of the field custom10 of the Task. This is an exact match. */
   @JsonProperty("custom-10-not-in")
   protected final String[] custom10NotIn;
 
-  /** Filter by the value of the field custom11 of the task. This is an exact match. */
+  /** Filter by the value of the field custom11 of the Task. This is an exact match. */
   @JsonProperty("custom-11")
   protected final String[] custom11;
 
   /**
-   * Filter by the custom11 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom11 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-11-like")
   protected final String[] custom11Like;
 
-  /** Filter out by values of the field custom11 of the task. This is an exact match. */
+  /** Filter out by values of the field custom11 of the Task. This is an exact match. */
   @JsonProperty("custom-11-not-in")
   protected final String[] custom11NotIn;
 
-  /** Filter by the value of the field custom12 of the task. This is an exact match. */
+  /** Filter by the value of the field custom12 of the Task. This is an exact match. */
   @JsonProperty("custom-12")
   protected final String[] custom12;
 
   /**
-   * Filter by the custom12 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom12 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-12-like")
   protected final String[] custom12Like;
 
-  /** Filter out by values of the field custom12 of the task. This is an exact match. */
+  /** Filter out by values of the field custom12 of the Task. This is an exact match. */
   @JsonProperty("custom-12-not-in")
   protected final String[] custom12NotIn;
 
-  /** Filter by the value of the field custom13 of the task. This is an exact match. */
+  /** Filter by the value of the field custom13 of the Task. This is an exact match. */
   @JsonProperty("custom-13")
   protected final String[] custom13;
 
   /**
-   * Filter by the custom13 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom13 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-13-like")
   protected final String[] custom13Like;
 
-  /** Filter out by values of the field custom13 of the task. This is an exact match. */
+  /** Filter out by values of the field custom13 of the Task. This is an exact match. */
   @JsonProperty("custom-13-not-in")
   protected final String[] custom13NotIn;
 
-  /** Filter by the value of the field custom14 of the task. This is an exact match. */
+  /** Filter by the value of the field custom14 of the Task. This is an exact match. */
   @JsonProperty("custom-14")
   protected final String[] custom14;
 
   /**
-   * Filter by the custom14 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom14 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-14-like")
   protected final String[] custom14Like;
 
-  /** Filter out by values of the field custom14 of the task. This is an exact match. */
+  /** Filter out by values of the field custom14 of the Task. This is an exact match. */
   @JsonProperty("custom-14-not-in")
   protected final String[] custom14NotIn;
 
-  /** Filter by the value of the field custom15 of the task. This is an exact match. */
+  /** Filter by the value of the field custom15 of the Task. This is an exact match. */
   @JsonProperty("custom-15")
   protected final String[] custom15;
 
   /**
-   * Filter by the custom15 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom15 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-15-like")
   protected final String[] custom15Like;
 
-  /** Filter out by values of the field custom15 of the task. This is an exact match. */
+  /** Filter out by values of the field custom15 of the Task. This is an exact match. */
   @JsonProperty("custom-15-not-in")
   protected final String[] custom15NotIn;
 
-  /** Filter by the value of the field custom16 of the task. This is an exact match. */
+  /** Filter by the value of the field custom16 of the Task. This is an exact match. */
   @JsonProperty("custom-16")
   protected final String[] custom16;
 
   /**
-   * Filter by the custom16 field of the task. This results in a substring search (% is appended to
+   * Filter by the custom16 field of the Task. This results in a substring search (% is appended to
    * the front and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("custom-16-like")
   protected final String[] custom16Like;
 
-  /** Filter out by values of the field custom16 of the task. This is an exact match. */
+  /** Filter out by values of the field custom16 of the Task. This is an exact match. */
   @JsonProperty("custom-16-not-in")
   protected final String[] custom16NotIn;
 

rest/taskana-rest-spring/src/main/java/pro/taskana/workbasket/rest/WorkbasketAccessItemQueryFilterParameter.java

@@ -10,12 +10,12 @@ import pro.taskana.workbasket.api.WorkbasketAccessItemQuery;
 public class WorkbasketAccessItemQueryFilterParameter
     implements QueryParameter<WorkbasketAccessItemQuery, Void> {
 
-  /** Filter by the key of the workbasket. This is an exact match. */
+  /** Filter by the key of the Workbasket. This is an exact match. */
   @JsonProperty("workbasket-key")
   private final String[] workbasketKey;
 
   /**
-   * Filter by the key of the workbasket. This results in a substring search.. (% is appended to the
+   * Filter by the key of the Workbasket. This results in a substring search.. (% is appended to the
    * beginning and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */

rest/taskana-rest-spring/src/main/java/pro/taskana/workbasket/rest/WorkbasketQueryFilterParameter.java

@@ -11,36 +11,36 @@ import pro.taskana.workbasket.api.WorkbasketType;
 
 public class WorkbasketQueryFilterParameter implements QueryParameter<WorkbasketQuery, Void> {
 
-  /** Filter by the name of the workbasket. This is an exact match. */
+  /** Filter by the name of the Workbasket. This is an exact match. */
   @JsonProperty("name")
   private final String[] name;
 
   /**
-   * Filter by the name of the workbasket. This results in a substring search. (% is appended to the
+   * Filter by the name of the Workbasket. This results in a substring search. (% is appended to the
    * beginning and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("name-like")
   private final String[] nameLike;
 
-  /** Filter by the key of the workbasket. This is an exact match. */
+  /** Filter by the key of the Workbasket. This is an exact match. */
   @JsonProperty("key")
   private final String[] key;
 
   /**
-   * Filter by the key of the workbasket. This results in a substring search.. (% is appended to the
+   * Filter by the key of the Workbasket. This results in a substring search.. (% is appended to the
    * beginning and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
   @JsonProperty("key-like")
   private final String[] keyLike;
 
-  /** Filter by the owner of the workbasket. This is an exact match. */
+  /** Filter by the owner of the Workbasket. This is an exact match. */
   @JsonProperty("owner")
   private final String[] owner;
 
   /**
-   * Filter by the owner of the workbasket. This results in a substring search.. (% is appended to
+   * Filter by the owner of the Workbasket. This results in a substring search.. (% is appended to
    * the beginning and end of the requested value). Further SQL "LIKE" wildcard characters will be
    * resolved correctly.
    */
@@ -48,22 +48,22 @@ public class WorkbasketQueryFilterParameter implements QueryParameter<Workbasket
   private final String[] ownerLike;
 
   /**
-   * Filter by the description of the workbasket. This results in a substring search.. (% is
+   * Filter by the description of the Workbasket. This results in a substring search.. (% is
    * appended to the beginning and end of the requested value). Further SQL "LIKE" wildcard
    * characters will be resolved correctly.
    */
   @JsonProperty("description-like")
   private final String[] descriptionLike;
 
-  /** Filter by the domain of the workbasket. This is an exact match. */
+  /** Filter by the domain of the Workbasket. This is an exact match. */
   @JsonProperty("domain")
   private final String[] domain;
 
-  /** Filter by the type of the workbasket. This is an exact match. */
+  /** Filter by the type of the Workbasket. This is an exact match. */
   @JsonProperty("type")
   private final WorkbasketType[] type;
 
-  /** Filter by the required permission for the workbasket. */
+  /** Filter by the required permission for the Workbasket. */
   @JsonProperty("required-permission")
   private final WorkbasketPermission requiredPermissions;