From 38203490c7573f70e3de26da8bc54f29c8022e9a Mon Sep 17 00:00:00 2001 From: Yura Bondarenko Date: Mon, 5 Sep 2022 09:51:05 +0200 Subject: [PATCH] 93803: Add missing docstrings --- .../browse/browse-definition-data.service.ts | 18 +++++++++++++- src/app/core/config/config-data.service.ts | 18 ++++++++++++++ ...submission-accesses-config-data.service.ts | 14 +++++++++++ .../submission-forms-config-data.service.ts | 17 +++++++++++++ .../core/data/access-status-data.service.ts | 5 +++- src/app/core/data/dso-redirect.service.ts | 14 +++++++++++ .../persistent-identifier-data.service.ts | 24 ------------------- .../vocabulary-entry-details.data.service.ts | 3 +++ .../vocabularies/vocabulary.data.service.ts | 3 +++ 9 files changed, 90 insertions(+), 26 deletions(-) delete mode 100644 src/app/core/data/persistent-identifier-data.service.ts diff --git a/src/app/core/browse/browse-definition-data.service.ts b/src/app/core/browse/browse-definition-data.service.ts index 1c68885432..32c3b44e14 100644 --- a/src/app/core/browse/browse-definition-data.service.ts +++ b/src/app/core/browse/browse-definition-data.service.ts @@ -14,6 +14,9 @@ import { IdentifiableDataService } from '../data/base/identifiable-data.service' import { FindAllData, FindAllDataImpl } from '../data/base/find-all-data'; import { dataService } from '../data/base/data-service.decorator'; +/** + * Data service responsible for retrieving browse definitions from the REST server + */ @Injectable({ providedIn: 'root', }) @@ -32,7 +35,20 @@ export class BrowseDefinitionDataService extends IdentifiableDataService>>} + * Return an observable that emits object list + */ findAll(options: FindListOptions = {}, useCachedVersionIfAvailable = true, reRequestOnStale = true, ...linksToFollow: FollowLinkConfig[]): Observable>> { return this.findAllData.findAll(options, useCachedVersionIfAvailable, reRequestOnStale, ...linksToFollow); } diff --git a/src/app/core/config/config-data.service.ts b/src/app/core/config/config-data.service.ts index 8c903a8ba6..9ef2f11ad1 100644 --- a/src/app/core/config/config-data.service.ts +++ b/src/app/core/config/config-data.service.ts @@ -6,7 +6,25 @@ import { getFirstCompletedRemoteData } from '../shared/operators'; import { map } from 'rxjs/operators'; import { BaseDataService } from '../data/base/base-data.service'; +/** + * Abstract data service to retrieve configuration objects from the REST server. + * Common logic for configuration objects should be implemented here. + */ export abstract class ConfigDataService extends BaseDataService { + /** + * Returns an observable of {@link RemoteData} of an object, based on an href, with a list of + * {@link FollowLinkConfig}, to automatically resolve {@link HALLink}s of the object + * + * Throws an error if a configuration object cannot be retrieved. + * + * @param href The url of object we want to retrieve + * @param useCachedVersionIfAvailable If this is true, the request will only be sent if there's + * no valid cached version. Defaults to true + * @param reRequestOnStale Whether or not the request should automatically be re- + * requested after the response becomes stale + * @param linksToFollow List of {@link FollowLinkConfig} that indicate which + * {@link HALLink}s should be automatically resolved + */ public findByHref(href: string, useCachedVersionIfAvailable = true, reRequestOnStale = true, ...linksToFollow: FollowLinkConfig[]): Observable> { return super.findByHref(href, useCachedVersionIfAvailable, reRequestOnStale, ...linksToFollow).pipe( getFirstCompletedRemoteData(), diff --git a/src/app/core/config/submission-accesses-config-data.service.ts b/src/app/core/config/submission-accesses-config-data.service.ts index 9cfdfaec96..d2da0fce42 100644 --- a/src/app/core/config/submission-accesses-config-data.service.ts +++ b/src/app/core/config/submission-accesses-config-data.service.ts @@ -27,6 +27,20 @@ export class SubmissionAccessesConfigDataService extends ConfigDataService { super('submissionaccessoptions', requestService, rdbService, objectCache, halService); } + /** + * Returns an observable of {@link RemoteData} of an object, based on an href, with a list of + * {@link FollowLinkConfig}, to automatically resolve {@link HALLink}s of the object + * + * Throws an error if a configuration object cannot be retrieved. + * + * @param href The url of object we want to retrieve + * @param useCachedVersionIfAvailable If this is true, the request will only be sent if there's + * no valid cached version. Defaults to true + * @param reRequestOnStale Whether or not the request should automatically be re- + * requested after the response becomes stale + * @param linksToFollow List of {@link FollowLinkConfig} that indicate which + * {@link HALLink}s should be automatically resolved + */ findByHref(href: string, useCachedVersionIfAvailable = true, reRequestOnStale = true, ...linksToFollow): Observable> { return super.findByHref(href, useCachedVersionIfAvailable, reRequestOnStale, ...linksToFollow as FollowLinkConfig[]) as Observable>; } diff --git a/src/app/core/config/submission-forms-config-data.service.ts b/src/app/core/config/submission-forms-config-data.service.ts index 3cb82b262a..f4c0690685 100644 --- a/src/app/core/config/submission-forms-config-data.service.ts +++ b/src/app/core/config/submission-forms-config-data.service.ts @@ -12,6 +12,9 @@ import { Observable } from 'rxjs'; import { FollowLinkConfig } from '../../shared/utils/follow-link-config.model'; import { dataService } from '../data/base/data-service.decorator'; +/** + * Data service to retrieve submission form configuration objects from the REST server. + */ @Injectable() @dataService(SUBMISSION_FORMS_TYPE) export class SubmissionFormsConfigDataService extends ConfigDataService { @@ -24,6 +27,20 @@ export class SubmissionFormsConfigDataService extends ConfigDataService { super('submissionforms', requestService, rdbService, objectCache, halService); } + /** + * Returns an observable of {@link RemoteData} of an object, based on an href, with a list of + * {@link FollowLinkConfig}, to automatically resolve {@link HALLink}s of the object + * + * Throws an error if a configuration object cannot be retrieved. + * + * @param href The url of object we want to retrieve + * @param useCachedVersionIfAvailable If this is true, the request will only be sent if there's + * no valid cached version. Defaults to true + * @param reRequestOnStale Whether or not the request should automatically be re- + * requested after the response becomes stale + * @param linksToFollow List of {@link FollowLinkConfig} that indicate which + * {@link HALLink}s should be automatically resolved + */ public findByHref(href: string, useCachedVersionIfAvailable = true, reRequestOnStale = true, ...linksToFollow: FollowLinkConfig[]): Observable> { return super.findByHref(href, useCachedVersionIfAvailable, reRequestOnStale, ...linksToFollow as FollowLinkConfig[]) as Observable>; } diff --git a/src/app/core/data/access-status-data.service.ts b/src/app/core/data/access-status-data.service.ts index aac9cc9136..2f641456fa 100644 --- a/src/app/core/data/access-status-data.service.ts +++ b/src/app/core/data/access-status-data.service.ts @@ -11,6 +11,9 @@ import { Item } from '../shared/item.model'; import { BaseDataService } from './base/base-data.service'; import { dataService } from './base/data-service.decorator'; +/** + * Data service responsible for retrieving the access status of Items + */ @Injectable() @dataService(ACCESS_STATUS) export class AccessStatusDataService extends BaseDataService { @@ -26,7 +29,7 @@ export class AccessStatusDataService extends BaseDataService /** * Returns {@link RemoteData} of {@link AccessStatusObject} that is the access status of the given item - * @param item Item we want the access status of + * @param item Item we want the access status of */ findAccessStatusFor(item: Item): Observable> { return this.findByHref(item._links.accessStatus.href); diff --git a/src/app/core/data/dso-redirect.service.ts b/src/app/core/data/dso-redirect.service.ts index 6c57dbb594..81ce678e43 100644 --- a/src/app/core/data/dso-redirect.service.ts +++ b/src/app/core/data/dso-redirect.service.ts @@ -25,6 +25,11 @@ import { getDSORoute } from '../../app-routing-paths'; const ID_ENDPOINT = 'pid'; const UUID_ENDPOINT = 'dso'; +/** + * A data service to retrieve DSpaceObjects by persistent identifier or UUID. + * Doesn't define a constant {@link linkPath} but switches between two endpoints on demand: + * {@link setLinkPath} must be called before each request. + */ class DsoByIdOrUUIDDataService extends IdentifiableDataService { constructor( protected requestService: RequestService, @@ -56,6 +61,10 @@ class DsoByIdOrUUIDDataService extends IdentifiableDataService { } } +/** + * A service to handle redirects from identifier paths to DSO path + * e.g.: redirect from /handle/... to /items/... + */ @Injectable() export class DsoRedirectService { private dataService: DsoByIdOrUUIDDataService; @@ -70,6 +79,11 @@ export class DsoRedirectService { this.dataService = new DsoByIdOrUUIDDataService(requestService, rdbService, objectCache, halService); } + /** + * Retrieve a DSpaceObject by + * @param id the identifier of the object to retrieve + * @param identifierType the type of the given identifier (defaults to UUID) + */ findByIdAndIDType(id: string, identifierType = IdentifierType.UUID): Observable> { this.dataService.setLinkPath(identifierType); return this.dataService.findById(id).pipe( diff --git a/src/app/core/data/persistent-identifier-data.service.ts b/src/app/core/data/persistent-identifier-data.service.ts deleted file mode 100644 index bd7d12a7c6..0000000000 --- a/src/app/core/data/persistent-identifier-data.service.ts +++ /dev/null @@ -1,24 +0,0 @@ -/** - * The contents of this file are subject to the license and copyright - * detailed in the LICENSE and NOTICE files at the root of the source - * tree and available online at - * - * http://www.dspace.org/license/ - */ -import { RequestService } from './request.service'; -import { RemoteDataBuildService } from '../cache/builders/remote-data-build.service'; -import { ObjectCacheService } from '../cache/object-cache.service'; -import { HALEndpointService } from '../shared/hal-endpoint.service'; -import { IdentifiableDataService } from './base/identifiable-data.service'; -import { DSpaceObject } from '../shared/dspace-object.model'; - -export class PersistentIdentifierDataService extends IdentifiableDataService { - constructor( - protected requestService: RequestService, - protected rdbService: RemoteDataBuildService, - protected objectCache: ObjectCacheService, - protected halService: HALEndpointService, - ) { - super('pid', requestService, rdbService, objectCache, halService); - } -} diff --git a/src/app/core/submission/vocabularies/vocabulary-entry-details.data.service.ts b/src/app/core/submission/vocabularies/vocabulary-entry-details.data.service.ts index f19c0c00c2..ab7646042e 100644 --- a/src/app/core/submission/vocabularies/vocabulary-entry-details.data.service.ts +++ b/src/app/core/submission/vocabularies/vocabulary-entry-details.data.service.ts @@ -22,6 +22,9 @@ import { Injectable } from '@angular/core'; import { VOCABULARY_ENTRY_DETAIL } from './models/vocabularies.resource-type'; import { dataService } from '../../data/base/data-service.decorator'; +/** + * Data service to retrieve vocabulary entry details from the REST server. + */ @Injectable() @dataService(VOCABULARY_ENTRY_DETAIL) export class VocabularyEntryDetailsDataService extends IdentifiableDataService implements FindAllData, SearchData { diff --git a/src/app/core/submission/vocabularies/vocabulary.data.service.ts b/src/app/core/submission/vocabularies/vocabulary.data.service.ts index e4e17b7e73..ef642a6793 100644 --- a/src/app/core/submission/vocabularies/vocabulary.data.service.ts +++ b/src/app/core/submission/vocabularies/vocabulary.data.service.ts @@ -21,6 +21,9 @@ import { Injectable } from '@angular/core'; import { VOCABULARY } from './models/vocabularies.resource-type'; import { dataService } from '../../data/base/data-service.decorator'; +/** + * Data service to retrieve vocabularies from the REST server. + */ @Injectable() @dataService(VOCABULARY) export class VocabularyDataService extends IdentifiableDataService implements FindAllData {