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.
This commit is contained in:
Mark H. Wood
2016-11-11 11:48:17 -05:00
parent 269af71afb
commit d1f321f345
67 changed files with 193 additions and 150 deletions

View File

@@ -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

View File

@@ -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)

View File

@@ -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).
* 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 a string that will allow this AuthorityType to be recognized and
* 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() {

View File

@@ -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> {
}

View File

@@ -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> {

View File

@@ -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
* 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}).
* Returns the size of the cache of all object that have been read from the database so far.
*
* @return connection cache size
* @throws SQLException When connecting to the active cache fails.

View File

@@ -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.

View File

@@ -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)

View File

@@ -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);

View File

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

View File

@@ -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

View File

@@ -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.

View File

@@ -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.
*
*/

View File

@@ -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;

View File

@@ -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>

View File

@@ -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.

View File

@@ -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 clazz The classtype to retrieve. (If no parameter with that class is found, a <tt>null</tt> value is returned
* @return
* @param <T> the type of parameter returned.
* @param key the key to retrieve the parameter from
* @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);

View File

@@ -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)
{

View File

@@ -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();

View File

@@ -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) {

View File

@@ -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) {

View File

@@ -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
* @param metadataFieldMapping
* Set the metadatafieldMapping used in the transforming of a record to actual metadata.
* @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;
}
}
}

View File

@@ -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) {

View File

@@ -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}
* @param generateQueryForItem
* Set the {@link GenerateQueryService} used to create a
* {@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){

View File

@@ -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;
}

View File

@@ -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
* @return
* @param fieldId name of the property.
* @return its value.
*/
public LicenseMetadataValue getCCField(String fieldId);

View File

@@ -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

View File

@@ -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#generateGraphURI(Context, DSpaceObject)} to
* {@link org.dspace.rdf.RDFUtil#generateIdentifier(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

View File

@@ -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)
{

View File

@@ -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

View File

@@ -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
* @throws org.apache.solr.client.solrj.SolrServerException
* @return counts for each facet by name.
* @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);

View File

@@ -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();
}

View File

@@ -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
*
* @deprecated As of DSpace 6.0, ElasticSearch statistics are replaced by Solr statistics
* @see org.dspace.statistics.service.SolrLoggerService#SolrLoggerService
* 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.
* @see org.dspace.statistics.service.SolrLoggerService
*
* @author kevinvandevelde at atmire.com
*/

View File

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

View File

@@ -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

View File

@@ -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

View File

@@ -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