CST-5249 add javadoc

dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionEvidence.java

@@ -8,7 +8,9 @@
 package org.dspace.app.suggestion;
 
 /**
- * 
+ * This DTO class is returned by an {@link org.dspace.app.suggestion.openaire.EvidenceScorer} to model the concept of
+ * an evidence / fact that has been used to evaluate the precision of a suggestion increasing or decreasing the score
+ * of the suggestion.
  *
  * @author Andrea Bollini (andrea.bollini at 4science.it)
  */
@@ -17,7 +19,7 @@ public class SuggestionEvidence {
     /** name of the evidence */
     private String name;
 
-    /** score of the evidence */
+    /** positive or negative value to influence the score of the suggestion */
     private double score;
 
     /** additional notes */

dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionSource.java

@@ -8,7 +8,8 @@
 package org.dspace.app.suggestion;
 
 /**
- * 
+ * This DTO class is used to pass around the number of items interested by suggestion provided by a specific source
+ * (i.e. openaire)
  *
  * @author Andrea Bollini (andrea.bollini at 4science.it)
  */

dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionTarget.java

@@ -10,7 +10,8 @@
 import org.dspace.content.Item;
 
 /**
- * 
+ * This DTO class is used to pass around the number of suggestions available from a specific source for a target
+ * repository item
  *
  * @author Andrea Bollini (andrea.bollini at 4science.it)
  */
@@ -29,7 +30,7 @@ public SuggestionTarget() {
     }
 
     /**
-     * Wrap a target person into a suggestion target.
+     * Wrap a target repository item (usually a person item) into a suggestion target.
      * 
      * @param item must be not null
      */

dspace-api/src/main/java/org/dspace/app/suggestion/openaire/DateScorer.java

@@ -8,12 +8,15 @@
 package org.dspace.app.suggestion.openaire;
 
 import java.util.Calendar;
+import java.util.Collections;
 import java.util.Date;
 import java.util.GregorianCalendar;
+import java.util.List;
 
 import org.dspace.app.suggestion.SuggestionEvidence;
 import org.dspace.app.suggestion.SuggestionUtils;
 import org.dspace.content.Item;
+import org.dspace.content.MetadataValue;
 import org.dspace.content.service.ItemService;
 import org.dspace.external.model.ExternalDataObject;
 import org.dspace.util.MultiFormatDateParser;
@@ -28,23 +31,60 @@
  */
 public class DateScorer implements EvidenceScorer {
 
+    /**
+     * if available it should contains the metadata field key in the form (schema.element[.qualifier]) that contains
+     * the birth date of the researcher
+     */
     private String birthDateMetadata;
 
-    //private String educationDateMetadata;
+    /**
+     * if available it should contains the metadata field key in the form (schema.element[.qualifier]) that contains
+     * the date of graduation of the researcher. If the metadata has multiple values the min will be used
+     */
+    private String educationDateMetadata;
 
+    /**
+     * Force the scorer to reject any publication that was issued before the specified date
+     */
     private String minDateMetadata;
 
+    /**
+     * Force the scorer to reject any publication that was issued after the specified date
+     */
     private String maxDateMetadata;
 
+    /**
+     * The minimal age that is expected for a researcher to be a potential author of a scholarly contribution
+     * (i.e. the minimum delta from the publication date and the birth date)
+     */
     private int birthDateDelta = 20;
+
+    /**
+     * The maximum age that is expected for a researcher to be a potential author of a scholarly contribution
+     * (i.e. the maximum delta from the publication date and the birth date)
+     */
     private int birthDateRange = 50;
 
+    /**
+     * The number of year from/before the graduation that is expected for a researcher to be a potential
+     * author of a scholarly contribution (i.e. the minimum delta from the publication date and the first
+     * graduation date)
+     */
     private int educationDateDelta = -3;
+
+    /**
+     * The maximum scientific longevity that is expected for a researcher from its graduation to be a potential
+     * author of a scholarly contribution (i.e. the maximum delta from the publication date and the first
+     * graduation date)
+     */
     private int educationDateRange = 50;
 
     @Autowired
     private ItemService itemService;
 
+    /**
+     * the metadata used in the publication to track the publication date (i.e. dc.date.issued)
+     */
     private String publicationDateMetadata;
 
     public void setItemService(ItemService itemService) {
@@ -58,15 +98,14 @@ public void setBirthDateMetadata(String birthDate) {
     public String getBirthDateMetadata() {
         return birthDateMetadata;
     }
-    /*
+
     public void setEducationDateMetadata(String educationDate) {
         this.educationDateMetadata = educationDate;
     }
 
     public String getEducationDateMetadata() {
         return educationDateMetadata;
     }
-    */
 
     public void setBirthDateDelta(int birthDateDelta) {
         this.birthDateDelta = birthDateDelta;
@@ -99,6 +138,7 @@ public void setPublicationDateMetadata(String publicationDateMetadata) {
     /**
      * Method which is responsible to evaluate ImportRecord based on the publication date.
      * ImportRecords which have a date outside the defined or calculated expected range will be discarded.
+     * {@link DateScorer#birthDateMetadata}, {@link DateScorer#educationDateMetadata}
      * 
      * @param importRecord the ExternalDataObject to check
      * @param researcher DSpace item
@@ -153,14 +193,8 @@ private Integer[] calculateRange(Item researcher) {
         } else {
             String birthDateStr = getSingleValue(researcher, birthDateMetadata);
             int birthDateYear = getYear(birthDateStr);
-            int educationDateYear = -1;
-            /*
-            getListMetadataValues(researcher, educationDateMetadata)
-              .stream()
-              .mapToInt(x -> getYear(x.getValue()))
-              .filter(d -> d > 0)
-              .min().orElse(-1);
-            */
+            int educationDateYear = getListMetadataValues(researcher, educationDateMetadata).stream()
+                    .mapToInt(x -> getYear(x.getValue())).filter(d -> d > 0).min().orElse(-1);
             if (educationDateYear > 0) {
                 return new Integer[] {
                     minYear > 0 ? minYear : educationDateYear + educationDateDelta,
@@ -177,15 +211,13 @@ private Integer[] calculateRange(Item researcher) {
         }
     }
 
-    /*
     private List<MetadataValue> getListMetadataValues(Item researcher, String metadataKey) {
         if (metadataKey != null) {
             return itemService.getMetadataByMetadataString(researcher, metadataKey);
         } else {
             return Collections.EMPTY_LIST;
         }
     }
-    */
 
     private String getSingleValue(Item researcher, String metadataKey) {
         if (metadataKey != null) {