[ADF-2905] Added JSDocs for core (#3281)

* [ADF-2905] Updated JSDocs for core

* [ADF-2905] Added missing JSDoc for user pref service

lib/core/form/components/widgets/text/text-mask.component.ts

@@ -41,6 +41,7 @@ export const CUSTOM_INPUT_CONTROL_VALUE_ACCESSOR: any = {
 })
 export class InputMaskDirective implements OnChanges, ControlValueAccessor {
 
+    /** Object defining mask and "reversed" status. */
     @Input('textMask') inputMask: {
         mask: '',
         isReversed: false

lib/core/services/highlight-transform.service.ts

@@ -26,6 +26,7 @@ export class HighlightTransformService {
      * @param text Text to search within
      * @param search Text pattern to search for
      * @param wrapperClass CSS class used to provide highlighting style
+     * @returns New text along with boolean value to indicate whether anything was highlighted 
      */
     public highlight(text: string, search: string, wrapperClass: string = 'highlight'): HightlightTransformResult {
         let isMatching = false,

lib/core/services/log.service.ts

@@ -41,6 +41,11 @@ export class LogService {
         this.onMessage = new Subject();
     }
 
+    /**
+     * Logs a message at the "ERROR" level.
+     * @param message Message to log
+     * @param optionalParams Interpolation values for the message in "printf" format
+     */
     error(message?: any, ...optionalParams: any[]) {
         if (this.currentLogLevel >= LogLevelsEnum.ERROR) {
 
@@ -50,6 +55,11 @@ export class LogService {
         }
     }
 
+    /**
+     * Logs a message at the "DEBUG" level.
+     * @param message Message to log
+     * @param optionalParams Interpolation values for the message in "printf" format
+     */
     debug(message?: any, ...optionalParams: any[]) {
         if (this.currentLogLevel >= LogLevelsEnum.DEBUG) {
 
@@ -59,6 +69,11 @@ export class LogService {
         }
     }
 
+    /**
+     * Logs a message at the "INFO" level.
+     * @param message Message to log
+     * @param optionalParams Interpolation values for the message in "printf" format
+     */
     info(message?: any, ...optionalParams: any[]) {
         if (this.currentLogLevel >= LogLevelsEnum.INFO) {
 
@@ -68,6 +83,11 @@ export class LogService {
         }
     }
 
+    /**
+     * Logs a message at any level from "TRACE" upwards.
+     * @param message Message to log
+     * @param optionalParams Interpolation values for the message in "printf" format
+     */
     log(message?: any, ...optionalParams: any[]) {
         if (this.currentLogLevel >= LogLevelsEnum.TRACE) {
 
@@ -77,6 +97,11 @@ export class LogService {
         }
     }
 
+    /**
+     * Logs a message at the "TRACE" level.
+     * @param message Message to log
+     * @param optionalParams Interpolation values for the message in "printf" format
+     */
     trace(message?: any, ...optionalParams: any[]) {
         if (this.currentLogLevel >= LogLevelsEnum.TRACE) {
 
@@ -86,6 +111,11 @@ export class LogService {
         }
     }
 
+    /**
+     * Logs a message at the "WARN" level.
+     * @param message Message to log
+     * @param optionalParams Interpolation values for the message in "printf" format
+     */
     warn(message?: any, ...optionalParams: any[]) {
         if (this.currentLogLevel >= LogLevelsEnum.WARN) {
 
@@ -95,6 +125,12 @@ export class LogService {
         }
     }
 
+    /**
+     * Logs a message if a boolean test fails.
+     * @param test Test value (typically a boolean expression)
+     * @param message Message to show if test is false
+     * @param optionalParams Interpolation values for the message in "printf" format
+     */
     assert(test?: boolean, message?: string, ...optionalParams: any[]) {
         if (this.currentLogLevel !== LogLevelsEnum.SILENT) {
 
@@ -104,18 +140,31 @@ export class LogService {
         }
     }
 
+    /**
+     * Starts an indented group of log messages.
+     * @param groupTitle Title shown at the start of the group
+     * @param optionalParams Interpolation values for the title in "printf" format
+     */
     group(groupTitle?: string, ...optionalParams: any[]) {
         if (this.currentLogLevel !== LogLevelsEnum.SILENT) {
             console.group(groupTitle, ...optionalParams);
         }
     }
 
+    /**
+     * Ends a indented group of log messages.
+     */
     groupEnd() {
         if (this.currentLogLevel !== LogLevelsEnum.SILENT) {
             console.groupEnd();
         }
     }
 
+    /**
+     * Converts a log level name string into its numeric equivalent.
+     * @param level Level name
+     * @returns Numeric log level
+     */
     getLogLevel(level: string): LogLevelsEnum {
         let referencedLevel = logLevels.find((currentLevel: any) => {
             return currentLevel.name.toLocaleLowerCase() === level.toLocaleLowerCase();
@@ -124,6 +173,11 @@ export class LogService {
         return referencedLevel ? referencedLevel.level : 5;
     }
 
+    /**
+     * Triggers notification callback for log messages.
+     * @param text Message text
+     * @param logLevel Log level for the message
+     */
     messageBus(text: string, logLevel: string) {
         this.onMessage.next({ text: text, type: logLevel });
     }

lib/core/services/notification.service.ts

@@ -30,6 +30,7 @@ export class NotificationService {
      * Opens a snackbar notification to show a message.
      * @param message The message to show
      * @param millisecondsDuration Time before notification disappears after being shown
+     * @returns Information/control object for the snackbar
      */
     public openSnackMessage(message: string, millisecondsDuration?: number): MatSnackBarRef<any> {
         return this.snackbar.open(message, null, {
@@ -42,6 +43,7 @@ export class NotificationService {
      * @param message The message to show
      * @param action Caption for the response button
      * @param millisecondsDuration Time before the notification disappears (unless the button is clicked)
+     * @returns Information/control object for the snackbar
      */
     public openSnackMessageAction(message: string, action: string, millisecondsDuration?: number): MatSnackBarRef<any> {
         return this.snackbar.open(message, action, {

lib/core/services/shared-links-api.service.ts

@@ -36,6 +36,7 @@ export class SharedLinksApiService {
     /**
      * Gets shared links available to the current user.
      * @param options Options supported by JSAPI
+     * @returns List of shared links
      */
     getSharedLinks(options: any = {}): Observable<NodePaging> {
         const { sharedLinksApi, handleError } = this;
@@ -54,9 +55,10 @@ export class SharedLinksApiService {
     }
 
     /**
-     * Create a shared links available to the current user.
-     * @param nodeId
+     * Creates a shared link available to the current user.
+     * @param nodeId ID of the node to link to
      * @param options Options supported by JSAPI
+     * @returns The shared link just created
      */
     createSharedLinks(nodeId: string, options: any = {}): Observable<SharedLinkEntry> {
         const { sharedLinksApi, handleError } = this;
@@ -69,8 +71,9 @@ export class SharedLinksApiService {
     }
 
     /**
-     * delete shared links
-     * @param sharedId to delete
+     * Deletes a shared link.
+     * @param sharedId ID of the link to delete
+     * @returns Null response notifying when the operation is complete
      */
     deleteSharedLink(sharedId: string): Observable<SharedLinkEntry> {
         const { sharedLinksApi, handleError } = this;

lib/core/services/sites.service.ts

@@ -32,6 +32,7 @@ export class SitesService {
     /**
      * Gets a list of all sites in the repository.
      * @param opts Options supported by JSAPI
+     * @returns List of sites
      */
     getSites(opts: any = {}): Observable<SitePaging> {
         const defaultOptions = {
@@ -47,6 +48,7 @@ export class SitesService {
      * Gets the details for a site.
      * @param siteId ID of the target site
      * @param opts Options supported by JSAPI
+     * @returns Information about the site
      */
     getSite(siteId: string, opts?: any): Observable<SiteEntry> {
         return Observable.fromPromise(this.apiService.getInstance().core.sitesApi.getSite(siteId, opts))
@@ -57,6 +59,7 @@ export class SitesService {
      * Deletes a site.
      * @param siteId Site to delete
      * @param permanentFlag True: deletion is permanent; False: site is moved to the trash
+     * @returns Null response notifying when the operation is complete
      */
     deleteSite(siteId: string, permanentFlag: boolean = true): Observable<any> {
         let options: any = {};
@@ -68,6 +71,7 @@ export class SitesService {
     /**
      * Gets a site's content.
      * @param siteId ID of the target site
+     * @returns Site content
      */
     getSiteContent(siteId: string): Observable<SiteEntry> {
         return this.getSite(siteId, { relations: ['containers'] });
@@ -76,6 +80,7 @@ export class SitesService {
     /**
      * Gets a list of all a site's members.
      * @param siteId ID of the target site
+     * @returns Site members
      */
     getSiteMembers(siteId: string): Observable<SiteEntry> {
         return this.getSite(siteId, { relations: ['members'] });
@@ -83,6 +88,7 @@ export class SitesService {
 
     /**
      * Gets the username of the user currently logged into ACS.
+     * @returns Username string
      */
     getEcmCurrentLoggedUserName(): string {
         return this.apiService.getInstance().ecmAuth.username;

lib/core/services/storage.service.ts

@@ -30,6 +30,7 @@ export class StorageService {
     /**
      * Gets an item.
      * @param key Key to identify the item
+     * @returns The item (if any) retrieved by the key
      */
     getItem(key: string): string | null {
         if (this.useLocalStorage) {
@@ -76,6 +77,7 @@ export class StorageService {
     /**
      * Is any item currently stored under `key`?
      * @param key Key identifying item to check
+     * @returns True if key retrieves an item, false otherwise
      */
     hasItem(key: string): boolean {
         if (this.useLocalStorage) {

lib/core/services/thumbnail.service.ts

@@ -158,6 +158,7 @@ export class ThumbnailService {
     /**
      * Gets a thumbnail URL for the given document node.
      * @param node Node to get URL for.
+     * @returns URL string
      */
     public getDocumentThumbnailUrl(node: any): string {
         let thumbnail = this.contentService.getDocumentThumbnailUrl(node);
@@ -167,6 +168,7 @@ export class ThumbnailService {
     /**
      * Gets a thumbnail URL for a MIME type.
      * @param mimeType MIME type for the thumbnail
+     * @returns URL string
      */
     public getMimeTypeIcon(mimeType: string): string {
         let icon = this.mimeTypeIcons[mimeType];
@@ -175,6 +177,7 @@ export class ThumbnailService {
 
     /**
      * Gets a "miscellaneous" thumbnail URL for types with no other icon defined.
+     * @returns URL string
      */
     public getDefaultMimeTypeIcon(): string {
         return this.DEFAULT_ICON;

lib/core/services/translation.service.ts

@@ -90,6 +90,10 @@ export class TranslationService {
         }
     }
 
+    /**
+     * Triggers a notification callback when the translation language changes.
+     * @param lang The new language code
+     */
     onTranslationChanged(lang: string): void {
         this.translate.onTranslationChange.next({
             lang: lang,
@@ -100,6 +104,7 @@ export class TranslationService {
     /**
      * Sets the target language for translations.
      * @param lang Code name for the language
+     * @returns Translations available for the language
      */
     use(lang: string): Observable<any> {
         this.customLoader.init(lang);
@@ -110,6 +115,7 @@ export class TranslationService {
      * Gets the translation for the supplied key.
      * @param key Key to translate
      * @param interpolateParams String(s) to be interpolated into the main message
+     * @returns Translated text
      */
     get(key: string|Array<string>, interpolateParams?: Object): Observable<string|any> {
         return this.translate.get(key, interpolateParams);
@@ -119,6 +125,7 @@ export class TranslationService {
      * Directly returns the translation for the supplied key.
      * @param key Key to translate
      * @param interpolateParams String(s) to be interpolated into the main message
+     * @returns Translated text
      */
     instant(key: string | Array<string>, interpolateParams?: Object): string | any {
         return this.translate.instant(key, interpolateParams);

lib/core/services/user-preferences.service.ts

@@ -75,6 +75,11 @@ export class UserPreferencesService {
         this.userPreferenceStatus[UserPreferenceValues.DisableCSRF] = this.disableCSRF;
     }
 
+    /**
+     * Sets up a callback to notify when a property has changed.
+     * @param property The property to watch
+     * @returns Notification callback
+     */
     select(property: string): Observable<any> {
         return this.onChange.map((userPreferenceStatus) => userPreferenceStatus[property]).distinctUntilChanged();
     }
@@ -83,6 +88,7 @@ export class UserPreferencesService {
      * Gets a preference property.
      * @param property Name of the property
      * @param defaultValue Default to return if the property is not found
+     * @returns Preference property
      */
     get(property: string, defaultValue?: string): string {
         const key = this.getPropertyKey(property);
@@ -108,7 +114,10 @@ export class UserPreferencesService {
         this.onChangeSubject.next(this.userPreferenceStatus);
     }
 
-    /** Gets the active storage prefix for preferences. */
+    /**
+     * Gets the active storage prefix for preferences.
+     * @returns Storage prefix
+     */
     getStoragePrefix(): string {
         return this.storage.getItem('USER_PROFILE') || 'GUEST';
     }
@@ -124,12 +133,16 @@ export class UserPreferencesService {
     /**
      * Gets the full property key with prefix.
      * @param property The property name
+     * @returns Property key
      */
     getPropertyKey(property: string): string {
         return `${this.getStoragePrefix()}__${property}`;
     }
 
-    /** Gets an array containing the available page sizes. */
+    /**
+     * Gets an array containing the available page sizes.
+     * @returns Array of page size values
+     */
     getDefaultPageSizes(): number[] {
         return this.defaults.supportedPageSizes;
     }
@@ -174,7 +187,10 @@ export class UserPreferencesService {
         this.set('LOCALE', value);
     }
 
-    /** Gets the default locale. */
+    /**
+     * Gets the default locale.
+     * @returns Default locale language code
+     */
     public getDefaultLocale(): string {
         return this.appConfig.get<string>('locale') || this.translate.getBrowserLang() || 'en';
     }