Finish documenting DOIService.

dspace-api/src/main/java/org/dspace/identifier/service/DOIService.java

@@ -17,26 +17,65 @@ import org.dspace.identifier.IdentifierException;
 import org.dspace.identifier.doi.DOIIdentifierException;
 
 /**
- * Service interface class for the DOI object.
+ * Service interface class for the {@link DOI} object.
- * The implementation of this class is responsible for all business logic calls for the DOI object and is autowired
+ * The implementation of this class is responsible for all business logic calls
- * by spring
+ * for the {@link DOI} object and is autowired by Spring.
  *
  * @author kevinvandevelde at atmire.com
  */
 public interface DOIService {
 
+    /**
+     * Update a DOI in storage.
+     *
+     * @param context current DSpace session.
+     * @param doi the DOI to persist.
+     * @throws SQLException passed through.
+     */
     public void update(Context context, DOI doi) throws SQLException;
 
+    /**
+     * Create a new DOI in storage.
+     *
+     * @param context current DSpace session.
+     * @return the new DOI.
+     * @throws SQLException passed through.
+     */
     public DOI create(Context context) throws SQLException;
 
+    /**
+     * Find a specific DOI in storage.
+     *
+     * @param context current DSpace session.
+     * @param doi string representation of the DOI.
+     * @return the DOI object found.
+     * @throws SQLException passed through, can mean none found.
+     */
     public DOI findByDoi(Context context, String doi) throws SQLException;
 
+    /**
+     * Find the DOI assigned to a given DSpace Object.
+     *
+     * @param context current DSpace session.
+     * @param dso The DSpace Object.
+     * @return the DSO's DOI.
+     * @throws SQLException passed through.
+     */
     public DOI findDOIByDSpaceObject(Context context, DSpaceObject dso) throws SQLException;
 
+    /**
+     * Find the DOI assigned to a given DSpace Object, unless it has one of a
+     * given set of statuses.
+     *
+     * @param context current DSpace context.
+     * @param dso the DSpace Object.
+     * @param statusToExclude uninteresting statuses.
+     * @return the DSO's DOI.
+     * @throws SQLException passed through.
+     */
     public DOI findDOIByDSpaceObject(Context context, DSpaceObject dso, List<Integer> statusToExclude)
         throws SQLException;
 
-
     /**
      * This method helps to convert a DOI into a URL. It takes DOIs in one of
      * the following formats  and returns it as URL (f.e.
@@ -55,6 +94,12 @@ public interface DOIService {
     public String DOIToExternalForm(String identifier)
         throws IdentifierException;
 
+    /**
+     * Convert an HTTP DOI URL (https://doi.org/10.something) to a "doi:" URI.
+     * @param identifier HTTP URL
+     * @return DOI URI
+     * @throws DOIIdentifierException if {@link identifier} is not recognizable.
+     */
     public String DOIFromExternalFormat(String identifier)
         throws DOIIdentifierException;
 
@@ -65,15 +110,23 @@ public interface DOIService {
      *                   f.e. 10.123/456, doi:10.123/456, http://dx.doi.org/10.123/456.
      * @return Given Identifier with DOI-Scheme, f.e. doi:10.123/456.
      * @throws IllegalArgumentException If identifier is empty or null.
-     * @throws org.dspace.identifier.doi.DOIIdentifierException If DOI could not be recognized.
+     * @throws DOIIdentifierException   If DOI could not be recognized.
      */
     public String formatIdentifier(String identifier)
         throws DOIIdentifierException;
 
+    /**
+     * Find all DOIs that have one of a given set of statuses.
+     * @param context current DSpace session.
+     * @param statuses desired statuses.
+     * @return all DOIs having any of the given statuses.
+     * @throws SQLException passed through.
+     */
     public List<DOI> getDOIsByStatus(Context context, List<Integer> statuses) throws SQLException;
 
     /**
-     * Find all DOIs that are similar to the specified pattern ant not in the specified states.
+     * Find all DOIs that are similar to the specified pattern and not in the
+     * specified states.
      *
      * @param context      DSpace context
      * @param doiPattern   The pattern, e.g. "10.5072/123.%"