secureCodeBox#121 Add Missing JavaDoc

Signed-off-by: Sven Strittmatter <[email protected]>

src/main/java/io/securecodebox/persistence/defectdojo/model/Model.java

@@ -6,5 +6,15 @@
  * Interface for all models
  */
 public interface Model {
+  /**
+   * Compares this model with the given query parameters
+   * <p>
+   *   The given query parameters are name value pairs, e.g.:
+   * </p>
+   *
+   * TODO: Should we annotate queryParams with {@code @NonNull}?
+   * @param queryParams may be {@code null}
+   * @return {@code true} if equal, elas {@code false}
+   */
   boolean equalsQueryString(Map<String, Object> queryParams);
 }

src/main/java/io/securecodebox/persistence/defectdojo/model/QueryParamsComparator.java

@@ -14,18 +14,55 @@
  * </p>
  */
 final class QueryParamsComparator {
-
+  /**
+   * Query parameter name for id
+   */
   static final String QUERY_PARAM_KEY_FOR_ID = "id";
+  /**
+   * Query parameter name for name
+   */
   static final String QUERY_PARAM_KEY_FOR_NAME = "name";
 
+  /**
+   * Hidden for pure static helper class
+   */
   private QueryParamsComparator() {
     super();
   }
 
+  /**
+   * Determines whether the given object is {@code null} or not
+   *
+   * @param o maybe {@code null}
+   * @return {@code true} if {@code o} is {@code null}, else {@code false}
+   */
   static boolean isNull(Object o) {
     return o == null;
   }
 
+  /**
+   * Determines whether the {@link HasId id} of the given model object is equal the given {@link #QUERY_PARAM_KEY_FOR_ID id}
+   * <p>
+   * Example:
+   * </p>
+   * <pre>
+   *   {@code
+   *    final var model = ...
+   *    final var queryParams = new HashMap<String, Object>();
+   *    queryParams.put(QueryParamsComparator.QUERY_PARAM_KEY_FOR_ID, 42);
+   *
+   *    if (QueryParamsComparator.isIdEqual(model, queryParams)) {
+   *      ...
+   *    }
+   *   }
+   * </pre>
+   * <p>
+   * TODO: What about type conversions? The id is a long in the models, but it may be a string in the map. Should it be treated as equal (42 == "42")?
+   *
+   * @param model       may be {@code null}
+   * @param queryParams may be {@code null}
+   * @return {@code true} id id is equal, else {@code false}
+   */
   static boolean isIdEqual(HasId model, Map<String, Object> queryParams) {
     if (isNull(model)) {
       return false;
@@ -46,6 +83,28 @@ static boolean isIdEqual(HasId model, Map<String, Object> queryParams) {
     return queryParams.get(QUERY_PARAM_KEY_FOR_ID).equals(model.getId());
   }
 
+  /**
+   * Determines whether the {@link HasName name} of the given model object is equal the given {@link #QUERY_PARAM_KEY_FOR_NAME name}
+   * <p>
+   * Example:
+   * </p>
+   * <pre>
+   *   {@code
+   *    final var model = ...
+   *    final var queryParams = new HashMap<String, Object>();
+   *    queryParams.put(QueryParamsComparator.QUERY_PARAM_KEY_FOR_NAME, "foo");
+   *
+   *    if (QueryParamsComparator.isNameEqual(model, queryParams)) {
+   *      ...
+   *    }
+   *   }
+   * </pre>
+   * <p>
+   *
+   * @param model       may be {@code null}
+   * @param queryParams may be {@code null}
+   * @return {@code true} if name is equal, else {@code false}
+   */
   static boolean isNameEqual(HasName model, Map<String, Object> queryParams) {
     if (isNull(model)) {
       return false;

src/main/java/io/securecodebox/persistence/defectdojo/service/GenericDefectDojoService.java

@@ -37,6 +37,11 @@
 import java.net.URISyntaxException;
 import java.util.*;
 
+/**
+ * Generic base implementation with common functionality shared by services
+ *
+ * @param <T> type of model the service handles
+ */
 @Slf4j
 abstract class GenericDefectDojoService<T extends Model> implements DefectDojoService<T> {
   private static final String API_PREFIX = "/api/v2/";