From 3ba72f00f8604f9328f087905bd3ba14a3f23380 Mon Sep 17 00:00:00 2001 From: Andy Stark <30621568+therealandeeee@users.noreply.github.com> Date: Thu, 13 Sep 2018 12:59:57 +0100 Subject: [PATCH] [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 | 12 ++++++++++-- docs/content-services/document-list.service.md | 14 +++++++------- .../content-services/inherited-button.directive.md | 8 ++++---- .../node-permission-dialog.service.md | 4 ++-- docs/content-services/permission-list.component.md | 4 ++-- docs/content-services/tag.service.md | 5 +++-- docs/content-services/upload-button.component.md | 4 ++-- .../content-services/upload-drag-area.component.md | 4 ++-- .../services/custom-resources.service.ts | 10 ++++++++++ .../services/document-list.service.ts | 6 ++---- .../components/inherited-button.directive.ts | 3 +++ .../permission-list/permission-list.component.ts | 1 + .../services/node-permission-dialog.service.ts | 2 +- .../search-radio/search-radio.component.ts | 1 + .../search-slider/search-slider.component.ts | 1 + .../search-text/search-text.component.ts | 1 + lib/content-services/tag/services/tag.service.ts | 1 + .../upload/components/base-upload/upload-base.ts | 1 + lib/core/services/cookie.service.ts | 1 + 19 files changed, 55 insertions(+), 28 deletions(-) diff --git a/docs/content-services/custom-resources.service.md b/docs/content-services/custom-resources.service.md index 2ef69224be..75ad816186 100644 --- a/docs/content-services/custom-resources.service.md +++ b/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)``
+- **getCorrespondingNodeIds**(nodeId: `string`, pagination: [`PaginationModel`](../../lib/core/models/pagination.model.ts) = `{}`): [`Observable`](http://reactivex.io/documentation/observable.html)``
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`
+ 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`
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`
+ 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)`>`
Gets favorite files for the current user. - _pagination:_ [`PaginationModel`](../../lib/core/models/pagination.model.ts) - Specifies how to paginate the results diff --git a/docs/content-services/document-list.service.md b/docs/content-services/document-list.service.md index a28314365a..0ec855043c 100644 --- a/docs/content-services/document-list.service.md +++ b/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)``
+- **copyNode**(nodeId: `string`, targetParentId: `string`): `any`
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)`` - 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)`>`
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)`>`
- (**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`
- (**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)``
+- **moveNode**(nodeId: `string`, targetParentId: `string`): `any`
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)`` - 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 diff --git a/docs/content-services/inherited-button.directive.md b/docs/content-services/inherited-button.directive.md index be9c0e7830..22c770ed50 100644 --- a/docs/content-services/inherited-button.directive.md +++ b/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)`` | | -| updated | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`MinimalNodeEntryEntity`](../content-services/document-library.model.md)`>` | Emitted when the node is updated | +| error | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`` | 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. | ## Details diff --git a/docs/content-services/node-permission-dialog.service.md b/docs/content-services/node-permission-dialog.service.md index c097bc3ff7..c0522dfa53 100644 --- a/docs/content-services/node-permission-dialog.service.md +++ b/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)`[]>`
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)`>`
diff --git a/docs/content-services/permission-list.component.md b/docs/content-services/permission-list.component.md index e6cc0273e7..8d59d96aab 100644 --- a/docs/content-services/permission-list.component.md +++ b/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)`` | | +| error | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`` | Emitted when an error occurs. | | update | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`` | Emitted when the permission is updated. | ## Details diff --git a/docs/content-services/tag.service.md b/docs/content-services/tag.service.md index ea51688254..2e090c9254 100644 --- a/docs/content-services/tag.service.md +++ b/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)``
+- **getAllTheTags**(opts?: `any`): [`Observable`](http://reactivex.io/documentation/observable.html)``
Gets a list of all the tags already defined in the repository. - - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`` - TagPaging object (defined in JSAPI) containing the tags + - _opts:_ `any` - (Optional) Options supported by JSAPI + - **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`` - TagPaging object (defined in JSAPI) containing the tags - **getTagsByNodeId**(nodeId: `string`): `any`
Gets a list of tags added to a node. - _nodeId:_ `string` - ID of the target node diff --git a/docs/content-services/upload-button.component.md b/docs/content-services/upload-button.component.md index d9b100c23f..cd2dc0d2ca 100644 --- a/docs/content-services/upload-button.component.md +++ b/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)`` | Emitted when a folder is created. | | error | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`` | 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. | diff --git a/docs/content-services/upload-drag-area.component.md b/docs/content-services/upload-drag-area.component.md index 04b48851ce..5298f30918 100644 --- a/docs/content-services/upload-drag-area.component.md +++ b/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)`` | Emitted when a folder is created. | | error | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`` | Emitted when an error occurs. | | success | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`` | Emitted when the file is uploaded successfully. | diff --git a/lib/content-services/document-list/services/custom-resources.service.ts b/lib/content-services/document-list/services/custom-resources.service.ts index 1cde8a171e..e247e7b368 100644 --- a/lib/content-services/document-list/services/custom-resources.service.ts +++ b/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); } diff --git a/lib/content-services/document-list/services/document-list.service.ts b/lib/content-services/document-list/services/document-list.service.ts index 30cadbcffe..3a27493923 100644 --- a/lib/content-services/document-list/services/document-list.service.ts +++ b/lib/content-services/document-list/services/document-list.service.ts @@ -150,8 +150,7 @@ export class DocumentListService { } /** - * @deprecated 2.3.0 - * Gets a folder node via its node ID. + * @deprecated 2.3.0. 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 - * 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. * @param node Target node * @param permission Permission level to query * @returns True if the node has the permission, false otherwise diff --git a/lib/content-services/permission-manager/components/inherited-button.directive.ts b/lib/content-services/permission-manager/components/inherited-button.directive.ts index 12d4adbb71..31bafcc6ad 100644 --- a/lib/content-services/permission-manager/components/inherited-button.directive.ts +++ b/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 = new EventEmitter(); + /** Emitted when an error occurs. */ @Output() error: EventEmitter = new EventEmitter(); diff --git a/lib/content-services/permission-manager/components/permission-list/permission-list.component.ts b/lib/content-services/permission-manager/components/permission-list/permission-list.component.ts index 2facc2869e..5b6e0aa755 100644 --- a/lib/content-services/permission-manager/components/permission-list/permission-list.component.ts +++ b/lib/content-services/permission-manager/components/permission-list/permission-list.component.ts @@ -37,6 +37,7 @@ export class PermissionListComponent implements OnInit { @Output() update: EventEmitter = new EventEmitter(); + /** Emitted when an error occurs. */ @Output() error: EventEmitter = new EventEmitter(); diff --git a/lib/content-services/permission-manager/services/node-permission-dialog.service.ts b/lib/content-services/permission-manager/services/node-permission-dialog.service.ts index 043ac1506b..5afdf0ded8 100644 --- a/lib/content-services/permission-manager/services/node-permission-dialog.service.ts +++ b/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 */ diff --git a/lib/content-services/search/components/search-radio/search-radio.component.ts b/lib/content-services/search/components/search-radio/search-radio.component.ts index a1383d448f..268a0c6889 100644 --- a/lib/content-services/search/components/search-radio/search-radio.component.ts +++ b/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; diff --git a/lib/content-services/search/components/search-slider/search-slider.component.ts b/lib/content-services/search/components/search-slider/search-slider.component.ts index 5b1d72a668..85b9819b97 100644 --- a/lib/content-services/search/components/search-slider/search-slider.component.ts +++ b/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; diff --git a/lib/content-services/search/components/search-text/search-text.component.ts b/lib/content-services/search/components/search-text/search-text.component.ts index fcee4e5114..c30d3f901b 100644 --- a/lib/content-services/search/components/search-text/search-text.component.ts +++ b/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 = ''; diff --git a/lib/content-services/tag/services/tag.service.ts b/lib/content-services/tag/services/tag.service.ts index 904ce93679..72bd52ba46 100644 --- a/lib/content-services/tag/services/tag.service.ts +++ b/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 { diff --git a/lib/content-services/upload/components/base-upload/upload-base.ts b/lib/content-services/upload/components/base-upload/upload-base.ts index c1abe723a7..378276901d 100644 --- a/lib/content-services/upload/components/base-upload/upload-base.ts +++ b/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(); diff --git a/lib/core/services/cookie.service.ts b/lib/core/services/cookie.service.ts index dff0ebe114..1f6be0f356 100644 --- a/lib/core/services/cookie.service.ts +++ b/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 */ }