[ADF-1769] Added JSDocs for services (#2949)

docs/notification.service.md

@@ -4,6 +4,18 @@ Shows a notification message with optional feedback.
 
 ![Notification Service screenshot](docassets/images/NotiService.png)
 
+## Methods
+
+-   `openSnackMessage(message: string, millisecondsDuration?: number): MatSnackBarRef<any>`  
+    Opens a snackbar notification to show a message.  
+    -   `message` - The message to show
+    -   `millisecondsDuration` - (Optional) Time before notification disappears after being shown
+-   `openSnackMessageAction(message: string, action: string, millisecondsDuration?: number): MatSnackBarRef<any>`  
+    Opens a snackbar notification with a message and a response button.  
+    -   `message` - The message to show
+    -   `action` - Caption for the response button
+    -   `millisecondsDuration` - (Optional) Time before the notification disappears (unless the button is clicked)
+
 ## Details
 
 The Notification Service is implemented on top of the Angular Material Design snackbar.

docs/page-title.service.md

@@ -4,8 +4,9 @@ Sets the page title.
 
 ## Methods
 
-`setTitle(value: string = '')`<br/>
+-   `setTitle(value: string = '')`  
     Sets the page title.  
+    -   `value` - The new title
 
 ## Details
 

docs/people-content.service.md

@@ -4,12 +4,13 @@ Gets information about a Content Services user.
 
 ## Methods
 
-`getPerson(personId: string): Observable<any>`<br/>
+-   `getPerson(personId: string): Observable<any>`  
     Gets information about a user identified by their username.  
-
+    -   `personId` - ID of the target user
-`getCurrentPerson(): Observable<any>`<br/>
+-   `getCurrentPerson(): Observable<any>`  
     Gets information about the user who is currently logged-in.   
 
+
 ## Details
 
 The class returned by `getPerson` and `getCurrentPerson` is detailed

docs/people-process.service.md

@@ -4,17 +4,21 @@ Gets information about Process Services users.
 
 ## Methods
 
-`getWorkflowUsers(taskId?: string, searchWord?: string): Observable<UserProcessModel[]>`<br/>
+-   `getWorkflowUsers(taskId?: string, searchWord?: string): Observable<UserProcessModel[]>`  
     Gets information about users across all tasks.  
-
+    -   `taskId` - (Optional) ID of the task
-`getUserImage(user: UserProcessModel): string`<br/>
+    -   `searchWord` - (Optional) Filter text to search for
+-   `getUserImage(user: UserProcessModel): string`  
     Gets the profile picture URL for the specified user.  
-
+    -   `user` - The target user
-`involveUserWithTask(taskId: string, idToInvolve: string): Observable<UserProcessModel[]>`<br/>
+-   `involveUserWithTask(taskId: string, idToInvolve: string): Observable<UserProcessModel[]>`  
     Sets a user to be involved with a task.  
-
+    -   `taskId` - ID of the target task
-`removeInvolvedUser(taskId: string, idToRemove: string): Observable<UserProcessModel[]>`<br/>
+    -   `idToInvolve` - ID of the user to involve
+-   `removeInvolvedUser(taskId: string, idToRemove: string): Observable<UserProcessModel[]>`  
     Removes a user who is currently involved with a task.  
+    -   `taskId` - ID of the target task
+    -   `idToRemove` - ID of the user to remove
 
 ## Details
 

docs/rating.service.md

@@ -4,14 +4,19 @@ Manages ratings for items in Content Services.
 
 ## Methods
 
-`getRating(nodeId: string, ratingType: any): any`<br/>
+-   `getRating(nodeId: string, ratingType: any): any`  
     Gets the current user's rating for a node.  
-
+    -   `nodeId` - Node to get the rating from
-`postRating(nodeId: string, ratingType: any, vote: any): any`<br/>
+    -   `ratingType` - Type of rating (can be "likes" or "fiveStar")
+-   `postRating(nodeId: string, ratingType: any, vote: any): any`  
     Adds the current user's rating for a node.  
-
+    -   `nodeId` - Target node for the rating
-`deleteRating(nodeId: string, ratingType: any): any`<br/>
+    -   `ratingType` - Type of rating (can be "likes" or "fiveStar")
+    -   `vote` - Rating value (boolean for "likes", numeric 0..5 for "fiveStar")
+-   `deleteRating(nodeId: string, ratingType: any): any`  
     Removes the current user's rating for a node.  
+    -   `nodeId` - Target node
+    -   `ratingType` - Type of rating to remove (can be "likes" or "fiveStar")
 
 ## Details
 

docs/shared-links-api.service.md

@@ -4,8 +4,9 @@ Finds shared links to Content Services items.
 
 ## Methods
 
-`getSharedLinks(options: any = {}): Observable<NodePaging>`<br/>
+-   `getSharedLinks(options: any = {}): Observable<NodePaging>`  
     Gets shared links available to the current user.  
+    -   `options` - Options supported by JSAPI
 
 ## Details
 

docs/sites.service.md

@@ -4,20 +4,23 @@ Accesses and manipulates sites from a Content Services repository.
 
 ## Methods
 
-`getSites(opts: any = {}): any`<br/>
+-   `getSites(opts: any = {}): Observable<SitePaging>`  
     Gets a list of all sites in the repository.  
-
+    -   `opts` - Options supported by JSAPI
-`getSite(siteId: string, opts?: any): any`<br/>
+-   `getSite(siteId: string, opts?: any): Observable<SiteEntry>`  
     Gets the details for a site.  
-
+    -   `siteId` - ID of the target site
-`deleteSite(siteId: string, permanentFlag: boolean = true): any`<br/>
+    -   `opts` - (Optional) Options supported by JSAPI
+-   `deleteSite(siteId: string, permanentFlag: boolean = true): Observable<any>`  
     Deletes a site.  
-
+    -   `siteId` - Site to delete
-`getSiteContent(siteId: string): Observable<any>`<br/>
+    -   `permanentFlag` - True: deletion is permanent; False: site is moved to the trash
+-   `getSiteContent(siteId: string): Observable<SiteEntry>`  
     Gets a site's content.  
-
+    -   `siteId` - ID of the target site
-`getSiteMembers(siteId: string): Observable<any>`<br/>
+-   `getSiteMembers(siteId: string): Observable<SiteEntry>`  
     Gets a list of all a site's members.  
+    -   `siteId` - ID of the target site
 
 ## Details
 

docs/storage.service.md

@@ -4,20 +4,22 @@ Stores items in the form of key-value pairs.
 
 ## Methods
 
-`getItem(key: string): string | null` <br/>
+-   `getItem(key: string): string`  
-Gets an item identified by `key`.
+    Gets an item.  
-
+    -   `key` - Key to identify the item
-`setItem(key: string, data: string)` <br/>
+-   `setItem(key: string, data: string)`  
-Stores an item under `key`.
+    Stores an item  
-
+    -   `key` - Key to identify the item
-`clear()` <br/>
+    -   `data` - Data to store
+-   `clear()`  
     Removes all currently stored items.   
 
-`removeItem(key: string)` <br/>
+-   `removeItem(key: string)`  
-Removes the item identified by `key`.
+    Removes a single item.  
-
+    -   `key` - Key to identify the item
-`hasItem(key: string): boolean` <br/>
+-   `hasItem(key: string): boolean`  
     Is any item currently stored under `key`?  
+    -   `key` - Key identifying item to check
 
 ## Details
 

lib/content-services/social/services/rating.service.ts

@@ -28,12 +28,23 @@ export class RatingService {
     constructor(private apiService: AlfrescoApiService) {
     }
 
+    /**
+     * Gets the current user's rating for a node.
+     * @param nodeId Node to get the rating from
+     * @param ratingType Type of rating (can be "likes" or "fiveStar")
+     */
     getRating(nodeId: string, ratingType: any): any {
         return Observable.fromPromise(this.apiService.getInstance().core.ratingsApi.getRating(nodeId, ratingType))
             .map(res => res)
             .catch(this.handleError);
     }
 
+    /**
+     * Adds the current user's rating for a node.
+     * @param nodeId Target node for the rating
+     * @param ratingType Type of rating (can be "likes" or "fiveStar")
+     * @param vote Rating value (boolean for "likes", numeric 0..5 for "fiveStar")
+     */
     postRating(nodeId: string, ratingType: any, vote: any): any {
         let ratingBody: RatingBody = {
             'id': ratingType,
@@ -44,6 +55,11 @@ export class RatingService {
             .catch(this.handleError);
     }
 
+    /**
+     * Removes the current user's rating for a node.
+     * @param nodeId Target node
+     * @param ratingType Type of rating to remove (can be "likes" or "fiveStar")
+     */
     deleteRating(nodeId: string, ratingType: any): any {
         return Observable.fromPromise(this.apiService.getInstance().core.ratingsApi.removeRating(nodeId, ratingType))
             .map(res => res)

lib/core/services/notification.service.ts

@@ -26,12 +26,23 @@ export class NotificationService {
     constructor(public snackbar: MatSnackBar) {
     }
 
+    /**
+     * Opens a snackbar notification to show a message.
+     * @param message The message to show
+     * @param millisecondsDuration Time before notification disappears after being shown
+     */
     public openSnackMessage(message: string, millisecondsDuration?: number): MatSnackBarRef<any> {
         return this.snackbar.open(message, null, {
             duration: millisecondsDuration || NotificationService.DEFAULT_DURATION_MESSAGE
         });
     }
 
+    /**
+     * Opens a snackbar notification with a message and a response button.
+     * @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)
+     */
     public openSnackMessageAction(message: string, action: string, millisecondsDuration?: number): MatSnackBarRef<any> {
         return this.snackbar.open(message, action, {
             duration: millisecondsDuration || NotificationService.DEFAULT_DURATION_MESSAGE

lib/core/services/page-title.service.ts

@@ -26,6 +26,10 @@ export class PageTitleService {
         private titleService: Title,
         private appConfig: AppConfigService) {}
 
+    /**
+     * Sets the page title.
+     * @param value The new title
+     */
     setTitle(value: string = '') {
         const name = this.appConfig.get('application.name') || 'Alfresco ADF Application';
         const title = value ? `${value} - ${name}` : `${name}`;

lib/core/services/people-content.service.ts

@@ -29,6 +29,10 @@ export class PeopleContentService {
        return this.apiService.getInstance().core.peopleApi;
     }
 
+    /**
+     * Gets information about a user identified by their username.
+     * @param personId ID of the target user
+     */
     getPerson(personId: string): Observable<any> {
         const { peopleApi, handleError } = this;
         const promise = peopleApi.getPerson(personId);
@@ -38,6 +42,7 @@ export class PeopleContentService {
             .catch(handleError);
     }
 
+    /** Gets information about the user who is currently logged-in. */
     getCurrentPerson(): Observable<any> {
         return this.getPerson('-me-');
     }

lib/core/services/people-process.service.ts

@@ -31,6 +31,11 @@ export class PeopleProcessService {
                 private logService: LogService) {
     }
 
+    /**
+     * Gets information about users across all tasks.
+     * @param taskId ID of the task
+     * @param searchWord Filter text to search for
+     */
     getWorkflowUsers(taskId?: string, searchWord?: string): Observable<UserProcessModel[]> {
         let option = { excludeTaskId: taskId, filter: searchWord };
         return Observable.fromPromise(this.getWorkflowUserApi(option))
@@ -38,16 +43,30 @@ export class PeopleProcessService {
             .catch(err => this.handleError(err));
     }
 
+    /**
+     * Gets the profile picture URL for the specified user.
+     * @param user The target user
+     */
     getUserImage(user: UserProcessModel): string {
         return this.getUserProfileImageApi(user.id);
     }
 
+    /**
+     * Sets a user to be involved with a task.
+     * @param taskId ID of the target task
+     * @param idToInvolve ID of the user to involve
+     */
     involveUserWithTask(taskId: string, idToInvolve: string): Observable<UserProcessModel[]> {
         let node = {userId: idToInvolve};
         return Observable.fromPromise(this.involveUserToTaskApi(taskId, node))
             .catch(err => this.handleError(err));
     }
 
+    /**
+     * Removes a user who is currently involved with a task.
+     * @param taskId ID of the target task
+     * @param idToRemove ID of the user to remove
+     */
     removeInvolvedUser(taskId: string, idToRemove: string): Observable<UserProcessModel[]> {
         let node = {userId: idToRemove};
         return Observable.fromPromise(this.removeInvolvedUserFromTaskApi(taskId, node))

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

@@ -33,6 +33,10 @@ export class SharedLinksApiService {
        return this.apiService.getInstance().core.sharedlinksApi;
     }
 
+    /**
+     * Gets shared links available to the current user.
+     * @param options Options supported by JSAPI
+     */
     getSharedLinks(options: any = {}): Observable<NodePaging> {
         const { sharedLinksApi, handleError } = this;
         const defaultOptions = {

lib/core/services/sites.service.ts

@@ -29,6 +29,10 @@ export class SitesService {
     constructor(
         private apiService: AlfrescoApiService) { }
 
+    /**
+     * Gets a list of all sites in the repository.
+     * @param opts Options supported by JSAPI
+     */
     getSites(opts: any = {}): Observable<SitePaging> {
         const defaultOptions = {
             skipCount: 0,
@@ -39,11 +43,21 @@ export class SitesService {
             .catch(this.handleError);
     }
 
+    /**
+     * Gets the details for a site.
+     * @param siteId ID of the target site
+     * @param opts Options supported by JSAPI
+     */
     getSite(siteId: string, opts?: any): Observable<SiteEntry> {
         return Observable.fromPromise(this.apiService.getInstance().core.sitesApi.getSite(siteId, opts))
             .catch(this.handleError);
     }
 
+    /**
+     * Deletes a site.
+     * @param siteId Site to delete
+     * @param permanentFlag True: deletion is permanent; False: site is moved to the trash
+     */
     deleteSite(siteId: string, permanentFlag: boolean = true): Observable<any> {
         let options: any = {};
         options.permanent = permanentFlag;
@@ -51,10 +65,18 @@ export class SitesService {
             .catch(this.handleError));
     }
 
+    /**
+     * Gets a site's content.
+     * @param siteId ID of the target site
+     */
     getSiteContent(siteId: string): Observable<SiteEntry> {
         return this.getSite(siteId, { relations: ['containers'] });
     }
 
+    /**
+     * Gets a list of all a site's members.
+     * @param siteId ID of the target site
+     */
     getSiteMembers(siteId: string): Observable<SiteEntry> {
         return this.getSite(siteId, { relations: ['members'] });
     }

lib/core/services/storage.service.ts

@@ -27,6 +27,10 @@ export class StorageService {
         this.useLocalStorage = this.storageAvailable('localStorage');
     }
 
+    /**
+     * Gets an item.
+     * @param key Key to identify the item
+     */
     getItem(key: string): string | null {
         if (this.useLocalStorage) {
             return localStorage.getItem(key);
@@ -35,6 +39,11 @@ export class StorageService {
         }
     }
 
+    /**
+     * Stores an item
+     * @param key Key to identify the item
+     * @param data Data to store
+     */
     setItem(key: string, data: string) {
         if (this.useLocalStorage) {
             localStorage.setItem(key, data);
@@ -43,6 +52,7 @@ export class StorageService {
         }
     }
 
+    /** Removes all currently stored items. */
     clear() {
         if (this.useLocalStorage) {
             localStorage.clear();
@@ -51,6 +61,10 @@ export class StorageService {
         }
     }
 
+    /**
+     * Removes a single item.
+     * @param key Key to identify the item
+     */
     removeItem(key: string) {
         if (this.useLocalStorage) {
             localStorage.removeItem(key);
@@ -59,6 +73,10 @@ export class StorageService {
         }
     }
 
+    /**
+     * Is any item currently stored under `key`?
+     * @param key Key identifying item to check
+     */
     hasItem(key: string): boolean {
         if (this.useLocalStorage) {
             return localStorage.getItem(key) ? true : false;