DS-4107 Improve javadocs

dspace-spring-rest/src/main/java/org/dspace/app/rest/converter/MetadataConverter.java

@@ -29,6 +29,9 @@ import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.core.convert.converter.Converter;
 import org.springframework.stereotype.Component;
 
+/**
+ * Converter to translate between lists of domain {@link MetadataValue}s and {@link MetadataRest} representations.
+ */
 @Component
 public class MetadataConverter implements Converter<List<MetadataValue>, MetadataRest> {
 
@@ -38,6 +41,12 @@ public class MetadataConverter implements Converter<List<MetadataValue>, Metadat
     @Autowired
     private MetadataValueConverter valueConverter;
 
+    /**
+     * Gets a rest representation of the given list of domain metadata values.
+     *
+     * @param metadataValueList the domain values.
+     * @return the rest representation.
+     */
     @Override
     public MetadataRest convert(List<MetadataValue> metadataValueList) {
         // Convert each value to a DTO while retaining place order in a map of key -> SortedSet
@@ -64,11 +73,11 @@ public class MetadataConverter implements Converter<List<MetadataValue>, Metadat
     }
 
     /**
-     * Completely replaces the metadata in the given dso.
+     * Sets a DSpace object's domain metadata values from a rest representation.
      *
      * @param context the context to use.
-     * @param dso the dso whose metadata should be updated.
+     * @param dso the DSpace object.
-     * @param metadataRest the new metadata.
+     * @param metadataRest the rest representation of the new metadata.
      * @throws SQLException if a database error occurs.
      * @throws AuthorizeException if an authorization error occurs.
      */

dspace-spring-rest/src/main/java/org/dspace/app/rest/converter/MetadataValueConverter.java

@@ -12,17 +12,26 @@ import org.dspace.content.MetadataValue;
 import org.springframework.core.convert.converter.Converter;
 import org.springframework.stereotype.Component;
 
+/**
+ * Converter to translate between domain {@link MetadataValue}s and {@link MetadataValueRest} representations.
+ */
 @Component
 public class MetadataValueConverter implements Converter<MetadataValue, MetadataValueRest> {
 
+    /**
+     * Gets a rest representation of the given domain metadata value.
+     *
+     * @param metadataValue the domain value.
+     * @return the rest representation.
+     */
     @Override
-    public MetadataValueRest convert(MetadataValue model) {
+    public MetadataValueRest convert(MetadataValue metadataValue) {
         MetadataValueRest metadataValueRest = new MetadataValueRest();
-        metadataValueRest.setValue(model.getValue());
+        metadataValueRest.setValue(metadataValue.getValue());
-        metadataValueRest.setLanguage(model.getLanguage());
+        metadataValueRest.setLanguage(metadataValue.getLanguage());
-        metadataValueRest.setAuthority(model.getAuthority());
+        metadataValueRest.setAuthority(metadataValue.getAuthority());
-        metadataValueRest.setConfidence(model.getConfidence());
+        metadataValueRest.setConfidence(metadataValue.getConfidence());
-        metadataValueRest.setPlace(model.getPlace());
+        metadataValueRest.setPlace(metadataValue.getPlace());
         return metadataValueRest;
     }
 }

dspace-spring-rest/src/main/java/org/dspace/app/rest/model/DSpaceObjectRest.java

@@ -51,6 +51,11 @@ public abstract class DSpaceObjectRest extends BaseObjectRest<String> {
         this.handle = handle;
     }
 
+    /**
+     * Gets the rest representation of all metadata of the DSpace object.
+     *
+     * @return the metadata.
+     */
     public MetadataRest getMetadata() {
         return metadata;
     }

dspace-spring-rest/src/main/java/org/dspace/app/rest/model/MetadataRest.java

@@ -15,11 +15,19 @@ import java.util.TreeMap;
 import com.fasterxml.jackson.annotation.JsonAnyGetter;
 import com.fasterxml.jackson.annotation.JsonAnySetter;
 
+/**
+ * Rest representation of a map of metadata keys to ordered lists of values.
+ */
 public class MetadataRest {
 
     @JsonAnySetter
     private SortedMap<String, List<MetadataValueRest>> map = new TreeMap();
 
+    /**
+     * Gets the map.
+     *
+     * @return the map of keys to ordered values.
+     */
     @JsonAnyGetter
     public SortedMap<String, List<MetadataValueRest>> getMap() {
         return map;
@@ -30,9 +38,9 @@ public class MetadataRest {
      *
      * @param key the key.
      * @param values the values. The values will be ordered according to their {@code place} value, if
-     *               nonnegative. Values that are negative (the default is -1) are assume to be non-explicitly
+     *               nonnegative. Values that are negative (the default is -1) are assumed to be non-explicitly
-     *               set and will will be ordered at the end of the list, after the last value with an order,
+     *               set and will will be ordered at the end of any explicitly ordered values, in the order
-     *               in the order they are passed to this method.
+     *               they are passed to this method.
      * @return this instance, to support chaining calls for easy initialization.
      */
     public MetadataRest put(String key, MetadataValueRest... values) {

dspace-spring-rest/src/main/java/org/dspace/app/rest/model/MetadataValueRest.java

@@ -7,7 +7,10 @@
  */
 package org.dspace.app.rest.model;
 
+import java.util.List;
+
 import com.fasterxml.jackson.annotation.JsonIgnore;
+import org.dspace.app.rest.converter.MetadataConverter;
 
 /**
  * An embeddable representation of the Metadata to use in with DSpace REST
@@ -25,6 +28,16 @@ public class MetadataValueRest {
 
     int confidence;
 
+    /**
+     * The order of this metadata value with respect to others in the same DSO with the same key.
+     *
+     * In the REST representation, all values of the same key are given as a json array that expresses
+     * their relative order, so there is no need to expose the exact numeric value publicly. The numeric
+     * value is only used at this level to ensure the intended order is respected when converting to/from json.
+     *
+     * @see MetadataConverter#convert(List)
+     * @see MetadataRest#put(String, MetadataValueRest...)
+     */
     @JsonIgnore
     int place = -1;
 

dspace-spring-rest/src/test/java/org/dspace/app/rest/matcher/MetadataMatcher.java

@@ -13,14 +13,32 @@ import static org.hamcrest.Matchers.is;
 
 import org.hamcrest.Matcher;
 
+/**
+ * Utility class to provide convenient matchers for metadata.
+ */
 public class MetadataMatcher {
 
     private MetadataMatcher() { }
 
+    /**
+     * Gets a matcher to ensure a given value is present among all values for a given metadata key.
+     *
+     * @param key the metadata key.
+     * @param value the value that must be present.
+     * @return the matcher.
+     */
     public static Matcher<? super Object> matchMetadata(String key, String value) {
         return hasJsonPath("$.['" + key + "'][*].value", contains(value));
     }
 
+    /**
+     * Gets a matcher to ensure a given value is present at a specific position in the list of values for a given key.
+     *
+     * @param key the metadata key.
+     * @param value the value that must be present.
+     * @param position the position it must be present at.
+     * @return the matcher.
+     */
     public static Matcher<? super Object> matchMetadata(String key, String value, int position) {
         return hasJsonPath("$.['" + key + "'][" + position + "].value", is(value));
     }