[ADF-3551] Updates for doc review (#3784)

* [ADF-3551] Updated doc comments

* [ADF-3551] Updated doc comments

* [ADF-3551] Doc files updated with new doc comments

docs/content-services/custom-resources.service.md

@@ -1,7 +1,7 @@
 ---
 Added: v2.3.0
 Status: Active
-Last reviewed: 2018-05-03
+Last reviewed: 2018-09-13
 ---
 
 # Custom Resources service
@@ -12,7 +12,7 @@ Manages Document List information that is specific to a user.
 
 ### Methods
 
--   **getCorrespondingNodeIds**(nodeId: `string`, pagination: [`PaginationModel`](../../lib/core/models/pagination.model.ts)): [`Observable`](http://reactivex.io/documentation/observable.html)`<string[]>`<br/>
+-   **getCorrespondingNodeIds**(nodeId: `string`, pagination: [`PaginationModel`](../../lib/core/models/pagination.model.ts) = `{}`): [`Observable`](http://reactivex.io/documentation/observable.html)`<string[]>`<br/>
     Gets the contents of one of the well-known aliases in the form of node ID strings.
     -   _nodeId:_ `string`  - ID of the target folder node
     -   _pagination:_ [`PaginationModel`](../../lib/core/models/pagination.model.ts)  - Specifies how to paginate the results
@@ -22,10 +22,18 @@ Manages Document List information that is specific to a user.
     -   _personId:_ `string`  - ID of the user
     -   _pagination:_ [`PaginationModel`](../../lib/core/models/pagination.model.ts)  - Specifies how to paginate the results
     -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`NodePaging`](../../lib/content-services/document-list/models/document-library.model.ts)`>` - List of nodes for the recently used files
+-   **hasCorrespondingNodeIds**(nodeId: `string`): `boolean`<br/>
+    Does the well-known alias have a corresponding node ID?
+    -   _nodeId:_ `string`  - Node to check
+    -   **Returns** `boolean` - True if the alias has a corresponding node ID, false otherwise
 -   **isCustomSource**(folderId: `string`): `boolean`<br/>
     Is the folder ID one of the well-known aliases?
     -   _folderId:_ `string`  - Folder ID name to check
     -   **Returns** `boolean` - True if the ID is a well-known name, false otherwise
+-   **isSupportedSource**(folderId: `string`): `boolean`<br/>
+    Is the folder ID a "-my", "-root-", or "-shared-" alias?
+    -   _folderId:_ `string`  - Folder ID name to check
+    -   **Returns** `boolean` - True if the ID is one of the suppored sources, false otherwise
 -   **loadFavorites**(pagination: [`PaginationModel`](../../lib/core/models/pagination.model.ts), includeFields: `string[]` = `[]`): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`NodePaging`](../../lib/content-services/document-list/models/document-library.model.ts)`>`<br/>
     Gets favorite files for the current user.
     -   _pagination:_ [`PaginationModel`](../../lib/core/models/pagination.model.ts)  - Specifies how to paginate the results

docs/content-services/document-list.service.md

@@ -1,7 +1,7 @@
 ---
 Added: v2.0.0
 Status: Active
-Last reviewed: 2018-04-16
+Last reviewed: 2018-09-13
 ---
 
 # Document List service
@@ -12,11 +12,11 @@ Implements node operations used by the [Document List component](../content-serv
 
 ### Methods
 
--   **copyNode**(nodeId: `string`, targetParentId: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<any>`<br/>
+-   **copyNode**(nodeId: `string`, targetParentId: `string`): `any`<br/>
     Copy a node to destination node
     -   _nodeId:_ `string`  - The id of the node to be copied
     -   _targetParentId:_ `string`  - The id of the folder where the node will be copied
-    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<any>` - NodeEntry for the copied node
+    -   **Returns** `any` - [NodeEntry](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeEntry.md) for the copied node
 -   **createFolder**(name: `string`, parentId: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`MinimalNodeEntity`](../content-services/document-library.model.md)`>`<br/>
     Creates a new folder in the path.
     -   _name:_ `string`  - Folder name
@@ -40,7 +40,7 @@ Implements node operations used by the [Document List component](../content-serv
     -   _includeFields:_ `string[]`  - Extra information to include (available options are "aspectNames", "isLink" and "association")
     -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`NodePaging`](../../lib/content-services/document-list/models/document-library.model.ts)`>` - Details of the folder
 -   **getFolderNode**(nodeId: `string`, includeFields: `string[]` = `[]`): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`MinimalNodeEntryEntity`](../content-services/document-library.model.md)`>`<br/>
-    (**Deprecated:** 2.3.0 Gets a folder node via its node ID.) 
+    (**Deprecated:** 2.3.0. Gets a folder node via its node ID.) 
     -   _nodeId:_ `string`  - ID of the folder node
     -   _includeFields:_ `string[]`  - Extra information to include (available options are "aspectNames", "isLink" and "association")
     -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`MinimalNodeEntryEntity`](../content-services/document-library.model.md)`>` - Details of the folder
@@ -54,15 +54,15 @@ Implements node operations used by the [Document List component](../content-serv
     -   _includeFields:_ `string[]`  - Extra information to include (available options are "aspectNames", "isLink" and "association")
     -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`NodeEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeEntry.md)`>` - Details of the folder
 -   **hasPermission**(node: `any`, permission: [`PermissionsEnum`](../../lib/core/models/permissions.enum.ts)`|string`): `boolean`<br/>
-    (**Deprecated:** 2.3.0 use the one in the content service Checks if a node has the specified permission.) 
+    (**Deprecated:** 2.3.0 - use the equivalent in the content service. Checks if a node has the specified permission.) 
     -   _node:_ `any`  - Target node
     -   _permission:_ [`PermissionsEnum`](../../lib/core/models/permissions.enum.ts)`|string`  - Permission level to query
     -   **Returns** `boolean` - True if the node has the permission, false otherwise
--   **moveNode**(nodeId: `string`, targetParentId: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<any>`<br/>
+-   **moveNode**(nodeId: `string`, targetParentId: `string`): `any`<br/>
     Moves a node to destination node.
     -   _nodeId:_ `string`  - The id of the node to be moved
     -   _targetParentId:_ `string`  - The id of the folder where the node will be moved
-    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<any>` - NodeEntry for the moved node
+    -   **Returns** `any` - [NodeEntry](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeEntry.md) for the moved node
 
 ## Details
 

docs/content-services/inherited-button.directive.md

@@ -1,7 +1,7 @@
 ---
 Added: v2.3.0
 Status: Active
-Last reviewed: 2018-06-08
+Last reviewed: 2018-09-13
 ---
 
 # Inherit Permission directive
@@ -23,14 +23,14 @@ Update the current node by adding/removing the inherited permissions.
 
 | Name | Type | Default value | Description |
 | ---- | ---- | ------------- | ----------- |
-| nodeId | `string` |  | ID of the node to add/remove inherited permissions |
+| nodeId | `string` |  | ID of the node to add/remove inherited permissions. |
 
 ### Events
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| error | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<any>` |  |
+| error | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<any>` | Emitted when an error occurs. |
-| updated | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`MinimalNodeEntryEntity`](../content-services/document-library.model.md)`>` | Emitted when the node is updated |
+| updated | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`MinimalNodeEntryEntity`](../content-services/document-library.model.md)`>` | Emitted when the node is updated. |
 
 ## Details
 

docs/content-services/node-permission-dialog.service.md

@@ -1,7 +1,7 @@
 ---
 Added: v2.4.0
 Status: Active
-Last reviewed: 2018-05-23
+Last reviewed: 2018-09-13
 ---
 
 # Node permission dialog service
@@ -16,7 +16,7 @@ Displays dialogs to let the user set node permissions.
     Closes the currently-open dialog.
 -   **openAddPermissionDialog**(node: `Node`, title?: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`MinimalNodeEntity`](../content-services/document-library.model.md)`[]>`<br/>
     Opens a dialog to add permissions to a node.
-    -   _node:_ `Node`  - 
+    -   _node:_ `Node`  - ID of the target node
     -   _title:_ `string`  - (Optional) Dialog title
     -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`MinimalNodeEntity`](../content-services/document-library.model.md)`[]>` - Node with updated permissions
 -   **updateNodePermissionByDialog**(nodeId?: `string`, title?: `string`): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`MinimalNodeEntryEntity`](../content-services/document-library.model.md)`>`<br/>

docs/content-services/permission-list.component.md

@@ -1,7 +1,7 @@
 ---
 Added: v2.3.0
 Status: Active
-Last reviewed: 2018-05-03
+Last reviewed: 2018-09-13
 ---
 
 # Permission List Component
@@ -42,7 +42,7 @@ but you can also supply your own content:
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| error | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<any>` |  |
+| error | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<any>` | Emitted when an error occurs. |
 | update | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<PermissionElement>` | Emitted when the permission is updated. |
 
 ## Details

docs/content-services/tag.service.md

@@ -17,9 +17,10 @@ Manages tags in Content Services.
     -   _nodeId:_ `string`  - ID of the target node
     -   _tagName:_ `string`  - Name of the tag to add
     -   **Returns** `any` - TagEntry object (defined in JSAPI) with details of the new tag
--   **getAllTheTags**(): [`Observable`](http://reactivex.io/documentation/observable.html)`<any>`<br/>
+-   **getAllTheTags**(opts?: `any`): [`Observable`](http://reactivex.io/documentation/observable.html)`<TagPaging>`<br/>
     Gets a list of all the tags already defined in the repository.
-    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<any>` - TagPaging object (defined in JSAPI) containing the tags
+    -   _opts:_ `any`  - (Optional) Options supported by JSAPI
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<TagPaging>` - TagPaging object (defined in JSAPI) containing the tags
 -   **getTagsByNodeId**(nodeId: `string`): `any`<br/>
     Gets a list of tags added to a node.
     -   _nodeId:_ `string`  - ID of the target node

docs/content-services/upload-button.component.md

@@ -1,7 +1,7 @@
 ---
 Added: v2.0.0
 Status: Active
-Last reviewed: 2018-03-23
+Last reviewed: 2018-09-13
 ---
 
 # Upload Button Component
@@ -45,7 +45,7 @@ Activates a file upload.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| beginUpload | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`UploadFilesEvent`](../../lib/content-services/upload/components/upload-files.event.ts)`>` |  |
+| beginUpload | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`UploadFilesEvent`](../../lib/content-services/upload/components/upload-files.event.ts)`>` | Emitted when the upload begins. |
 | createFolder | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<Object>` | Emitted when a folder is created. |
 | error | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<Object>` | Emitted when an error occurs. |
 | permissionEvent | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`PermissionModel`](../../lib/content-services/document-list/models/permissions.model.ts)`>` | Emitted when create permission is missing. |

docs/content-services/upload-drag-area.component.md

@@ -1,7 +1,7 @@
 ---
 Added: v2.0.0
 Status: Active
-Last reviewed: 2018-08-07
+Last reviewed: 2018-09-13
 ---
 
 # Upload Drag Area Component
@@ -72,7 +72,7 @@ as the drag/drop target:
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| beginUpload | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`UploadFilesEvent`](../../lib/content-services/upload/components/upload-files.event.ts)`>` | Raised after files or folders dropped and before the upload process starts. |
+| beginUpload | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`UploadFilesEvent`](../../lib/content-services/upload/components/upload-files.event.ts)`>` | Emitted when the upload begins. |
 | createFolder | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<Object>` | Emitted when a folder is created. |
 | error | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<Object>` | Emitted when an error occurs. |
 | success | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<Object>` | Emitted when the file is uploaded successfully. |

lib/content-services/document-list/services/custom-resources.service.ts

@@ -261,6 +261,11 @@ export class CustomResourcesService {
         return isCustomSources;
     }
 
+    /**
+     * Is the folder ID a "-my", "-root-", or "-shared-" alias?
+     * @param folderId Folder ID name to check
+     * @returns True if the ID is one of the suppored sources, false otherwise
+     */
     isSupportedSource(folderId: string): boolean {
         let isSupportedSources = false;
         const sources = ['-my-', '-root-', '-shared-'];
@@ -330,6 +335,11 @@ export class CustomResourcesService {
         return of([]);
     }
 
+    /**
+     * Does the well-known alias have a corresponding node ID?
+     * @param nodeId Node to check
+     * @returns True if the alias has a corresponding node ID, false otherwise
+     */
     hasCorrespondingNodeIds(nodeId: string): boolean {
         return this.isCustomSource(nodeId) || this.isSupportedSource(nodeId);
     }

lib/content-services/document-list/services/document-list.service.ts

@@ -150,8 +150,7 @@ export class DocumentListService {
     }
 
     /**
-     * @deprecated 2.3.0
+     * @deprecated 2.3.0. Gets a folder node via its node ID.
-     * Gets a folder node via its node ID.
      * @param nodeId ID of the folder node
      * @param includeFields Extra information to include (available options are "aspectNames", "isLink" and "association")
      * @returns Details of the folder
@@ -195,8 +194,7 @@ export class DocumentListService {
     }
 
     /**
-     * @Deprecated 2.3.0 use the one in the content service
+     * @Deprecated 2.3.0 - use the equivalent in the content service. Checks if a node has the specified permission.
-     * Checks if a node has the specified permission.
      * @param node Target node
      * @param permission Permission level to query
      * @returns True if the node has the permission, false otherwise

lib/content-services/permission-manager/components/inherited-button.directive.ts

@@ -29,12 +29,15 @@ import { MinimalNodeEntryEntity } from 'alfresco-js-api';
 })
 export class InheritPermissionDirective {
 
+    /** ID of the node to add/remove inherited permissions. */
     @Input()
     nodeId: string;
 
+    /** Emitted when the node is updated. */
     @Output()
     updated: EventEmitter<MinimalNodeEntryEntity> = new EventEmitter<MinimalNodeEntryEntity>();
 
+    /** Emitted when an error occurs. */
     @Output()
     error: EventEmitter<any> = new EventEmitter<any>();
 

lib/content-services/permission-manager/components/permission-list/permission-list.component.ts

@@ -37,6 +37,7 @@ export class PermissionListComponent implements OnInit {
     @Output()
     update: EventEmitter<PermissionElement> = new EventEmitter();
 
+    /** Emitted when an error occurs. */
     @Output()
     error: EventEmitter<any> = new EventEmitter();
 

lib/content-services/permission-manager/services/node-permission-dialog.service.ts

@@ -35,7 +35,7 @@ export class NodePermissionDialogService {
 
     /**
      * Opens a dialog to add permissions to a node.
-     * @param nodeId ID of the target node
+     * @param node ID of the target node
      * @param title Dialog title
      * @returns Node with updated permissions
      */

lib/content-services/search/components/search-radio/search-radio.component.ts

@@ -37,6 +37,7 @@ export interface SearchRadioOption {
 })
 export class SearchRadioComponent implements SearchWidget, OnInit {
 
+    /** The value of the selected radio button. */
     @Input()
     value: string;
 

lib/content-services/search/components/search-slider/search-slider.component.ts

@@ -38,6 +38,7 @@ export class SearchSliderComponent implements SearchWidget, OnInit {
     max: number;
     thumbLabel = false;
 
+    /** The numeric value represented by the slider. */
     @Input()
     value: number | null;
 

lib/content-services/search/components/search-text/search-text.component.ts

@@ -29,6 +29,7 @@ import { SearchQueryBuilderService } from '../../search-query-builder.service';
 })
 export class SearchTextComponent implements SearchWidget, OnInit {
 
+    /** The content of the text box. */
     @Input()
     value = '';
 

lib/content-services/tag/services/tag.service.ts

@@ -45,6 +45,7 @@ export class TagService {
 
     /**
      * Gets a list of all the tags already defined in the repository.
+     * @param opts Options supported by JSAPI
      * @returns TagPaging object (defined in JSAPI) containing the tags
      */
     getAllTheTags(opts?: any): Observable<TagPaging> {

lib/content-services/upload/components/base-upload/upload-base.ts

@@ -72,6 +72,7 @@ export abstract class UploadBase implements OnInit, OnDestroy {
     @Output()
     error = new EventEmitter();
 
+    /** Emitted when the upload begins. */
     @Output()
     beginUpload = new EventEmitter<UploadFilesEvent>();
 

lib/core/services/cookie.service.ts

@@ -58,6 +58,7 @@ export class CookieService {
             (path ? `;path=${path}` : ';path=/');
     }
 
+    /** Placeholder for testing purposes - do not use. */
     clear() {
         /* placeholder for testing purposes */
     }