Clean up remaining doclint errors and warnings.

Throughout dspace-sword I was baffled by the validation aspect, so
you'll see lots of "UNKNOWN.  PLEASE DOCUMENT." that I wrote just to
shut doclint up.  If you know how this works, please amend my
placeholders.

dspace-api/src/main/java/org/dspace/app/util/DCInput.java

@@ -94,6 +94,7 @@ public class DCInput
      * a HashMap
      * 
      * @param fieldMap
+     *     named field values.
      *     
      * @param listMap
      *     value-pairs map, computed from the forms definition XML file

dspace-api/src/main/java/org/dspace/app/util/DCInputSet.java

@@ -120,7 +120,7 @@ public class DCInputSet
      * Does the current input set define the named field?
      * Scan through every field in every page of the input set
      *
-     * @param fieldName
+     * @param fieldName selects the field.
      * @return true if the current set has the named field
      */
     public boolean isFieldPresent(String fieldName)

dspace-api/src/main/java/org/dspace/authority/AuthorityValue.java

@@ -242,8 +242,9 @@ public class AuthorityValue {
     }
 
     /**
-     * Provides a string that will allow this AuthorityType to be recognized and provides information to create a new instance to be created using public AuthorityValue newInstance(String info).
+     * Provides a string that will allow this AuthorityType to be recognized and
-     * See the implementation of {@link com.atmire.org.dspace.authority.AuthorityValueGenerator#generateRaw(java.lang.String, java.lang.String) AuthorityValueGenerator#generateRaw(java.lang.String, java.lang.String)} for more details.
+     * provides information to create a new instance to be created using {@link #newInstance(String)}.
+     * See the implementation of {@link org.dspace.authority.AuthorityValueServiceImpl#generateRaw(java.lang.String, java.lang.String, java.lang.String)} for more details.
      * @return see {@link org.dspace.authority.service.AuthorityValueService#GENERATE AuthorityValueService.GENERATE}
      */
     public String generateString() {

dspace-api/src/main/java/org/dspace/content/dao/DSpaceObjectDAO.java

@@ -15,7 +15,7 @@ import org.dspace.core.GenericDAO;
  * All DSpaceObject DAO classes should implement this class since it ensures that the T object is of type DSpaceObject
  *
  * @author kevinvandevelde at atmire.com
- * @param <T>
+ * @param <T> some implementation of DSpaceObject
  */
 public interface DSpaceObjectDAO<T extends DSpaceObject> extends GenericDAO<T> {
 }

dspace-api/src/main/java/org/dspace/content/dao/DSpaceObjectLegacySupportDAO.java

@@ -17,7 +17,7 @@ import java.sql.SQLException;
  * to identify DSpaceObjects prior to DSpace 6.0
  *
  * @author kevinvandevelde at atmire.com
- * @param <T>
+ * @param <T> some implementation of DSpaceObject
  */
 public interface DSpaceObjectLegacySupportDAO<T extends DSpaceObject> extends DSpaceObjectDAO<T> {
 

dspace-api/src/main/java/org/dspace/core/Context.java

@@ -631,9 +631,7 @@ public class Context
 
 
     /**
-     * Returns the size of the cache of all object that have been read from the database so far. A larger number
+     * Returns the size of the cache of all object that have been read from the database so far.
-     * means that more memory is consumed by the cache. This also has a negative impact on the query performance. In
-     * that case you should consider clearing the cache (see {@link Context#clearCache() clearCache}).
      *
      * @return connection cache size
      * @throws SQLException When connecting to the active cache fails.

dspace-api/src/main/java/org/dspace/core/DBConnection.java

@@ -48,8 +48,9 @@ public interface DBConnection<T> {
 
     /**
      * Reload a DSpace object from the database. This will make sure the object is valid and stored in the cache.
+     * @param <E> the type of entity.
      * @param entity The DSpace object to reload
-     * @return 
+     * @return the reloaded entity.
      * @throws SQLException
      *     An exception that provides information on a database access error or other errors.
      */
@@ -57,6 +58,7 @@ public interface DBConnection<T> {
 
     /**
      * Remove a DSpace object from the cache when batch processing a large number of objects.
+     * @param <E> the type of entity.
      * @param entity The DSpace object to reload
      * @throws SQLException
      *     An exception that provides information on a database access error or other errors.

dspace-api/src/main/java/org/dspace/core/LegacyPluginServiceImpl.java

@@ -127,7 +127,7 @@ public class LegacyPluginServiceImpl implements PluginService
      *
      * @param interfaceClass interface Class object
      * @return instance of plugin
-     * @throws PluginConfigurationError
+     * @throws PluginConfigurationError if no matching singleton plugin is configured.
      */
     @Override
     public Object getSinglePlugin(Class interfaceClass)

dspace-api/src/main/java/org/dspace/discovery/SearchService.java

@@ -132,10 +132,10 @@ public interface SearchService {
     String createLocationQueryForAdministrableItems(Context context) throws SQLException;
 
     /**
-     * Transforms the metadata field of the given sort configuration into the indexed field which we can then use in our solr queries
+     * Transforms the metadata field of the given sort configuration into the indexed field which we can then use in our Solr queries.
      *
      * @param metadataField the metadata field
-     * @param type @see org.dspace.discovery.configuration.DiscoveryConfigurationParameters
+     * @param type see {@link org.dspace.discovery.configuration.DiscoveryConfigurationParameters}
      * @return the indexed field
      */
     String toSortFieldIndex(String metadataField, String type);

dspace-api/src/main/java/org/dspace/eperson/EPerson.java

@@ -104,8 +104,8 @@ public class EPerson extends DSpaceObject implements DSpaceObjectLegacySupport
     /**
      * Return true if this object equals obj, false otherwise.
      * 
-     * @param obj
+     * @param obj another EPerson.
-     * @return true if ResourcePolicy objects are equal
+     * @return true if EPerson objects are equal in ID, email, and full name
      */
     @Override
     public boolean equals(Object obj)

dspace-api/src/main/java/org/dspace/eperson/EPersonCLITool.java

@@ -48,7 +48,7 @@ public class EPersonCLITool {
      *
      * @param argv the command line arguments given
      * @throws ParseException
-     *     Base for Exceptions thrown during parsing of a command-line. {@see org.apache.commons.cli.ParseException}
+     *     Base for Exceptions thrown during parsing of a command-line.
      * @throws SQLException
      *     An exception that provides information on a database access error or other errors.
      * @throws AuthorizeException

dspace-api/src/main/java/org/dspace/eperson/service/SubscribeService.java

@@ -148,7 +148,7 @@ public interface SubscribeService {
      *
      * @param context
      *            DSpace context
-     * @param eperson
+     * @param ePerson
      *            find out if this e-person is subscribed
      * @throws SQLException
      *     An exception that provides information on a database access error or other errors.

dspace-api/src/main/java/org/dspace/event/ConsumerProfile.java

@@ -53,11 +53,11 @@ public class ConsumerProfile
      *            configuration name of the consumer profile
      * @return a new ConsumerProfile; never null.
      * @throws IllegalArgumentException if no class or no filters configured for the specified consumer
-     * @throws ClassNotFoundException
+     * @throws ClassNotFoundException passed through.
      *     
-     * @throws InstantiationException
+     * @throws InstantiationException passed through.
      *     
-     * @throws IllegalAccessException
+     * @throws IllegalAccessException passed through.
      *     
      */
     public static ConsumerProfile makeConsumerProfile(String name)
@@ -73,11 +73,11 @@ public class ConsumerProfile
      * Get class and filters from DSpace Configuration.
      * 
      * @throws IllegalArgumentException if no class or no filters configured for the specified consumer
-     * @throws ClassNotFoundException
+     * @throws ClassNotFoundException passed through.
      *     
-     * @throws InstantiationException
+     * @throws InstantiationException passed through.
      *     
-     * @throws IllegalAccessException
+     * @throws IllegalAccessException passed through.
      *     
      */
     

dspace-api/src/main/java/org/dspace/harvest/HarvestedCollection.java

@@ -94,7 +94,7 @@ public class HarvestedCollection implements ReloadableEntity<Integer>
     /** 
      * A function to set all harvesting-related parameters at once 
      * @param type
-     *     harvest type (TYPE_NONE, TYPE_DMD, TYPE_DMDREF, TYPE_FULL) {@see HarvestedCollection}
+     *     harvest type (TYPE_NONE, TYPE_DMD, TYPE_DMDREF, TYPE_FULL)
      * @param oaiSource
      *     base URL of the OAI-PMH server
      * @param oaiSetId
@@ -113,7 +113,7 @@ public class HarvestedCollection implements ReloadableEntity<Integer>
      * Setters for the appropriate harvesting-related columns
      *
      * @param type
-     *     harvest type (TYPE_NONE, TYPE_DMD, TYPE_DMDREF, TYPE_FULL) {@see HarvestedCollection}
+     *     harvest type (TYPE_NONE, TYPE_DMD, TYPE_DMDREF, TYPE_FULL
      */
     public void setHarvestType(int type) {
         this.harvestType = type;

dspace-api/src/main/java/org/dspace/identifier/DOIIdentifierProvider.java

@@ -34,7 +34,7 @@ import org.springframework.beans.factory.annotation.Required;
  * Provide service for DOIs using DataCite.
  * 
  * <p>This class handles reservation, registration and deletion of DOIs using
- * the direct API from {@link <a href="http://www.datacite.org">DataCite</a>}.
+ * the direct API from <a href="http://www.datacite.org">DataCite</a>.
  * Please pay attention that some members of DataCite offer special services
  * and want their customers to use special APIs. If you are unsure ask your
  * registration agency.</p>

dspace-api/src/main/java/org/dspace/identifier/IdentifierProvider.java

@@ -55,9 +55,6 @@ public abstract class IdentifierProvider {
 
     /**
      * Create and apply an identifier to a DSpaceObject.
-     * If you just mark an identifier for an asynchronous registration, please call
-     * {@link org.dspace.content.DSpaceObject#resetIdentifiersCache()} after its registration. If you register
-     * identifiers directly in this method the IdentifierService will call this method for you.
      * 
      * @param context
      *     The relevant DSpace Context.

dspace-api/src/main/java/org/dspace/importer/external/datamodel/Query.java

@@ -56,9 +56,10 @@ public class Query {
 
     /**
      * Retrieve a parameter as a certain given class
-     * @param key  the key to retrieve the parameter from
+     * @param <T> the type of parameter returned.
-     * @param clazz  The classtype to retrieve. (If no parameter with that class is found, a <tt>null</tt> value is returned
+     * @param key the key to retrieve the parameter from
-     * @return 
+     * @param clazz the type to retrieve. (If no parameter with that class is found, a <tt>null</tt> value is returned.)
+     * @return the selected parameter, or null.
      */
     public <T> T getParameterAsClass(String key, Class<T> clazz) {
         Collection c=parameters.getCollection(key);

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/AbstractMetadataFieldMapping.java

@@ -39,7 +39,7 @@ public abstract class AbstractMetadataFieldMapping<RecordType> implements Metada
 
     /**
      * Set a map of metadataprocessors. This map is used to process metadata to make it more compliant for certain metadata fields
-     * @param metadataProcessorMap
+     * @param metadataProcessorMap the new map.
      */
     public void setMetadataProcessorMap(Map<MetadataFieldConfig, MetadataProcessorService> metadataProcessorMap)
     {

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/MetadataFieldConfig.java

@@ -72,7 +72,7 @@ public class MetadataFieldConfig {
     /**
      * Create a MetadataFieldConfig based on a given MetadatumDTO
      * This MetadatumDTO object contains the schema, element and qualifier needed to initialize the MetadataFieldConfig
-     * @param value
+     * @param value the DTO.
      */
     public MetadataFieldConfig(MetadatumDTO value) {
         this.schema = value.getSchema();

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/contributor/CombinedMetadatumContributor.java

@@ -50,7 +50,7 @@ public class CombinedMetadatumContributor<T> implements MetadataContributor<T> {
     /**
      * Set the metadatafieldMapping used in the transforming of a record to actual metadata
      *
-     * @param metadataFieldMapping
+     * @param metadataFieldMapping the new mapping.
      */
     @Override
     public void setMetadataFieldMapping(MetadataFieldMapping<T, MetadataContributor<T>> metadataFieldMapping) {

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/contributor/SimpleXpathMetadatumContributor.java

@@ -50,7 +50,7 @@ public class SimpleXpathMetadatumContributor implements MetadataContributor<OMEl
 
     /**
      * Set the metadataFieldMapping of this SimpleXpathMetadatumContributor
-     * @param metadataFieldMapping
+     * @param metadataFieldMapping the new mapping.
      */
     public void setMetadataFieldMapping(MetadataFieldMapping<OMElement,MetadataContributor<OMElement>> metadataFieldMapping) {
         this.metadataFieldMapping = metadataFieldMapping;
@@ -58,7 +58,7 @@ public class SimpleXpathMetadatumContributor implements MetadataContributor<OMEl
 
     /**
      * Set the prefixToNamespaceMapping for this object,
-     * @param prefixToNamespaceMapping
+     * @param prefixToNamespaceMapping the new mapping.
      */
     @Resource(name="isiFullprefixMapping")
     public void setPrefixToNamespaceMapping(Map<String, String> prefixToNamespaceMapping) {

dspace-api/src/main/java/org/dspace/importer/external/pubmed/metadatamapping/contributor/PubmedDateMetadatumContributor.java

@@ -34,13 +34,15 @@ public class PubmedDateMetadatumContributor<T> implements MetadataContributor<T>
 
     private MetadataFieldMapping<T, MetadataContributor<T>> metadataFieldMapping;
 
-    /* A list of all the dateFormats to attempt, these should be configured to have the most specific first and the more lenient at the back */
+    /* A list of all the dateFormats to attempt.  These should be configured to
+       have the most specific first and the more lenient at the back. */
     private List<String> dateFormatsToAttempt;
 
 
     public List<String> getDateFormatsToAttempt() {
         return dateFormatsToAttempt;
     }
+
     @Required
     public void setDateFormatsToAttempt(List<String> dateFormatsToAttempt) {
         this.dateFormatsToAttempt = dateFormatsToAttempt;
@@ -52,8 +54,8 @@ public class PubmedDateMetadatumContributor<T> implements MetadataContributor<T>
     private MetadataContributor year;
 
     /**
-     * Set the metadatafieldMapping used in the transforming of a record to actual metadata
+     * Set the metadatafieldMapping used in the transforming of a record to actual metadata.
-     * @param metadataFieldMapping
+     * @param metadataFieldMapping the new mapping.
      */
     @Override
     public void setMetadataFieldMapping(MetadataFieldMapping<T, MetadataContributor<T>> metadataFieldMapping) {
@@ -200,4 +202,4 @@ public class PubmedDateMetadatumContributor<T> implements MetadataContributor<T>
         this.year = year;
     }
 
-}
+}

dspace-api/src/main/java/org/dspace/importer/external/pubmed/metadatamapping/contributor/PubmedLanguageMetadatumContributor.java

@@ -45,7 +45,7 @@ public class PubmedLanguageMetadatumContributor<T> implements MetadataContributo
      * Initialize the PubmedLanguageMetadatumContributor class using a {@link org.dspace.importer.external.metadatamapping.MetadataFieldConfig} and a language -{@link org.dspace.importer.external.metadatamapping.contributor.MetadataContributor}
      *
      * @param field {@link org.dspace.importer.external.metadatamapping.MetadataFieldConfig} used in mapping
-     * @param language
+     * @param language the language.
      */
     public PubmedLanguageMetadatumContributor(MetadataFieldConfig field, MetadataContributor language) {
         this();
@@ -56,7 +56,7 @@ public class PubmedLanguageMetadatumContributor<T> implements MetadataContributo
     /**
      * Set the metadatafieldMapping used in the transforming of a record to actual metadata
      *
-     * @param metadataFieldMapping
+     * @param metadataFieldMapping the new mapping.
      */
     @Override
     public void setMetadataFieldMapping(MetadataFieldMapping<T, MetadataContributor<T>> metadataFieldMapping) {

dspace-api/src/main/java/org/dspace/importer/external/service/AbstractImportMetadataSourceService.java

@@ -40,8 +40,11 @@ public abstract class AbstractImportMetadataSourceService<RecordType> extends Ab
 	}
 
     /**
-     * Set the {@link GenerateQueryService} used to create a {@link org.dspace.importer.external.datamodel.Query} for a DSpace {@link org.dspace.content.Item}
+     * Set the {@link GenerateQueryService} used to create a
-     * @param generateQueryForItem
+     * {@link org.dspace.importer.external.datamodel.Query} for a DSpace
+     * {@link org.dspace.content.Item}.
+     *
+     * @param generateQueryForItem the query generator to be used.
      */
     @Autowired
 	public void setGenerateQueryForItem(GenerateQueryService generateQueryForItem) {
@@ -58,7 +61,7 @@ public abstract class AbstractImportMetadataSourceService<RecordType> extends Ab
 
     /**
      * Sets the MetadataFieldMapping to base the mapping of RecordType and
-     * @param metadataFieldMapping
+     * @param metadataFieldMapping the map to be used.
      */
 	@Required
 	public void setMetadataFieldMapping(
@@ -68,7 +71,7 @@ public abstract class AbstractImportMetadataSourceService<RecordType> extends Ab
 
     /**
      *  Return an ImportRecord constructed from the results in a RecordType
-     * @param recordType The recordtype to retrieve the DCValueMapping from
+     * @param recordType The record type to retrieve the DCValueMapping from
      * @return An {@link ImportRecord}, This is based on the results retrieved from the recordTypeMapping
      */
 	public ImportRecord transformSourceRecords(RecordType recordType){

dspace-api/src/main/java/org/dspace/importer/external/service/components/MetadataSource.java

@@ -86,7 +86,7 @@ public interface MetadataSource {
      *  Delegates to one or more MetadataSource implementations based on the uri.  Results will be aggregated.
      * @param query a query object to base the search on.
      * @return a collection of import records. Only the identifier of the found records may be put in the record.
-     * @throws MetadataSourceException
+     * @throws MetadataSourceException passed through.
      */
     public Collection<ImportRecord> findMatchingRecords(Query query) throws MetadataSourceException;
 }

dspace-api/src/main/java/org/dspace/license/service/CreativeCommonsService.java

@@ -133,8 +133,8 @@ public interface CreativeCommonsService {
      * Get a few license-specific properties. We expect these to be cached at
      * least per server run.
      *
-     * @param fieldId
+     * @param fieldId name of the property.
-     * @return 
+     * @return its value.
      */
     public LicenseMetadataValue getCCField(String fieldId);
     

dspace-api/src/main/java/org/dspace/rdf/RDFUtil.java

@@ -135,7 +135,7 @@ public class RDFUtil {
      *             {@link org.dspace.core.Constants#ITEM Constants.ITEM}.
      * @param id UUID of the DSpaceObject you want to generate a URI for.
      * @param handle Handle of the DSpaceObject you want to generate a URI for.
-     * @param identifier
+     * @param identifier identifiers of the object.
      *     
      * @return URI to identify the DSO or null if no URI could be generated.
      *         This can happen f.e. if you use a URIGenerator that uses

dspace-api/src/main/java/org/dspace/rdf/storage/URIGenerator.java

@@ -16,8 +16,7 @@ import org.dspace.core.Context;
 
 /**
  * Please use 
- * {@link org.dspace.rdf.RDFUtil#generateIdentifier(Context, DSpaceObject)} and
+ * {@link org.dspace.rdf.RDFUtil#generateIdentifier(Context, DSpaceObject)} to 
- * {@link org.dspace.rdf.RDFUtil#generateGraphURI(Context, DSpaceObject)} to 
  * get URIs for RDF data.
  * Please note that URIs can be generated for DSpaceObjects of the 
  * type SITE, COMMUNITY, COLLECTION or ITEM only. Currently dspace-rdf 

dspace-api/src/main/java/org/dspace/sort/OrderFormat.java

@@ -59,13 +59,13 @@ public class OrderFormat
      *     metadata language code
      * @param type
      *     metadata type
-     *     {@see OrderFormat.AUTHOR}
-     *     {@see OrderFormat.TITLE}
-     *     {@see OrderFormat.TEXT}
-     *     {@see OrderFormat.DATE}
-     *     {@see OrderFormat.AUTHORITY}
      * @return sort string
      *     
+     * @see OrderFormat#AUTHOR
+     * @see OrderFormat#TITLE
+     * @see OrderFormat#TEXT
+     * @see OrderFormat#DATE
+     * @see #AUTHORITY
      */
     public static String makeSortString(String value, String language, String type)
     {

dspace-api/src/main/java/org/dspace/statistics/content/StatisticsDataVisits.java

@@ -489,9 +489,9 @@ public class StatisticsDataVisits extends StatisticsData
      * Gets the name of the DSO (example for collection: ((Collection) dso).getname();
      *
      * @param value
-     *     
+     *     UUID (or legacy record ID) of the DSO in question.
      * @param datasetQuery
-     *     
+     *     unknown, PLEASE DOCUMENT.
      * @param context
      *     The relevant DSpace Context.
      * @return the name of the given DSO

dspace-api/src/main/java/org/dspace/statistics/content/StatisticsDataWorkflow.java

@@ -149,10 +149,10 @@ public class StatisticsDataWorkflow extends StatisticsData {
 
 
     /**
-     * Retrieve the total counts for the facets (total count is same query but none of the filter queries
+     * Retrieve the total counts for the facets (total count is same query but none of the filter queries).
      * @param typeGenerator the type generator
-     * @return as a key the
+     * @return counts for each facet by name.
-     * @throws org.apache.solr.client.solrj.SolrServerException
+     * @throws org.apache.solr.client.solrj.SolrServerException passed through.
      */
     protected Map<String, Long> getTotalFacetCounts(DatasetTypeGenerator typeGenerator) throws SolrServerException {
         ObjectCount[] objectCounts = solrLoggerService.queryFacetField(getQuery(), null, typeGenerator.getType(), -1, false, null);

dspace-api/src/main/java/org/dspace/statistics/content/filter/StatisticsFilter.java

@@ -15,6 +15,8 @@ package org.dspace.statistics.content.filter;
  */
 public interface StatisticsFilter {
 
-    /** Convert this filter's configuration to a query string fragment. */
+    /** Convert this filter's configuration to a query string fragment.
+     * @return a query fragment.
+     */
     public String toQuery();
 }

dspace-api/src/main/java/org/dspace/statistics/service/ElasticSearchLoggerService.java

@@ -20,10 +20,10 @@ import java.util.HashMap;
 
 /**
  * Service interface class for the Elastic Search logging.
- * The implementation of this class is responsible for all business logic calls for the Elastic Search logging and is autowired by spring
+ * The implementation of this class is responsible for all business logic calls for the Elastic Search logging and is autowired by Spring.
- * 
+ *
- * @deprecated  As of DSpace 6.0, ElasticSearch statistics are replaced by Solr statistics
+ * @deprecated  As of DSpace 6.0, ElasticSearch statistics are replaced by Solr statistics.
- * @see org.dspace.statistics.service.SolrLoggerService#SolrLoggerService
+ * @see org.dspace.statistics.service.SolrLoggerService
  *
  * @author kevinvandevelde at atmire.com
  */

dspace-api/src/main/java/org/dspace/statistics/util/StatisticsImporter.java

@@ -528,8 +528,8 @@ public class StatisticsImporter
 
     /**
      * Inner class to hold a cache of reverse lookups of IP addresses
-     * @param <K>
+     * @param <K> key type.
-     * @param <V>
+     * @param <V> value type.
      */
     static class DNSCache<K,V> extends LinkedHashMap<K,V>
     {

dspace-api/src/main/java/org/dspace/submit/lookup/CiNiiService.java

@@ -152,7 +152,7 @@ public class CiNiiService
      *     maximun number of results returned
      * @param appId
      *     registered application identifier for the API
-     * @return
+     * @return matching NAIDs
      * @throws IOException
      *     A general class of exceptions produced by failed or interrupted I/O operations.
      * @throws HttpException

dspace-api/src/main/java/org/dspace/workflow/WorkflowService.java

@@ -26,6 +26,7 @@ import java.util.List;
  * are required to have.
  *
  * @author kevinvandevelde at atmire.com
+ * @param <T> some implementation of workflow item.
  */
 public interface WorkflowService<T extends WorkflowItem> {
 
@@ -60,7 +61,7 @@ public interface WorkflowService<T extends WorkflowItem> {
      *     The relevant DSpace Context.
      * @param wsi
      *     workspace item
-     * @return 
+     * @return the resulting workflow item.
      * @throws SQLException
      *     An exception that provides information on a database access error or other errors.
      * @throws AuthorizeException

dspace-api/src/main/java/org/dspace/xmlworkflow/WorkflowUtils.java

@@ -214,7 +214,7 @@ public class WorkflowUtils extends Util{
      * @param collection
      *     the target collection
      * @param roleId
-     *     
+     *     the role to be linked.
      * @param group
      *     group of EPersons
      * @throws AuthorizeException

dspace-jspui/src/main/java/org/dspace/app/webui/discovery/DiscoverUtility.java

@@ -91,7 +91,7 @@ public class DiscoverUtility
      * @param scope
      *     DSpace object
      * @param enableFacet
-     *     
+     *     UNKNOWN.  PLEASE DOCUMENT.
      * @return the query.
      */
     public static DiscoverQuery getDiscoverQuery(Context context,
@@ -128,7 +128,7 @@ public class DiscoverUtility
      * @param scope
      *     DSpace object
      * @param enableFacet
-     *     
+     *     UNKNOWN.  PLEASE DOCUMENT.
      * @return the query.
      */
     public static DiscoverQuery getTagCloudDiscoverQuery(Context context,

dspace-jspui/src/main/java/org/dspace/app/webui/util/UIUtil.java

@@ -609,7 +609,7 @@ public class UIUtil extends Util
      * @param dso The DSpaceObject to mark (it can be a BrowseItem or an Item)
      * @param markType the type of the mark.
      * @return (X)HTML markup
-     * @throws JspException
+     * @throws JspException on a database error.
      */
     public static String getMarkingMarkup(HttpServletRequest hrq, DSpaceObject dso, String markType)
             throws JspException

dspace-jspui/src/main/java/org/dspace/app/webui/util/VersionUtil.java

@@ -346,11 +346,12 @@ public class VersionUtil
     }
     
     /**
-     * Retrieve the summary for the version
+     * Retrieve the summary for the version.
      * 
      * @param context
      *     The relevant DSpace Context.
      * @param stringVersionID
+     *     An encoded integer version number.
      * @return version summary string
      */
     public static String getSummary(Context context, String stringVersionID)

dspace-jspui/src/main/java/org/dspace/app/webui/util/XMLUtil.java

@@ -63,7 +63,7 @@ public class XMLUtil
      * @param xsltFilename
      *            the filename of the stylesheet
      * @return the transformed xml document
-     * @throws Exception
+     * @throws Exception passed through.
      */
     public static Document transformDocument(Document xmlDocument,
             String xsltFilename) throws Exception
@@ -82,7 +82,7 @@ public class XMLUtil
      * @param xsltFilename
      *            the filename of the stylesheet
      * @return the transformed xml document
-     * @throws Exception
+     * @throws Exception passed through.
      */
     public static Document transformDocument(Document xmlDocument, Map<String, String> parameters, String xsltFilename) throws Exception
     {
@@ -116,18 +116,18 @@ public class XMLUtil
     }
 
     /**
-     * Applies a stylesheet (that receives parameters) to a given xml document.
+     * Applies a stylesheet (that receives parameters) to a given XML document.
      * The resulting XML document is converted to a string after transformation.
      * 
      * @param xmlDocument
-     *            the xml document to be transformed
+     *            the XML document to be transformed
      * @param parameters
      *            the hashtable with the parameters to be passed to the
      *            stylesheet
      * @param xsltFilename
      *            the filename of the stylesheet
-     * @return the transformed xml document as a string
+     * @return the transformed XML document as a string
-     * @throws Exception
+     * @throws Exception passed through.
      */
     public static String transformDocumentAsString(Document xmlDocument, Map<String, String> parameters, String xsltFilename) throws Exception
     {
@@ -155,14 +155,14 @@ public class XMLUtil
     }
 
     /**
-     * Applies a stylesheet to a given xml document.
+     * Applies a stylesheet to a given XML document.
      * 
      * @param xmlDocument
-     *            the xml document to be transformed
+     *            the XML document to be transformed
      * @param xsltFilename
      *            the filename of the stylesheet
-     * @return the transformed xml document
+     * @return the transformed XML document
-     * @throws Exception
+     * @throws Exception passed through.
      */
     public static String transformDocumentAsString(Document xmlDocument,
             String xsltFilename) throws Exception

dspace-rest/src/main/java/org/dspace/rest/filter/ItemFilterSet.java

@@ -39,8 +39,8 @@ public class ItemFilterSet {
      * Construct a set of Item Filters identified by a list string.
      * 
      * @param filterList
-     *     Comma separated list of filter names to include
+     *     Comma separated list of filter names to include.
-     *     @see org.dspace.rest.common#ItemFilter.ALL to retrieve all filters
+     *     Use {@link org.dspace.rest.common.ItemFilter#ALL} to retrieve all filters.
      * @param reportItems
      *     If true, return item details.  If false, return only counts of items.
      */

dspace-sword/src/main/java/org/dspace/sword/SWORDAuthenticator.java

@@ -109,7 +109,7 @@ public class SWORDAuthenticator
      * @param request
      *     service document request
      * @return authenticated SWORD context
-     * @throws SWORDException
+     * @throws SWORDException passed through.
      * @throws SWORDErrorException on generic SWORD exception
      * @throws SWORDAuthenticationException Thrown if the authentication fails
      */
@@ -142,7 +142,7 @@ public class SWORDAuthenticator
      * @param request
      *     ATOM document request
      * @return a SWORDContext object containing the relevant users
-     * @throws SWORDException
+     * @throws SWORDException passed through.
      * @throws SWORDErrorException on generic SWORD exception
      * @throws SWORDAuthenticationException Thrown if the authentication fails
      */
@@ -215,7 +215,7 @@ public class SWORDAuthenticator
      * @param deposit
      *     deposit request
      * @return a SWORDContext object containing the relevant users
-     * @throws SWORDException
+     * @throws SWORDException passed through.
      * @throws SWORDErrorException on generic SWORD exception
      * @throws SWORDAuthenticationException Thrown if the authentication fails
      */

dspace-sword/src/main/java/org/dspace/sword/SWORDContext.java

@@ -165,7 +165,7 @@ public class SWORDContext
      * operations are flushed.  You should, in general, not try to commit the contexts directly
      * when using the SWORD API.
      *
-     * @throws DSpaceSWORDException
+     * @throws DSpaceSWORDException on database error.
      */
     public void commit()
             throws DSpaceSWORDException

dspace-sword/src/main/java/org/dspace/sword/SWORDService.java

@@ -25,11 +25,11 @@ import org.purl.sword.base.Deposit;
  * @author Richard Jones
  *
  * This class represents the actual sword service provided by dspace.  It
- * is the central location for the authentcated contexts, the installation
+ * is the central location for the authenticated contexts, the installation
- * specific configuration, and the url management.
+ * specific configuration, and the URL management.
  *
- * It is ubiquotous in the sword implementation, and all related
+ * It is ubiquitous in the sword implementation, and all related
- * information and services should be retrived via this api
+ * information and services should be retrieved via this API.
  *
  */
 public class SWORDService
@@ -158,7 +158,7 @@ public class SWORDService
      * @param original
      *     is original?
      * @return the most appropriate filename for the incoming deposit
-     * @throws DSpaceSWORDException
+     * @throws DSpaceSWORDException on database error.
      */
     public String getFilename(Context context, Deposit deposit,
             boolean original)

dspace-sword/src/main/java/org/dspace/sword/SWORDUrlManager.java

@@ -447,7 +447,7 @@ public class SWORDUrlManager
      * @param url
      *     URL to check
      * @return true if the given URL the base media link URL
-     * @throws DSpaceSWORDException
+     * @throws DSpaceSWORDException passed through.
      */
     public boolean isBaseMediaLinkUrl(String url)
             throws DSpaceSWORDException
@@ -461,6 +461,7 @@ public class SWORDUrlManager
      *
      * @param bitstream
      *     target bitstream
+     * @return a URL to the given Bitstream.
      * @throws DSpaceSWORDException
      *     can be thrown by the internals of the DSpace SWORD implementation
      */
@@ -514,8 +515,12 @@ public class SWORDUrlManager
     }
 
     /**
-     * Get the base media link URL.
+     * Get the base media link URL.  It can be configured using
+     * {@code sword-server.media-link.url}.  If not configured, it will be
+     * calculated using {@code dspace.baseUrl} and the constant path
+     * {@code /sword/media-link}.
      *
+     * @return that URL.
      * @throws DSpaceSWORDException
      *     can be thrown by the internals of the DSpace SWORD implementation
      */

dspace-sword/src/main/java/org/purl/sword/atom/Author.java

@@ -156,8 +156,9 @@ public class Author extends XmlElement implements SwordElementInterface
      * is a XOM element.
      *
      * @param author The element to unmarshall.
-     * @param validationContext
+     * @param validationProperties UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
+     * @throws org.purl.sword.base.UnmarshallException passed through
      */
     public SwordValidationInfo unmarshall(Element author, Properties validationProperties)
     throws UnmarshallException

dspace-sword/src/main/java/org/purl/sword/atom/Content.java

@@ -160,8 +160,8 @@ public class Content extends XmlElement implements SwordElementInterface
     /**
      * Unmarshall the content element into the data in this object. 
      * 
-     * @param content
+     * @param content the element to unmarshall.
-     * @param validationProperties
+     * @param validationProperties UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      * @throws UnmarshallException If the element does not contain a
      *                             content element or if there are problems
@@ -245,9 +245,9 @@ public class Content extends XmlElement implements SwordElementInterface
  
     /**
      * 
-     * @param elements
+     * @param elements add results to this.
-     * @param attributes
+     * @param attributes add these too.
-     * @param validationContext
+     * @param validationContext UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      */
     protected SwordValidationInfo validate(List<SwordValidationInfo> elements,

dspace-sword/src/main/java/org/purl/sword/atom/Entry.java

@@ -574,8 +574,8 @@ public class Entry extends XmlElement implements SwordElementInterface
  
     /**
      *
-     * @param info
+     * @param info add results to this.  If null, a new one is created.
-     * @param validationContext
+     * @param validationContext UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      */
     protected SwordValidationInfo validate(SwordValidationInfo info,

dspace-sword/src/main/java/org/purl/sword/atom/Generator.java

@@ -212,7 +212,10 @@ public class Generator extends XmlElement implements SwordElementInterface
  
     /**
      *
+     * @param validationContext UNKNOWN.  PLEASE DOCUMENT.
+     * @return SWORD validation info.
      */
+    @Override
     public SwordValidationInfo validate(Properties validationContext)
     {
         return validate(null, null, validationContext);
@@ -220,9 +223,9 @@ public class Generator extends XmlElement implements SwordElementInterface
  
     /**
      * 
-     * @param existing
+     * @param existing add results to this.
-     * @param attributeItems
+     * @param attributeItems add these too.
-     * @param validationContext
+     * @param validationContext UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      */
     public SwordValidationInfo validate(List<SwordValidationInfo> existing,

dspace-sword/src/main/java/org/purl/sword/atom/Source.java

@@ -94,8 +94,8 @@ public class Source extends XmlElement implements SwordElementInterface
  
     /**
      * 
-     * @param source
+     * @param source the element to unmarshall.
-     * @param validationProperties
+     * @param validationProperties UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      * @throws UnmarshallException If there was an error unmarshalling the data. 
      */

dspace-sword/src/main/java/org/purl/sword/atom/TextConstruct.java

@@ -147,8 +147,8 @@ implements SwordElementInterface
  
     /**
      * 
-     * @param text The text element. 
+     * @param text The text element.
-     * @param validationProperties
+     * @param validationProperties UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      * @throws UnmarshallException If the specified element is not of
      *                             the correct type, where the localname is used
@@ -251,9 +251,9 @@ implements SwordElementInterface
  
     /**
      *
-     * @param existing
+     * @param existing add results to this.
-     * @param attributeItems
+     * @param attributeItems add these too.
-     * @param validationContext
+     * @param validationContext UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      */
     protected SwordValidationInfo validate(List<SwordValidationInfo> existing,

dspace-sword/src/main/java/org/purl/sword/base/BasicContentElement.java

@@ -62,7 +62,7 @@ implements SwordElementInterface
      * is an area that can be improved in a future implementation, if necessary. 
      * 
      * @param element The text element.
-     * @param validationProperties
+     * @param validationProperties UNKNOWN.  PLEASE DOCUMENT.
      * @return object representing the text element
      * @throws UnmarshallException If the specified element is not of
      *                             the correct type, where the localname is used
@@ -140,9 +140,9 @@ implements SwordElementInterface
  
     /**
      *
-     * @param existing
+     * @param existing add results to this.
-     * @param attributeItems
+     * @param attributeItems UNKNOWN.  PLEASE DOCUMENT.
-     * @param validationContext
+     * @param validationContext UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      */
     protected SwordValidationInfo validate(List<SwordValidationInfo> existing,

dspace-sword/src/main/java/org/purl/sword/base/Collection.java

@@ -679,9 +679,9 @@ public class Collection extends XmlElement implements SwordElementInterface
  
     /**
      *
-     * @param existing
+     * @param existing add results to this.
-     * @param attributes
+     * @param attributes UNKNOWN.  PLEASE DOCUMENT.
-     * @param validationContext
+     * @param validationContext UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      */
     protected SwordValidationInfo validate(List<SwordValidationInfo> existing,

dspace-sword/src/main/java/org/purl/sword/base/DepositResponse.java

@@ -199,7 +199,7 @@ public class DepositResponse
      * Unmarshall the specified XML data into a SWORD error document. 
      * 
      * @param xml The XML data as a string. 
-     * @param validationContext
+     * @param validationContext UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      * @throws UnmarshallException If there was an error unmarshalling the data. 
      */

dspace-sword/src/main/java/org/purl/sword/base/SWORDEntry.java

@@ -267,7 +267,7 @@ public class SWORDEntry extends Entry
      * extensions that exist in the element. 
      * 
      * @param entry The entry to parse. 
-     * @param validationProperties
+     * @param validationProperties UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      * @throws UnmarshallException If the entry is not an atom:entry 
      *              or if there is an exception extracting the data. 

dspace-sword/src/main/java/org/purl/sword/base/SWORDErrorDocument.java

@@ -100,9 +100,9 @@ public class SWORDErrorDocument extends SWORDEntry
  
     /**
      * 
-     * @param entry
+     * @param entry an element to unmarshall.
-     * @param validationProperties
+     * @param validationProperties UNKNOWN.  PLEASE DOCUMENT.
-     * @throws org.purl.sword.base.UnmarshallException
+     * @throws org.purl.sword.base.UnmarshallException passed through.
      */
     public SwordValidationInfo unmarshall(Element entry, Properties validationProperties)
     throws UnmarshallException
@@ -155,7 +155,7 @@ public class SWORDErrorDocument extends SWORDEntry
  
     /**
      *
-     * @param validationContext
+     * @param validationContext UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      */
     public SwordValidationInfo validate(Properties validationContext)
@@ -165,8 +165,8 @@ public class SWORDErrorDocument extends SWORDEntry
  
     /**
      * 
-     * @param info
+     * @param info add results to this.
-     * @param validationContext
+     * @param validationContext unused.
      * @return SWORD validation info
      */
     protected SwordValidationInfo validate(SwordValidationInfo info,

dspace-sword/src/main/java/org/purl/sword/base/Service.java

@@ -373,6 +373,7 @@ public class Service extends XmlElement implements SwordElementInterface
      * @param service
      *     element to unmarshall
      * @param validationProperties
+     *     UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      * @throws UnmarshallException If the element does not contain a
      *      content element or if there are problems
@@ -528,8 +529,8 @@ public class Service extends XmlElement implements SwordElementInterface
  
     /**
      *
-     * @param existing
+     * @param existing add results to this.
-     * @param validationContext
+     * @param validationContext UNKNOWN.  PLEASE DOCUMENT.
      * @return validation information
      */
     protected SwordValidationInfo validate(List<SwordValidationInfo> existing,

dspace-sword/src/main/java/org/purl/sword/base/ServiceDocument.java

@@ -129,9 +129,12 @@ public class ServiceDocument {
     }
 
     /**
-     * 
+     * Convert the specified XML string into a set of objects used within the
-     * @param xml
+     * service. A new Service object will be created and stored. This will
-     * @param validationProperties
+     * dispose of any previous Service object associated with this object.
+     *
+     * @param xml The XML string.
+     * @param validationProperties UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      * @throws UnmarshallException
      *     If there was a problem unmarshalling the data. This might be
@@ -156,7 +159,7 @@ public class ServiceDocument {
 
     /**
      * Unmarshall the specified element. This version does not generate any
-     * valiation information.
+     * validation information.
      *
      * @param element
      *     element to unmarshall
@@ -176,7 +179,9 @@ public class ServiceDocument {
      * information.
      * 
      * @param element
+     *     element to unmarshall.
      * @param validationProperties
+     *     UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      * @throws UnmarshallException
      *     If there was a problem unmarshalling the data. This might be

dspace-sword/src/main/java/org/purl/sword/base/SwordAcceptPackaging.java

@@ -107,7 +107,7 @@ implements SwordElementInterface
      * is an area that can be improved in a future implementation, if necessary. 
      * 
      * @param acceptPackaging The text element.
-     * @param validationProperties
+     * @param validationProperties UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      * 
      * @throws UnmarshallException If the specified element is not of
@@ -213,9 +213,9 @@ implements SwordElementInterface
  
     /**
      *
-     * @param existing
+     * @param existing add results to this.
-     * @param attributeItems
+     * @param attributeItems UNKNOWN.  PLEASE DOCUMENT.
-     * @param validationContext
+     * @param validationContext UNKNOWN.  PLEASE DOCUMENT.
      * @return SWORD validation info
      */
     protected SwordValidationInfo validate(List<SwordValidationInfo> existing,

dspace-sword/src/main/java/org/purl/sword/base/SwordValidationInfo.java

@@ -312,6 +312,7 @@ public class SwordValidationInfo {
 
     /**
      *
+     * @return the iterator.
      */
     public Iterator<SwordValidationInfo> getValidationAttributeInfoIterator()
     {
@@ -320,6 +321,7 @@ public class SwordValidationInfo {
 
     /**
      *
+     * @return the iterator.
      */
     public Iterator<SwordValidationInfo> getUnmarshallElementInfoIterator()
     {
@@ -328,6 +330,7 @@ public class SwordValidationInfo {
 
     /**
      * 
+     * @return the iterator.
      */
     public Iterator<SwordValidationInfo> getUnmarshallAttributeInfoIterator()
     {
@@ -350,8 +353,8 @@ public class SwordValidationInfo {
 
     /**
      * 
-     * @param elementItems
+     * @param elementItems UNKNOWN.  PLEASE DOCUMENT.
-     * @param attributeItems
+     * @param attributeItems UNKNOWN.  PLEASE DOCUMENT.
      */
     public void addUnmarshallValidationInfo(
             List<SwordValidationInfo> elementItems,

dspace-sword/src/main/java/org/purl/sword/base/Workspace.java

@@ -185,8 +185,9 @@ public class Workspace extends XmlElement implements SwordElementInterface
  
     /**
      *
-     * @param workspace
+     * @param workspace the element to unmarshall.
-     * @param validationProperties
+     * @param validationProperties UNKNOWN.  PLEASE DOCUMENT.
+     * @return UNKNOWN.  PLEASE DOCUMENT.
      * @throws UnmarshallException If the element does not contain a
      *                             workspace element or if there are problems
      *                             accessing the data. 
@@ -272,7 +273,9 @@ public class Workspace extends XmlElement implements SwordElementInterface
  
     /**
      * 
-     * @param existing
+     * @param existing add results to this.
+     * @param validationContext UNKNOWN.  PLEASE DOCUMENT.
+     * @return UNKNOWN.  PLEASE DOCUMENT.
      */
     protected SwordValidationInfo validate(List<SwordValidationInfo> existing,
             Properties validationContext)

dspace-sword/src/main/java/org/purl/sword/client/PostDialog.java

@@ -177,7 +177,7 @@ implements ActionListener, ChangeListener
  
     /**
      * 
-     * @param parentFrame
+     * @param parentFrame the parent of this dialog.
      */
     public PostDialog(JFrame parentFrame)
     {

dspace-swordv2/src/main/java/org/dspace/sword2/SwordAuthenticator.java

@@ -307,6 +307,7 @@ public class SwordAuthenticator
      * @throws DSpaceSwordException
      *     can be thrown by the internals of the DSpace SWORD implementation
      * @throws SwordError
+     *     never.
      */
     public boolean canSubmit(SwordContext swordContext, DSpaceObject dso,
             VerboseDescription msg)

dspace-swordv2/src/main/java/org/dspace/sword2/SwordIngesterFactory.java

@@ -36,13 +36,15 @@ public class SwordIngesterFactory
      *
      * @param context
      *     The relevant DSpace Context.
-     * @param deposit        the original deposit request
+     * @param deposit
+     *     The original deposit request
      * @param dso
      *     target DSpace object
      * @return SWORDIngester object
      * @throws DSpaceSwordException
      *     can be thrown by the internals of the DSpace SWORD implementation
      * @throws SwordError
+     *     if no suitable ingester is configured.
      */
     public static SwordContentIngester getContentInstance(Context context,
             Deposit deposit, DSpaceObject dso)

dspace-swordv2/src/main/java/org/dspace/sword2/SwordUrlManager.java

@@ -199,6 +199,7 @@ public class SwordUrlManager
      * @throws DSpaceSwordException
      *     can be thrown by the internals of the DSpace SWORD implementation
      * @throws SwordError
+     *     if a proper URL cannot be calculated.
      */
     // FIXME: we need to generalise this to DSpaceObjects, so that we can support
     // Communities, Collections and Items separately

dspace-xmlui/src/main/java/org/dspace/app/xmlui/aspect/administrative/FlowContainerUtils.java

@@ -586,10 +586,11 @@ public class FlowContainerUtils
 	/**
 	 * Look up the id of a group authorized for one of the given roles. If no group is currently 
 	 * authorized to perform this role then a new group will be created and assigned the role.
+     * THIS DOCUMENTATION IS WRONG.  PLEASE FIX IT.
 	 * 
 	 * @param context The current DSpace context.
 	 * @param collection The collection.
-	 * @return The id of the group associated with that particular role or -1
+	 * @return The Group associated with that particular role or -1
      * @throws java.sql.SQLException passed through.
      * @throws org.dspace.authorize.AuthorizeException passed through.
 	 */
@@ -624,6 +625,15 @@ public class FlowContainerUtils
 	}
 
 	/**
+	 * Look up the id of a group authorized for one of the given roles. If no group is currently
+	 * authorized to perform this role then a new group will be created and assigned the role.
+     * THIS DOCUMENTATION IS WRONG.  PLEASE FIX IT.
+	 *
+     * @param context DSpace context.
+     * @param collectionID The Collection whose roles will be searched.
+     * @return the UUID of the matching group.
+     * @throws java.sql.SQLException passed through.
+     * @throws org.dspace.authorize.AuthorizeException passed through.
 	 * @see #getCollectionDefaultRead(Context, Collection)
      */
 	public static UUID getCollectionDefaultRead(final Context context, final UUID collectionID) throws SQLException, AuthorizeException {