[ADF-2905] Added JSDocs for process services (#3292)

* [ADF-2905] Added JSDocs for process services

* [ADF-2905] Added missing return value in tasklist service

lib/process-services/people/components/people-search/people-search.component.ts

@@ -32,15 +32,19 @@ import { PerformSearchCallback } from '../../interfaces/perform-search-callback.
 
 export class PeopleSearchComponent implements OnInit {
 
+    /** Parameters for displaying the list. */
     @Input()
     results: Observable<UserProcessModel[]>;
 
+    /** Emitted when a search is performed with a new keyword. */
     @Output()
     searchPeople: EventEmitter<any> = new EventEmitter();
 
+    /** Emitted when a user is selected and the action button is clicked. */
     @Output()
     success: EventEmitter<UserProcessModel> = new EventEmitter<UserProcessModel>();
 
+    /** Emitted when the "close" button is clicked. */
     @Output()
     closeSearch = new EventEmitter();
 

lib/process-services/process-list/services/process-filter.service.ts

@@ -30,6 +30,7 @@ export class ProcessFilterService {
     /**
      * Gets all filters defined for a Process App.
      * @param appId ID of the target app
+     * @returns Array of filter details
      */
     getProcessFilters(appId: number): Observable<FilterProcessRepresentationModel[]> {
         return Observable.fromPromise(this.callApiProcessFilters(appId))
@@ -48,6 +49,7 @@ export class ProcessFilterService {
      * Retrieves the process filter by ID.
      * @param filterId ID of the filter
      * @param appId ID of the target app
+     * @returns Details of the filter
      */
     getProcessFilterById(filterId: number, appId?: number): Observable<FilterProcessRepresentationModel> {
         return Observable.fromPromise(this.callApiProcessFilters(appId))
@@ -60,6 +62,7 @@ export class ProcessFilterService {
      * Retrieves the process filter by name.
      * @param filterName Name of the filter
      * @param appId ID of the target app
+     * @returns Details of the filter
      */
     getProcessFilterByName(filterName: string, appId?: number): Observable<FilterProcessRepresentationModel> {
         return Observable.fromPromise(this.callApiProcessFilters(appId))
@@ -71,6 +74,7 @@ export class ProcessFilterService {
     /**
      * Creates and returns the default filters for an app.
      * @param appId ID of the target app
+     * @returns Default filters just created
      */
     public createDefaultFilters(appId: number): Observable<FilterProcessRepresentationModel[]> {
         let runningFilter = this.getRunningFilterInstance(appId);
@@ -114,6 +118,7 @@ export class ProcessFilterService {
     /**
      * Creates and returns a filter that matches "running" process instances.
      * @param appId ID of the target app
+     * @returns Filter just created
      */
     public getRunningFilterInstance(appId: number): FilterProcessRepresentationModel {
         return new FilterProcessRepresentationModel({
@@ -128,6 +133,7 @@ export class ProcessFilterService {
     /**
      * Returns a static Completed filter instance.
      * @param appId ID of the target app
+     * @returns Details of the filter
      */
     private getCompletedFilterInstance(appId: number): FilterProcessRepresentationModel {
         return new FilterProcessRepresentationModel({
@@ -142,6 +148,7 @@ export class ProcessFilterService {
     /**
      * Returns a static All filter instance.
      * @param appId ID of the target app
+     * @returns Details of the filter
      */
     private getAllFilterInstance(appId: number): FilterProcessRepresentationModel {
         return new FilterProcessRepresentationModel({
@@ -156,6 +163,7 @@ export class ProcessFilterService {
     /**
      * Adds a filter.
      * @param filter The filter to add
+     * @returns The filter just added
      */
     addProcessFilter(filter: FilterProcessRepresentationModel): Observable<FilterProcessRepresentationModel> {
         return Observable.fromPromise(this.alfrescoApiService.getInstance().activiti.userFiltersApi.createUserProcessInstanceFilter(filter))
@@ -168,6 +176,7 @@ export class ProcessFilterService {
     /**
      * Calls `getUserProcessInstanceFilters` from the Alfresco JS API.
      * @param appId ID of the target app
+     * @returns List of filter details
      */
     callApiProcessFilters(appId?: number) {
         if (appId) {

lib/process-services/process-list/services/process.service.ts

@@ -35,9 +35,10 @@ export class ProcessService {
     }
 
     /**
-     * Get process instances for a filter and optionally a process definition.
+     * Gets process instances for a filter and optionally a process definition.
      * @param requestNode Filter for instances
      * @param processDefinitionKey Limits returned instances to a process definition
+     * @returns List of process instances
      */
     getProcessInstances(requestNode: ProcessFilterParamRepresentationModel, processDefinitionKey?: string): Observable<ProcessListModel> {
         return Observable.fromPromise(this.alfrescoApiService.getInstance().activiti.processApi.getProcessInstances(requestNode))
@@ -53,8 +54,9 @@ export class ProcessService {
     }
 
     /**
-     * Fetches the Process Audit information as a pdf
+     * Fetches the Process Audit information as a PDF.
      * @param processId ID of the target process
+     * @returns Binary PDF data
      */
     fetchProcessAuditPdfById(processId: string): Observable<Blob> {
         return Observable.fromPromise(this.alfrescoApiService.getInstance().activiti.processApi.getProcessAuditPdf(processId))
@@ -62,8 +64,9 @@ export class ProcessService {
     }
 
     /**
-     * Fetches the Process Audit information in a json format.
+     * Fetches the Process Audit information in a JSON format.
      * @param processId ID of the target process
+     * @returns JSON data
      */
     fetchProcessAuditJsonById(processId: string): Observable<any> {
         return Observable.fromPromise(this.alfrescoApiService.getInstance().activiti.processApi.getProcessAuditJson(processId))
@@ -73,6 +76,7 @@ export class ProcessService {
     /**
      * Gets Process Instance metadata.
      * @param processInstanceId ID of the target process
+     * @returns Metadata for the instance
      */
     getProcess(processInstanceId: string): Observable<ProcessInstance> {
         return Observable.fromPromise(this.alfrescoApiService.getInstance().activiti.processApi.getProcessInstance(processInstanceId))
@@ -83,6 +87,7 @@ export class ProcessService {
      * Gets task instances for a process instance.
      * @param processInstanceId ID of the process instance
      * @param state Task state filter (can be "active" or "completed")
+     * @returns Array of task instance details
      */
     getProcessTasks(processInstanceId: string, state?: string): Observable<TaskDetailsModel[]> {
         let taskOpts = state ? {
@@ -103,6 +108,7 @@ export class ProcessService {
     /**
      * Gets process definitions associated with an app.
      * @param appId ID of a target app
+     * @returns Array of process definitions
      */
     getProcessDefinitions(appId?: number): Observable<ProcessDefinitionRepresentation[]> {
         let opts = appId ? {
@@ -126,6 +132,7 @@ export class ProcessService {
      * @param outcome Process outcome
      * @param startFormValues Values for the start form
      * @param variables Array of process instance variables
+     * @returns Details of the process instance just started
      */
     startProcess(processDefinitionId: string, name: string, outcome?: string, startFormValues?: FormValues, variables?: ProcessInstanceVariable[]): Observable<ProcessInstance> {
         let startRequest: any = {
@@ -151,6 +158,7 @@ export class ProcessService {
     /**
      * Cancels a process instance.
      * @param processInstanceId ID of process to cancel
+     * @returns Null response notifying when the operation is complete
      */
     cancelProcess(processInstanceId: string): Observable<void> {
         return Observable.fromPromise(
@@ -162,6 +170,7 @@ export class ProcessService {
     /**
      * Gets the variables for a process instance.
      * @param processInstanceId ID of the target process
+     * @returns Array of instance variable info
      */
     getProcessInstanceVariables(processInstanceId: string): Observable<ProcessInstanceVariable[]> {
         return Observable.fromPromise(
@@ -175,6 +184,7 @@ export class ProcessService {
      * Creates or updates variables for a process instance.
      * @param processInstanceId ID of the target process
      * @param variables Variables to update
+     * @returns Array of instance variable info
      */
     createOrUpdateProcessInstanceVariables(processInstanceId: string, variables: ProcessInstanceVariable[]): Observable<ProcessInstanceVariable[]> {
         return Observable.fromPromise(
@@ -187,6 +197,7 @@ export class ProcessService {
      * Deletes a variable for a process instance.
      * @param processInstanceId ID of the target process
      * @param variableName Name of the variable to delete
+     * @returns Null response notifying when the operation is complete
      */
     deleteProcessInstanceVariable(processInstanceId: string, variableName: string): Observable<void> {
         return Observable.fromPromise(

lib/process-services/task-list/components/task-standalone.component.ts

@@ -26,21 +26,27 @@ import { Component, EventEmitter, Input, Output, ViewEncapsulation } from '@angu
 
 export class TaskStandaloneComponent {
 
+    /** Name of the task. */
     @Input()
     taskName: string;
 
+    /** If true then Task completed message is shown and `Complete` and `Cancel` buttons are hidden. */
     @Input()
     isCompleted: boolean = false;
 
+    /** Toggles rendering of the `Complete` button. */
     @Input()
     hasCompletePermission: boolean = true;
 
+    /** Toggles rendering of the `Cancel` button. */
     @Input()
     hideCancelButton: boolean = true;
 
+    /** Emitted when the "Cancel" button is clicked. */
     @Output()
     cancel: EventEmitter<void> = new EventEmitter<void>();
 
+    /** Emitted when the form associated with the task is completed. */
     @Output()
     complete: EventEmitter<void> = new EventEmitter<void>();
 

lib/process-services/task-list/services/task-filter.service.ts

@@ -37,6 +37,7 @@ export class TaskFilterService {
     /**
      * Creates and returns the default filters for a process app.
      * @param appId ID of the target app
+     * @returns Array of default filters just created
      */
     public createDefaultFilters(appId: number): Observable<FilterRepresentationModel[]> {
         let involvedTasksFilter = this.getInvolvedTasksFilterInstance(appId);
@@ -87,6 +88,7 @@ export class TaskFilterService {
     /**
      * Gets all task filters for a process app.
      * @param appId Optional ID for a specific app
+     * @returns Array of task filter details
      */
     getTaskListFilters(appId?: number): Observable<FilterRepresentationModel[]> {
         return Observable.fromPromise(this.callApiTaskFilters(appId))
@@ -104,6 +106,7 @@ export class TaskFilterService {
      * Gets a task filter by ID.
      * @param filterId ID of the filter
      * @param appId ID of the app for the filter
+     * @returns Details of task filter
      */
     getTaskFilterById(filterId: number, appId?: number): Observable<FilterRepresentationModel> {
         return Observable.fromPromise(this.callApiTaskFilters(appId))
@@ -116,6 +119,7 @@ export class TaskFilterService {
      * Gets a task filter by name.
      * @param taskName Name of the filter
      * @param appId ID of the app for the filter
+     * @returns Details of task filter
      */
     getTaskFilterByName(taskName: string, appId?: number): Observable<FilterRepresentationModel> {
         return Observable.fromPromise(this.callApiTaskFilters(appId))
@@ -127,6 +131,7 @@ export class TaskFilterService {
     /**
      * Adds a new task filter
      * @param filter The new filter to add
+     * @returns Details of task filter just added
      */
     addFilter(filter: FilterRepresentationModel): Observable<FilterRepresentationModel> {
         return Observable.fromPromise(this.apiService.getInstance().activiti.userFiltersApi.createUserTaskFilter(filter))
@@ -139,6 +144,7 @@ export class TaskFilterService {
     /**
      * Calls `getUserTaskFilters` from the Alfresco JS API.
      * @param appId ID of the target app
+     * @returns List of task filters
      */
     callApiTaskFilters(appId?: number) {
         if (appId) {
@@ -151,6 +157,7 @@ export class TaskFilterService {
     /**
      * Creates and returns a filter for "Involved" task instances.
      * @param appId ID of the target app
+     * @returns The newly created filter
      */
     getInvolvedTasksFilterInstance(appId: number): FilterRepresentationModel {
         return new FilterRepresentationModel({
@@ -165,6 +172,7 @@ export class TaskFilterService {
     /**
      * Creates and returns a filter for "My Tasks" task instances.
      * @param appId ID of the target app
+     * @returns The newly created filter
      */
     getMyTasksFilterInstance(appId: number): FilterRepresentationModel {
         return new FilterRepresentationModel({
@@ -179,6 +187,7 @@ export class TaskFilterService {
     /**
      * Creates and returns a filter for "Queued Tasks" task instances.
      * @param appId ID of the target app
+     * @returns The newly created filter
      */
     getQueuedTasksFilterInstance(appId: number): FilterRepresentationModel {
         return new FilterRepresentationModel({
@@ -193,6 +202,7 @@ export class TaskFilterService {
     /**
      * Creates and returns a filter for "Completed" task instances.
      * @param appId ID of the target app
+     * @returns The newly created filter
      */
     getCompletedTasksFilterInstance(appId: number): FilterRepresentationModel {
         return new FilterRepresentationModel({

lib/process-services/task-list/services/tasklist.service.ts

@@ -44,6 +44,7 @@ export class TaskListService {
      * Gets all the filters in the list that belong to a task.
      * @param taskId ID of the target task
      * @param filterList List of filters to search through
+     * @returns Filters belonging to the task
      */
     getFilterForTaskById(taskId: string, filterList: FilterRepresentationModel[]): Observable<FilterRepresentationModel> {
         return Observable.from(filterList)
@@ -54,6 +55,7 @@ export class TaskListService {
     /**
      * Gets the search query for a task based on the supplied filter.
      * @param filter The filter to use
+     * @returns The search query
      */
     private generateTaskRequestNodeFromFilter(filter: FilterRepresentationModel): TaskQueryRequestRepresentationModel {
         let requestNode = {
@@ -69,6 +71,7 @@ export class TaskListService {
      * Checks if a taskId is filtered with the given filter.
      * @param taskId ID of the target task
      * @param filter The filter you want to check
+     * @returns The filter if it is related or null otherwise
      */
      isTaskRelatedToFilter(taskId: string, filter: FilterRepresentationModel): Observable<FilterRepresentationModel> {
         let requestNodeForFilter = this.generateTaskRequestNodeFromFilter(filter);
@@ -81,6 +84,7 @@ export class TaskListService {
     /**
      * Gets all the tasks matching the supplied query.
      * @param requestNode Query to search for tasks
+     * @returns List of tasks
      */
     getTasks(requestNode: TaskQueryRequestRepresentationModel): Observable<TaskListModel> {
         return Observable.fromPromise(this.callApiTasksFiltered(requestNode))
@@ -94,6 +98,7 @@ export class TaskListService {
      * Gets tasks matching a query and state value.
      * @param requestNode Query to search for tasks
      * @param state Task state. Can be "open" or "completed".
+     * @returns List of tasks
      */
     findTasksByState(requestNode: TaskQueryRequestRepresentationModel, state?: string): Observable<TaskListModel> {
         if (state) {
@@ -106,6 +111,7 @@ export class TaskListService {
      * Gets all tasks matching a query and state value.
      * @param requestNode Query to search for tasks.
      * @param state Task state. Can be "open" or "completed".
+     * @returns List of tasks
      */
     findAllTaskByState(requestNode: TaskQueryRequestRepresentationModel, state?: string): Observable<TaskListModel> {
         if (state) {
@@ -118,8 +124,9 @@ export class TaskListService {
     }
 
     /**
-     * Get all tasks matching the supplied query but ignoring the task state.
+     * Gets all tasks matching the supplied query but ignoring the task state.
      * @param requestNode Query to search for tasks
+     * @returns List of tasks
      */
     findAllTasksWithoutState(requestNode: TaskQueryRequestRepresentationModel): Observable<TaskListModel> {
         return Observable.forkJoin(
@@ -138,6 +145,7 @@ export class TaskListService {
     /**
      * Gets details for a task.
      * @param taskId ID of the target task.
+     * @returns Task details
      */
     getTaskDetails(taskId: string): Observable<TaskDetailsModel> {
         return Observable.fromPromise(this.callApiTaskDetails(taskId))
@@ -150,6 +158,7 @@ export class TaskListService {
     /**
      * Gets the checklist for a task.
      * @param id ID of the target task
+     * @returns Array of checklist task details
      */
     getTaskChecklist(id: string): Observable<TaskDetailsModel[]> {
         return Observable.fromPromise(this.callApiTaskChecklist(id))
@@ -165,6 +174,7 @@ export class TaskListService {
 
     /**
      * Gets all available reusable forms.
+     * @returns Array of form details
      */
     getFormList(): Observable<Form []> {
         let opts = {
@@ -187,6 +197,7 @@ export class TaskListService {
      * Attaches a form to a task.
      * @param taskId ID of the target task
      * @param formId ID of the form to add
+     * @returns Null response notifying when the operation is complete
      */
     attachFormToATask(taskId: string, formId: number): Observable<any> {
         return Observable.fromPromise(this.apiService.taskApi.attachForm(taskId, {'formId': formId})).catch(err => this.handleError(err));
@@ -195,6 +206,7 @@ export class TaskListService {
     /**
      * Adds a subtask (ie, a checklist task) to a parent task.
      * @param task The task to add
+     * @returns The subtask that was added
      */
     addTask(task: TaskDetailsModel): Observable<TaskDetailsModel> {
         return Observable.fromPromise(this.callApiAddTask(task))
@@ -207,6 +219,7 @@ export class TaskListService {
     /**
      * Deletes a subtask (ie, a checklist task) from a parent task.
      * @param taskId The task to delete
+     * @returns Null response notifying when the operation is complete
      */
     deleteTask(taskId: string): Observable<TaskDetailsModel> {
         return Observable.fromPromise(this.callApiDeleteTask(taskId))
@@ -216,6 +229,7 @@ export class TaskListService {
     /**
      * Gives completed status to a task.
      * @param taskId ID of the target task
+     * @returns Null response notifying when the operation is complete
      */
     completeTask(taskId: string) {
         return Observable.fromPromise(this.apiService.taskApi.completeTask(taskId))
@@ -226,6 +240,7 @@ export class TaskListService {
     /**
      * Gets the total number of the tasks found by a query.
      * @param requestNode Query to search for tasks
+     * @returns Number of tasks
      */
     public getTotalTasks(requestNode: TaskQueryRequestRepresentationModel): Observable<any> {
         requestNode.size = 0;
@@ -238,6 +253,7 @@ export class TaskListService {
     /**
      * Creates a new standalone task.
      * @param task Details of the new task
+     * @returns Details of the newly created task
      */
     createNewTask(task: TaskDetailsModel): Observable<TaskDetailsModel> {
         return Observable.fromPromise(this.callApiCreateTask(task))
@@ -251,6 +267,7 @@ export class TaskListService {
      * Assigns a task to a user or group.
      * @param taskId The task to assign
      * @param requestNode User or group to assign the task to
+     * @returns Details of the assigned task
      */
     assignTask(taskId: string, requestNode: any): Observable<TaskDetailsModel> {
         let assignee = {assignee: requestNode.id};
@@ -265,6 +282,7 @@ export class TaskListService {
      * Assigns a task to a user.
      * @param taskId ID of the task to assign
      * @param userId ID of the user to assign the task to
+     * @returns Details of the assigned task
      */
     assignTaskByUserId(taskId: string, userId: number): Observable<TaskDetailsModel> {
         let assignee = {assignee: userId};
@@ -278,6 +296,7 @@ export class TaskListService {
     /**
      * Claims a task for the current user.
      * @param taskId ID of the task to claim
+     * @returns Details of the claimed task
      */
     claimTask(taskId: string): Observable<TaskDetailsModel> {
         return Observable.fromPromise(this.apiService.taskApi.claimTask(taskId))
@@ -287,6 +306,7 @@ export class TaskListService {
     /**
      * Unclaims a task for the current user.
      * @param taskId ID of the task to unclaim
+     * @returns Null response notifying when the operation is complete
      */
     unclaimTask(taskId: string): Observable<TaskDetailsModel> {
         return Observable.fromPromise(this.apiService.taskApi.unclaimTask(taskId))
@@ -297,6 +317,7 @@ export class TaskListService {
      * Updates the details (name, description, due date) for a task.
      * @param taskId ID of the task to update
      * @param updated Data to update the task (as a `TaskUpdateRepresentation` instance).
+     * @returns Updated task details
      */
     updateTask(taskId: any, updated): Observable<TaskDetailsModel> {
         return Observable.fromPromise(this.apiService.taskApi.updateTask(taskId, updated))
@@ -306,6 +327,7 @@ export class TaskListService {
     /**
      * Fetches the Task Audit information in PDF format.
      * @param taskId ID of the target task
+     * @returns Binary PDF data
      */
     fetchTaskAuditPdfById(taskId: string): Observable<Blob> {
         return Observable.fromPromise(this.apiService.taskApi.getTaskAuditPdf(taskId))
@@ -315,6 +337,7 @@ export class TaskListService {
     /**
      * Fetch the Task Audit information in JSON format
      * @param taskId ID of the target task
+     * @returns JSON data
      */
     fetchTaskAuditJsonById(taskId: string): Observable<any> {
         return Observable.fromPromise(this.apiService.taskApi.getTaskAuditJson(taskId))