[ADF-3745] Updates for doc review (#4203)

docs/core/identity-user.service.md

@@ -2,7 +2,7 @@
 Title: Identity user service
 Added: v3.0.0
 Status: Active
-Last reviewed: 2019-01-09
+Last reviewed: 2019-01-23
 ---
 
 # [Identity user service](../../lib/core/userinfo/services/identity-user.service.ts "Defined in identity-user.service.ts")
@@ -13,6 +13,41 @@ Gets OAuth2 personal details and roles for users.
 
 ### Methods
 
+-   **checkUserHasAnyApplicationRole**(userId: `string`, applicationName: `string`, roleNames: `string[]`): [`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>`<br/>
+    Checks if a user has any application role.
+    -   _userId:_ `string`  - ID of the target user
+    -   _applicationName:_ `string`  - Name of the application
+    -   _roleNames:_ `string[]`  - List of role names to check for
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>` - True if the user has one or more of the roles, false otherwise
+-   **checkUserHasAnyClientAppRole**(userId: `string`, clientId: `string`, roleNames: `string[]`): [`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>`<br/>
+    Checks whether a user has any of the client app roles.
+    -   _userId:_ `string`  - ID of the target user
+    -   _clientId:_ `string`  - ID of the client app
+    -   _roleNames:_ `string[]`  - List of role names to check for
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>` - True if the user has one or more of the roles, false otherwise
+-   **checkUserHasApplicationAccess**(userId: `string`, applicationName: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>`<br/>
+    Checks if a user has access to an application.
+    -   _userId:_ `string`  - ID of the user
+    -   _applicationName:_ `string`  - Name of the application
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>` - True if the user has access, false otherwise
+-   **checkUserHasClientApp**(userId: `string`, clientId: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>`<br/>
+    Checks whether user has access to a client app.
+    -   _userId:_ `string`  - ID of the target user
+    -   _clientId:_ `string`  - ID of the client app
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>` - True if the user has access, false otherwise
+-   **findUsersByName**(search: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<any>`<br/>
+    Find users based on search input.
+    -   _search:_ `string`  - Search query string
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<any>` - List of users
+-   **getClientIdByApplicationName**(applicationName: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<string>`<br/>
+    Gets the client ID for an application.
+    -   _applicationName:_ `string`  - Name of the application
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<string>` - Client ID string
+-   **getClientRoles**(userId: `string`, clientId: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<any[]>`<br/>
+    Get client roles of a user for a particular client.
+    -   _userId:_ `string`  - ID of the target user
+    -   _clientId:_ `string`  - ID of the client app
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<any[]>` - List of client roles
 -   **getCurrentUserInfo**(): [`IdentityUserModel`](../../lib/core/userinfo/models/identity-user.model.ts)<br/>
     Gets the name and other basic details of the current user.
     -   **Returns** [`IdentityUserModel`](../../lib/core/userinfo/models/identity-user.model.ts) - The user's details

docs/core/renditions.service.md

@@ -2,28 +2,61 @@
 Title: Renditions service
 Added: v2.0.0
 Status: Active
+Last reviewed: 2019-01-23
 ---
 
 # [Renditions service](../../lib/core/services/renditions.service.ts "Defined in renditions.service.ts")
 
 Manages prearranged conversions of content to different formats.
 
-## Methods
+## Class members
 
-`isRenditionAvailable(nodeId: string, encoding: string):`[`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>`<br/>
-Has the specified rendition been set up for this item?
+### Methods
 
-`isConversionPossible(nodeId: string, encoding: string):`[`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>`<br/>
-Is it possible to convert this item to the specified format?
-
-`getRenditionUrl(nodeId: string, encoding: string): string`<br/>
-Gets a URL linking to a rendition.
-
-`getRenditionsListByNodeId(nodeId: string):`[`Observable`](http://reactivex.io/documentation/observable.html)`<RenditionPaging>`<br/>
-Gets all available renditions for an item.
-
-`convert(nodeId: string, encoding: string, pollingInterval: number = 1000)`<br/>
-Performs a format conversion on an item directly.
+-   **convert**(nodeId: `string`, encoding: `string`, pollingInterval: `number` = `1000`, retries: `number` = `5`): [`Observable`](http://reactivex.io/documentation/observable.html)`<Object>`<br/>
+    Repeatedly attempts to create a rendition, through to success or failure.
+    -   _nodeId:_ `string`  - ID of the target node
+    -   _encoding:_ `string`  - Name of the rendition encoding
+    -   _pollingInterval:_ `number`  - Time interval (in milliseconds) between checks for completion
+    -   _retries:_ `number`  - Number of attempts to make before declaring failure
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<Object>` - True if the rendition was created, false otherwise
+-   **createRendition**(nodeId: `string`, encoding: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<__type>`<br/>
+    Creates a rendition for a node.
+    -   _nodeId:_ `string`  - ID of the target node
+    -   _encoding:_ `string`  - Name of the rendition encoding
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<__type>` - Null response to indicate completion
+-   **generateRenditionForNode**(nodeId: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<any>`<br/>
+    Generates a rendition for a node using the first available encoding.
+    -   _nodeId:_ `string`  - ID of the target node
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<any>` - Null response to indicate completion
+-   **getAvailableRenditionForNode**(nodeId: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`RenditionEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionEntry.md)`>`<br/>
+    Gets the first available rendition found for a node.
+    -   _nodeId:_ `string`  - ID of the target node
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`RenditionEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionEntry.md)`>` - Information object for the rendition
+-   **getRendition**(nodeId: `string`, encoding: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`RenditionEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionEntry.md)`>`<br/>
+    Gets information about a rendition of a node.
+    -   _nodeId:_ `string`  - ID of the target node
+    -   _encoding:_ `string`  - Name of the rendition encoding
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`RenditionEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionEntry.md)`>` - Information object about the rendition
+-   **getRenditionUrl**(nodeId: `string`, encoding: `string`): `string`<br/>
+    Gets a URL linking to the specified rendition of a node.
+    -   _nodeId:_ `string`  - ID of the target node
+    -   _encoding:_ `string`  - Name of the rendition encoding
+    -   **Returns** `string` - URL string
+-   **getRenditionsListByNodeId**(nodeId: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`RenditionPaging`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionPaging.md)`>`<br/>
+    Gets a list of all renditions for a node.
+    -   _nodeId:_ `string`  - ID of the target node
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`RenditionPaging`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionPaging.md)`>` - Paged list of rendition details
+-   **isConversionPossible**(nodeId: `string`, encoding: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>`<br/>
+    Checks if the node can be converted using the specified rendition.
+    -   _nodeId:_ `string`  - ID of the target node
+    -   _encoding:_ `string`  - Name of the rendition encoding
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>` - True if the node can be converted, false otherwise
+-   **isRenditionAvailable**(nodeId: `string`, encoding: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>`<br/>
+    Checks if the specified rendition is available for a node.
+    -   _nodeId:_ `string`  - ID of the target node
+    -   _encoding:_ `string`  - Name of the rendition encoding
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<boolean>` - True if the rendition is available, false otherwise
 
 ## Details
 
@@ -42,5 +75,5 @@ in the ADF API. The `encoding` identifies the conversion performed by the rendit
 See the
 [Renditions API page](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionsApi.md#createRendition)
 in the Alfresco JS API for more information about the
-[RenditionPaging](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionPaging.md)
+[`RenditionPaging`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionPaging.md)
 class and other implementation details.

docs/process-services-cloud/edit-task-filter-cloud.component.md

@@ -25,23 +25,23 @@ Edits Task Filter Details.
 | Name | Type | Default value | Description |
 | ---- | ---- | ------------- | ----------- |
 | appName | `string` |  | (required) Name of the app. |
-| id | `string` | "" | (required) The id of the Task filter. |
-| filterProperties | `string []` | `['state', 'assignment', 'sort', 'order']` | List of task filter properties to display. |
-| toggleFilterActions | `boolean` | `true` | Toggles edit task filter actions. |
-| showTitle | `boolean` | `true` | Toggles edit task filter title. |
+| filterProperties | `string[]` |  | List of task filter properties to display. |
+| id | `string` |  | (required) ID of the task filter. |
+| showTitle | `boolean` | true | Toggles the title. |
+| toggleFilterActions | `boolean` | true | Toggles the filter actions. |
 
 ### Events
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
 | action | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`FilterActionType`](../../lib/process-services-cloud/src/lib/task/task-filters/models/filter-cloud.model.ts)`>` | Emitted when a filter action occurs (i.e Save, Save As, Delete). |
-| filterChange | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`TaskFilterCloudModel`](../../lib/process-services-cloud/src/lib/task/task-filters/models/filter-cloud.model.ts)`>` | Emitted when a task filter property changes. |
+| filterChange | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`TaskFilterCloudModel`](../../lib/process-services-cloud/src/lib/task/task-filters/models/filter-cloud.model.ts)`>` | Emitted when an task filter property changes. |
 
 ## Details
 
 ### Editing APS2 task filter
 
-Use the application name and task filter id property to edit task filter properties:
+Use the `appName` and `id` properties to edit task filter properties:
 
 ```html
 <adf-cloud-edit-task-filter
@@ -54,10 +54,10 @@ By default these below properties are displayed:
 
 **_state_**, **_assignment_**, **_sort_**, **_order_**.
 
-However, you can also choose which properties to show using a input property
-`filterProperties`:
+However, you can also choose which properties to show using the
+`filterProperties` input property:
 
-Populate the filterProperties in the component class:
+Populate the `filterProperties` in the component class:
 
 ```ts
 import { UserProcessModel } from '@alfresco/adf-core';
@@ -91,8 +91,7 @@ With this configuration, only the four listed properties will be shown.
 </adf-cloud-edit-task-filter>
 ```
 
-
-All Available properties are:
+The available properties are:
 
 **_appName_**, **_state_**, **_assignment_**, **_sort_**, **_order_**, **_processDefinitionId_**, **_processInstanceId_**, **_dueAfter_**, **_dueBefore_**, **_claimedDateFrom_**, **_claimedDateTo_**, **_createdDateFrom_**, **_createdDateTo_**, **_taskName_**, **_parentTaskId_**, **_priority_**, **_standAlone_**, **_lastModifiedFrom_**, **_lastModifiedTo_**, **_owner_**, **_dueDateFrom_**, **_dueDateTo_**.
 

lib/core/form/services/form.service.ts

@@ -484,7 +484,7 @@ export class FormService {
 
     /**
      * Gets the ID of a form.
-     * @param res Object representing a form
+     * @param form Object representing a form
      * @returns ID string
      */
     getFormId(form: any): string {

lib/core/services/renditions.service.ts

@@ -29,6 +29,11 @@ export class RenditionsService {
     constructor(private apiService: AlfrescoApiService) {
     }
 
+    /**
+     * Gets the first available rendition found for a node.
+     * @param nodeId ID of the target node
+     * @returns Information object for the rendition
+     */
     getAvailableRenditionForNode(nodeId: string): Observable<RenditionEntry> {
         return from(this.apiService.renditionsApi.getRenditions(nodeId)).pipe(
             map((availableRenditions: RenditionPaging) => {
@@ -39,6 +44,11 @@ export class RenditionsService {
             }));
     }
 
+    /**
+     * Generates a rendition for a node using the first available encoding.
+     * @param nodeId ID of the target node
+     * @returns Null response to indicate completion
+     */
     generateRenditionForNode(nodeId: string): Observable<any> {
         return this.getAvailableRenditionForNode(nodeId).pipe(
             map((rendition: RenditionEntry) => {
@@ -51,6 +61,12 @@ export class RenditionsService {
         );
     }
 
+    /**
+     * Checks if the specified rendition is available for a node.
+     * @param nodeId ID of the target node
+     * @param encoding Name of the rendition encoding
+     * @returns True if the rendition is available, false otherwise
+     */
     isRenditionAvailable(nodeId: string, encoding: string): Observable<boolean> {
         return new Observable((observer) => {
             this.getRendition(nodeId, encoding).subscribe(
@@ -70,6 +86,12 @@ export class RenditionsService {
         });
     }
 
+    /**
+     * Checks if the node can be converted using the specified rendition.
+     * @param nodeId ID of the target node
+     * @param encoding Name of the rendition encoding
+     * @returns True if the node can be converted, false otherwise
+     */
     isConversionPossible(nodeId: string, encoding: string): Observable<boolean> {
         return new Observable((observer) => {
             this.getRendition(nodeId, encoding).subscribe(
@@ -85,22 +107,53 @@ export class RenditionsService {
         });
     }
 
+    /**
+     * Gets a URL linking to the specified rendition of a node.
+     * @param nodeId ID of the target node
+     * @param encoding Name of the rendition encoding
+     * @returns URL string
+     */
     getRenditionUrl(nodeId: string, encoding: string): string {
         return this.apiService.contentApi.getRenditionUrl(nodeId, encoding);
     }
 
+    /**
+     * Gets information about a rendition of a node.
+     * @param nodeId ID of the target node
+     * @param encoding Name of the rendition encoding
+     * @returns Information object about the rendition
+     */
     getRendition(nodeId: string, encoding: string): Observable<RenditionEntry> {
         return from(this.apiService.renditionsApi.getRendition(nodeId, encoding));
     }
 
+    /**
+     * Gets a list of all renditions for a node.
+     * @param nodeId ID of the target node
+     * @returns Paged list of rendition details
+     */
     getRenditionsListByNodeId(nodeId: string): Observable<RenditionPaging> {
         return from(this.apiService.renditionsApi.getRenditions(nodeId));
     }
 
+    /**
+     * Creates a rendition for a node.
+     * @param nodeId ID of the target node
+     * @param encoding Name of the rendition encoding
+     * @returns Null response to indicate completion
+     */
     createRendition(nodeId: string, encoding: string): Observable<{}> {
         return from(this.apiService.renditionsApi.createRendition(nodeId, { id: encoding }));
     }
 
+    /**
+     * Repeatedly attempts to create a rendition, through to success or failure.
+     * @param nodeId ID of the target node
+     * @param encoding Name of the rendition encoding
+     * @param pollingInterval Time interval (in milliseconds) between checks for completion
+     * @param retries Number of attempts to make before declaring failure
+     * @returns True if the rendition was created, false otherwise
+     */
     convert(nodeId: string, encoding: string, pollingInterval: number = 1000, retries: number = 5) {
         return this.createRendition(nodeId, encoding)
             .pipe(

lib/core/userinfo/services/identity-user.service.ts

@@ -44,6 +44,7 @@ export class IdentityUserService {
 
     /**
      * Gets the name and other basic details of the current user.
+     * @returns The user's details
      */
     getCurrentUserInfo(): IdentityUserModel {
         const familyName = this.getValueFromToken<string>(IdentityUserService.FAMILY_NAME);
@@ -56,6 +57,8 @@ export class IdentityUserService {
 
     /**
      * Gets a named value from the user access token.
+     * @param key Key name of the field to retrieve
+     * @returns Value from the token
      */
     getValueFromToken<T>(key: string): T {
         let value;
@@ -69,6 +72,8 @@ export class IdentityUserService {
 
     /**
      * Find users based on search input.
+     * @param search Search query string
+     * @returns List of users
      */
     findUsersByName(search: string): Observable<any> {
         if (search === '') {
@@ -87,6 +92,9 @@ export class IdentityUserService {
 
     /**
      * Get client roles of a user for a particular client.
+     * @param userId ID of the target user
+     * @param clientId ID of the client app
+     * @returns List of client roles
      */
     getClientRoles(userId: string, clientId: string): Observable<any[]> {
         const url = this.buildUserClientRoleMapping(userId, clientId);
@@ -102,6 +110,9 @@ export class IdentityUserService {
 
     /**
      * Checks whether user has access to a client app.
+     * @param userId ID of the target user
+     * @param clientId ID of the client app
+     * @returns True if the user has access, false otherwise
      */
     checkUserHasClientApp(userId: string, clientId: string): Observable<boolean> {
         return this.getClientRoles(userId, clientId).pipe(
@@ -115,7 +126,11 @@ export class IdentityUserService {
     }
 
     /**
-     * Checks whether user has any of client app role.
+     * Checks whether a user has any of the client app roles.
+     * @param userId ID of the target user
+     * @param clientId ID of the client app
+     * @param roleNames List of role names to check for
+     * @returns True if the user has one or more of the roles, false otherwise
      */
     checkUserHasAnyClientAppRole(userId: string, clientId: string, roleNames: string[]): Observable<boolean> {
         return this.getClientRoles(userId, clientId).pipe(
@@ -139,7 +154,9 @@ export class IdentityUserService {
     }
 
     /**
-     * Get client id for an application.
+     * Gets the client ID for an application.
+     * @param applicationName Name of the application
+     * @returns Client ID string
      */
     getClientIdByApplicationName(applicationName: string): Observable<string> {
         const url = this.buildGetClientsUrl();
@@ -158,10 +175,10 @@ export class IdentityUserService {
     }
 
     /**
-     * Checks a user has access to an application
-     * @param userId Id of the user
+     * Checks if a user has access to an application.
+     * @param userId ID of the user
      * @param applicationName Name of the application
-     * @returns Boolean
+     * @returns True if the user has access, false otherwise
      */
     checkUserHasApplicationAccess(userId: string, applicationName: string): Observable<boolean> {
         return this.getClientIdByApplicationName(applicationName).pipe(
@@ -172,7 +189,11 @@ export class IdentityUserService {
     }
 
     /**
-     * Checks a user has any application role
+     * Checks if a user has any application role.
+     * @param userId ID of the target user
+     * @param applicationName Name of the application
+     * @param roleNames List of role names to check for
+     * @returns True if the user has one or more of the roles, false otherwise
      */
     checkUserHasAnyApplicationRole(userId: string, applicationName: string, roleNames: string[]): Observable<boolean> {
         return this.getClientIdByApplicationName(applicationName).pipe(
@@ -184,6 +205,7 @@ export class IdentityUserService {
 
     /**
      * Gets details for all users.
+     * @returns Array of user info objects
      */
     getUsers(): Observable<IdentityUserModel[]> {
         const url = this.buildUserUrl();
@@ -203,6 +225,8 @@ export class IdentityUserService {
 
     /**
      * Gets a list of roles for a user.
+     * @param userId ID of the user
+     * @returns Array of role info objects
      */
     getUserRoles(userId: string): Observable<IdentityRoleModel[]> {
         const url = this.buildRolesUrl(userId);
@@ -222,6 +246,8 @@ export class IdentityUserService {
 
     /**
      * Gets an array of users (including the current user) who have any of the roles in the supplied list.
+     * @param roleNames List of role names to look for
+     * @returns Array of user info objects
      */
     async getUsersByRolesWithCurrentUser(roleNames: string[]): Promise<IdentityUserModel[]> {
         const filteredUsers: IdentityUserModel[] = [];
@@ -241,6 +267,8 @@ export class IdentityUserService {
 
     /**
      * Gets an array of users (not including the current user) who have any of the roles in the supplied list.
+     * @param roleNames List of role names to look for
+     * @returns Array of user info objects
      */
     async getUsersByRolesWithoutCurrentUser(roleNames: string[]): Promise<IdentityUserModel[]> {
         const filteredUsers: IdentityUserModel[] = [];

lib/process-services-cloud/src/lib/task/task-filters/components/edit-task-filter-cloud.component.ts

@@ -51,6 +51,7 @@ export class EditTaskFilterCloudComponent implements OnChanges {
     @Input()
     id: string;
 
+    /** List of task filter properties to display. */
     @Input()
     filterProperties: string[] = EditTaskFilterCloudComponent.DEFAULT_TASK_FILTER_PROPERTIES; // default ['state', 'assignment', 'sort', 'order']
 

tools/doc/doctool.config.json

@@ -48,6 +48,8 @@
         "NodeEntry": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeEntry.md",
         "ProcessInstanceFilterRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/alfresco-activiti-rest-api/docs/ProcessInstanceFilterRepresentation.md",
         "RelatedContentRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-activiti-rest-api/docs/RelatedContentRepresentation.md",
+        "RenditionEntry": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionEntry.md",
+        "RenditionPaging": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionPaging.md",
         "SiteEntry": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/SiteEntry.md",
         "SitePaging": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/SitePaging.md",
         "TagEntry": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/TagEntry.md",