From 76ad797488f26054aa6ded33238d88fada52c5d6 Mon Sep 17 00:00:00 2001 From: Andy Stark <30621568+therealandeeee@users.noreply.github.com> Date: Fri, 9 Feb 2018 18:06:24 +0000 Subject: [PATCH] [ADF-1769] Added JSDocs and methods and updated script (#2927) --- docs/content.service.md | 51 +++++++++++--- docs/cookie.service.md | 22 +++--- docs/deleted-nodes-api.service.md | 15 ++-- docs/discovery-api.service.md | 16 ++--- docs/document-actions.service.md | 20 ++++-- docs/document-list.service.md | 70 +++++++++---------- docs/ecm-user.service.md | 15 ++-- lib/config/DocProcessor/tools/tscProps.js | 12 +++- lib/config/DocProcessor/tools/tscProps.ts | 20 +++++- .../services/document-actions.service.ts | 13 ++++ .../services/document-list.service.ts | 24 ++++++- lib/core/services/content.service.ts | 14 ++-- lib/core/services/cookie.service.ts | 15 ++-- .../services/deleted-nodes-api.service.ts | 4 ++ lib/core/services/discovery-api.service.ts | 6 ++ .../userinfo/services/ecm-user.service.ts | 11 ++- 16 files changed, 219 insertions(+), 109 deletions(-) diff --git a/docs/content.service.md b/docs/content.service.md index fbe9eb5928..58c4453c74 100644 --- a/docs/content.service.md +++ b/docs/content.service.md @@ -4,17 +4,46 @@ Accesses app-generated data objects via URLs and file downloads. ## Methods -`downloadBlob(blob: Blob, fileName: string): void`
-Starts downloading the data in `blob` to a named file. - -`downloadData(data: any, fileName: string): void`
-Starts downloading a data object to a named file. - -`downloadJSON(json: any, fileName): void`
-Starts downloading of JSON data to a named file. - -`createTrustedUrl(blob: Blob): string`
-Creates a trusted URL to access the data in `blob`. +- `downloadBlob(blob: Blob, fileName: string)` + Invokes content download for a Blob with a file name. + - `blob` - Content to download. + - `fileName` - Name of the resulting file. +- `downloadData(data: any, fileName: string)` + Invokes content download for a data array with a file name. + - `data` - Data to download. + - `fileName` - Name of the resulting file. +- `downloadJSON(json: any, fileName)` + Invokes content download for a JSON object with a file name. + - `json` - JSON object to download. + - `fileName` - Name of the resulting file. +- `createTrustedUrl(blob: Blob): string` + Creates a trusted object URL from the Blob. WARNING: calling this method with untrusted user data exposes your application to XSS security risks! + - `blob` - Data to wrap into object URL +- `getDocumentThumbnailUrl(node: any, attachment?: boolean, ticket?: string): string` + Get thumbnail URL for the given document node. + - `node` - Node to get URL for. + - `attachment` - (Optional) Retrieve content as an attachment for download + - `ticket` - (Optional) Custom ticket to use for authentication +- `getContentUrl(node: any, attachment?: boolean, ticket?: string): string` + Get content URL for the given node. + - `node` - nodeId or node to get URL for. + - `attachment` - (Optional) Retrieve content as an attachment for download + - `ticket` - (Optional) Custom ticket to use for authentication +- `getNodeContent(nodeId: string): Observable` + Get content for the given node. + - `nodeId` - ID of the target node +- `createFolder(relativePath: string, name: string, parentId?: string): Observable` + Create a folder + - `relativePath` - Location to create the folder + - `name` - Folder name + - `parentId` - (Optional) Node ID of parent folder +- `hasPermission(node: any, permission: PermissionsEnum | string): boolean` + Check if the user has permissions on that node + - `node` - Node to check allowableOperations + - `permission` - Create, delete, update, updatePermissions, !create, !delete, !update, !updatePermissions +- `hasAllowableOperations(node: any): boolean` + Check if the node has the properties allowableOperations + - `node` - Node to check allowableOperations ## Details diff --git a/docs/cookie.service.md b/docs/cookie.service.md index 159e11e340..63b0f12ad9 100644 --- a/docs/cookie.service.md +++ b/docs/cookie.service.md @@ -4,11 +4,18 @@ Stores key-value data items as browser cookies. ## Methods -`getItem(key: string): string | null`
-Gets an item identified by `key`. +- `isEnabled(): boolean` + Checks if cookies are enabled. -` setItem(key: string, data: string, expiration: Date | null, path: string | null): void `
-Stores an item under `key`. +- `getItem(key: string): string` + Retrieves a cookie by its key. + - `key` - Key to identify the cookie +- `setItem(key: string, data: string, expiration: Date | null, path: string | null)` + Set a cookie. + - `key` - Key to identify the cookie + - `data` - Data value to set for the cookie + - `expiration` - Expiration date of the data + - `path` - "Pathname" to store the cookie ## Details @@ -21,10 +28,7 @@ Cookies have a storage size limit that varies between browsers but is often arou 4KB. Consider using [web storage](storage.service.md) if you need to store data beyond this size. - - ## See also -- [Content service](content.service.md) -- [Storage service](storage.service.md) - \ No newline at end of file +- [Content service](content.service.md) +- [Storage service](storage.service.md) diff --git a/docs/deleted-nodes-api.service.md b/docs/deleted-nodes-api.service.md index 8fdad166a5..12d5067faf 100644 --- a/docs/deleted-nodes-api.service.md +++ b/docs/deleted-nodes-api.service.md @@ -4,8 +4,9 @@ Gets a list of Content Services nodes currently in the trash. ## Methods -`getDeletedNodes(options?: Object): Observable`
-Gets a list of nodes in the trash. +- `getDeletedNodes(options?: Object): Observable` + Gets a list of nodes in the trash. + - `options` - (Optional) Options for JSAPI call ## Details @@ -15,13 +16,7 @@ more information about this class). The format of the `options` parameter is described in the [getDeletedNodes](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodesApi.md#getDeletedNodes) page of the Alfresco JS API docs. - - ## See also -- [Nodes api service](nodes-api.service.md) -- [Node service](node.service.md) - - - - +- [Nodes api service](nodes-api.service.md) +- [Node service](node.service.md) diff --git a/docs/discovery-api.service.md b/docs/discovery-api.service.md index 9116334444..d2ed03efbb 100644 --- a/docs/discovery-api.service.md +++ b/docs/discovery-api.service.md @@ -4,11 +4,11 @@ Gets version and license information for Process Services and Content Services. ## Methods -`public getEcmProductInfo(): Observable`
-Gets product information for Content Services. +- `getEcmProductInfo(): any` + Gets product information for Content Services. -`public getBpmProductInfo(): Observable`
-Gets product information for Process Services. +- `getBpmProductInfo(): any` + Gets product information for Process Services. ## Details @@ -18,12 +18,6 @@ See the [Alfresco JS API docs](https://github.com/Alfresco/alfresco-js-api/tree/master/src/alfresco-discovery-rest-api) to learn more about the REST API used by this service. - - ## See also -- [Product version model](product-version.model.md) - - - - +- [Product version model](product-version.model.md) diff --git a/docs/document-actions.service.md b/docs/document-actions.service.md index ffbc0b30dd..83e7a2b011 100644 --- a/docs/document-actions.service.md +++ b/docs/document-actions.service.md @@ -2,6 +2,19 @@ Implements the document menu actions for the Document List component. +## Methods + +- `getHandler(key: string): ContentActionHandler` + Gets the handler for an action. + - `key` - Identifier of the action +- `setHandler(key: string, handler: ContentActionHandler): boolean` + Sets a new handler for an action. + - `key` - Identifier of the action + - `handler` - Handler for the action +- `canExecuteAction(obj: any): boolean` + Checks if actions can be executed for an item. + - `obj` - Item to receive an action + ## Details This service implements the built-in actions that can be applied to a document @@ -72,10 +85,7 @@ export class MyView { You will probably want to set up all your custom actions at the application root level or with a custom application service. - - ## See also -- [Content action component](content-action.component.md) -- [Folder actions service](folder-actions.service.md) - \ No newline at end of file +- [Content action component](content-action.component.md) +- [Folder actions service](folder-actions.service.md) diff --git a/docs/document-list.service.md b/docs/document-list.service.md index 79e8c7ebc7..c9b50aa0ed 100644 --- a/docs/document-list.service.md +++ b/docs/document-list.service.md @@ -4,35 +4,41 @@ Implements node operations used by the Document List component. ## Methods -`deleteNode(nodeId: string): Observable`
-Deletes a node. +- `deleteNode(nodeId: string): Observable` + Deletes a node. + - `nodeId` - ID of the node to delete +- `copyNode(nodeId: string, targetParentId: string): any` + Copy a node to destination node + - `nodeId` - The id of the node to be copied + - `targetParentId` - The id of the folder where the node will be copied +- `moveNode(nodeId: string, targetParentId: string): any` + Move a node to destination node + - `nodeId` - The id of the node to be moved + - `targetParentId` - The id of the folder where the node will be moved +- `createFolder(name: string, parentId: string): Observable` + Create a new folder in the path. + - `name` - Folder name + - `parentId` - Parent folder ID +- `getFolder(folder: string, opts?: any): any` + Gets the folder node with the specified relative name path below the root node. + - `folder` - Path to folder. + - `opts` - (Optional) Options. +- `getFolderNode(nodeId: string): Promise` + Gets a folder node via its node ID. + - `nodeId` - ID of the folder node +- `getDocumentThumbnailUrl(node: MinimalNodeEntity): any` + Get thumbnail URL for the given document node. + - `node` - Node to get URL for. +- `getMimeTypeIcon(mimeType: string): string` + Gets the icon that represents a MIME type. + - `mimeType` - MIME type to get the icon for +- `getDefaultMimeTypeIcon(): string` + Gets a default icon for MIME types with no specific icon. -`copyNode(nodeId: string, targetParentId: string)`
-Places a copy of an existing node under a new parent node. - -`moveNode(nodeId: string, targetParentId: string)`
-hasPermission(node: any, permission: PermissionsEnum|string): boolean. - -`createFolder(name: string, parentId: string): Observable`
-Creates a folder. - -`getFolder(folder: string, opts?: any): Observable`
-Gets a folder node via its pathname from root. - -`getFolderNode(nodeId: string): Promise`
-Gets a folder node via its node ID. - -`getDocumentThumbnailUrl(node: MinimalNodeEntity): string`
-Gets the thumbnail URL for a document node. - -`getMimeTypeIcon(mimeType: string): string`
-Gets the icon that represents a MIME type. - -`getDefaultMimeTypeIcon(): string`
-Gets a default icon for MIME types with no specific icon. - -`hasPermission(node: any, permission: PermissionsEnum|string): boolean`
-Gets a folder node via its pathname from root. +- `hasPermission(node: any, permission: PermissionsEnum|string): boolean` + Checks if a node has the specified permission. + - `node` - Target node + - `permission` - Permission level to query ## Details @@ -73,12 +79,6 @@ The `hasPermission` method reports whether or not the user has the specified per node. The Permissions enum contains the values DELETE, UPDATE, CREATE, UPDATEPERMISSIONS, NOT_DELETE, NOT_UPDATE, NOT_CREATE and NOT_UPDATEPERMISSIONS but you can also supply these values via their string equivalents. - - ## See also -- [Document list component](document-list.component.md) - - - - +- [Document list component](document-list.component.md) diff --git a/docs/ecm-user.service.md b/docs/ecm-user.service.md index 93881e2f62..863102e64c 100644 --- a/docs/ecm-user.service.md +++ b/docs/ecm-user.service.md @@ -4,14 +4,15 @@ Gets information about a Content Services user. ## Methods -`getUserInfo(userName: string): Observable`
-Gets information about a user identified by their username. +- `getUserInfo(userName: string): Observable` + Gets information about a user identified by their username. + - `userName` - Target username +- `getCurrentUserInfo(): Observable` + Gets information about the user who is currently logged-in. -`getCurrentUserInfo(): Observable`
-Gets information about the user who is currently logged-in. - -`getUserProfileImage(avatarId: string)`
-Returns a profile image as a URL. +- `getUserProfileImage(avatarId: string): string` + Returns a profile image as a URL. + - `avatarId` - Target avatar ## Details diff --git a/lib/config/DocProcessor/tools/tscProps.js b/lib/config/DocProcessor/tools/tscProps.js index 3505ab5736..beab7f0702 100644 --- a/lib/config/DocProcessor/tools/tscProps.js +++ b/lib/config/DocProcessor/tools/tscProps.js @@ -27,7 +27,8 @@ var ParamData = /** @class */ (function () { var sig = this.name; if (this.optional) sig += "?"; - sig += ": " + this.type; + if (this.type) + sig += ": " + this.type; if (this.initializer) sig += " = " + this.initializer; return sig; @@ -134,6 +135,8 @@ var ServiceDocAutoContent = /** @class */ (function () { var methData = new MethodData(); methData.name = memSymbol.getName(); var doc = ts.displayPartsToString(memSymbol.getDocumentationComment()); + if (!doc) + console.log("Warning: Method " + classDec.name.escapedText + "." + methData.name + " is not documented"); methData.docText = doc.replace(/\r\n/g, " "); var sig = checker.getSignatureFromDeclaration(method); var returnType = sig.getReturnType(); @@ -143,9 +146,14 @@ var ServiceDocAutoContent = /** @class */ (function () { for (var p = 0; p < params.length; p++) { var pData = new ParamData(); pData.name = params[p].name.getText(); - pData.type = params[p].type.getText(); + if (params[p].type) + pData.type = params[p].type.getText(); + else + pData.type = ""; var paramSymbol = checker.getSymbolAtLocation(params[p].name); pData.docText = ts.displayPartsToString(paramSymbol.getDocumentationComment()); + if (!pData.docText) + console.log("Warning: Parameter \"" + pData.name + "\" of " + classDec.name.escapedText + "." + methData.name + " is not documented"); pData.optional = params[p].questionToken ? true : false; if (params[p].initializer) { var initText = params[p].initializer.getText(); diff --git a/lib/config/DocProcessor/tools/tscProps.ts b/lib/config/DocProcessor/tools/tscProps.ts index d9a1057eac..260407bf31 100644 --- a/lib/config/DocProcessor/tools/tscProps.ts +++ b/lib/config/DocProcessor/tools/tscProps.ts @@ -39,12 +39,13 @@ class ParamData { optional: boolean; getSignature() { - let sig =this.name; + let sig = this.name; if (this.optional) sig += "?"; - sig += ": " + this.type; + if (this.type) + sig += ": " + this.type; if (this.initializer) sig += " = " + this.initializer; @@ -192,6 +193,10 @@ class ServiceDocAutoContent implements NgDocAutoContent { methData.name = memSymbol.getName(); let doc = ts.displayPartsToString(memSymbol.getDocumentationComment()); + + if (!doc) + console.log(`Warning: Method ${classDec.name.escapedText}.${methData.name} is not documented`); + methData.docText = doc.replace(/\r\n/g, " "); let sig = checker.getSignatureFromDeclaration(method); let returnType = sig.getReturnType(); @@ -203,9 +208,18 @@ class ServiceDocAutoContent implements NgDocAutoContent { for (let p = 0; p < params.length; p++){ let pData = new ParamData(); pData.name = params[p].name.getText(); - pData.type = params[p].type.getText(); + + if (params[p].type) + pData.type = params[p].type.getText(); + else + pData.type = ""; + let paramSymbol = checker.getSymbolAtLocation(params[p].name); pData.docText = ts.displayPartsToString(paramSymbol.getDocumentationComment()); + + if (!pData.docText) + console.log(`Warning: Parameter "${pData.name}" of ${classDec.name.escapedText}.${methData.name} is not documented`); + pData.optional = params[p].questionToken ? true : false; if (params[p].initializer) { diff --git a/lib/content-services/document-list/services/document-actions.service.ts b/lib/content-services/document-list/services/document-actions.service.ts index ff6c000bf6..032ad02f9e 100644 --- a/lib/content-services/document-list/services/document-actions.service.ts +++ b/lib/content-services/document-list/services/document-actions.service.ts @@ -41,6 +41,10 @@ export class DocumentActionsService { this.setupActionHandlers(); } + /** + * Gets the handler for an action. + * @param key Identifier of the action + */ getHandler(key: string): ContentActionHandler { if (key) { let lkey = key.toLowerCase(); @@ -49,6 +53,11 @@ export class DocumentActionsService { return null; } + /** + * Sets a new handler for an action. + * @param key Identifier of the action + * @param handler Handler for the action + */ setHandler(key: string, handler: ContentActionHandler): boolean { if (key) { let lkey = key.toLowerCase(); @@ -58,6 +67,10 @@ export class DocumentActionsService { return false; } + /** + * Checks if actions can be executed for an item. + * @param obj Item to receive an action + */ canExecuteAction(obj: any): boolean { return this.documentListService && obj && obj.entry.isFile === true; } 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 7c9758f2e7..479f47b4eb 100644 --- a/lib/content-services/document-list/services/document-list.service.ts +++ b/lib/content-services/document-list/services/document-list.service.ts @@ -62,6 +62,10 @@ export class DocumentListService { return this.apiService.getInstance().nodes.getNodeChildren(rootNodeId, params); } + /** + * Deletes a node. + * @param nodeId ID of the node to delete + */ deleteNode(nodeId: string): Observable { return Observable.fromPromise(this.apiService.getInstance().nodes.deleteNode(nodeId)); } @@ -70,7 +74,7 @@ export class DocumentListService { * Copy a node to destination node * * @param nodeId The id of the node to be copied - * @param targetParentId The id of the folder-node where the node have to be copied to + * @param targetParentId The id of the folder where the node will be copied */ copyNode(nodeId: string, targetParentId: string) { return Observable.fromPromise(this.apiService.getInstance().nodes.copyNode(nodeId, { targetParentId })) @@ -81,7 +85,7 @@ export class DocumentListService { * Move a node to destination node * * @param nodeId The id of the node to be moved - * @param targetParentId The id of the folder-node where the node have to be moved to + * @param targetParentId The id of the folder where the node will be moved */ moveNode(nodeId: string, targetParentId: string) { return Observable.fromPromise(this.apiService.getInstance().nodes.moveNode(nodeId, { targetParentId })) @@ -111,6 +115,10 @@ export class DocumentListService { .catch(err => this.handleError(err)); } + /** + * Gets a folder node via its node ID. + * @param nodeId ID of the folder node + */ getFolderNode(nodeId: string): Promise { let opts: any = { includeSource: true, @@ -130,14 +138,26 @@ export class DocumentListService { return this.thumbnailService.getDocumentThumbnailUrl(node); } + /** + * Gets the icon that represents a MIME type. + * @param mimeType MIME type to get the icon for + */ getMimeTypeIcon(mimeType: string): string { return this.thumbnailService.getMimeTypeIcon(mimeType); } + /** + * Gets a default icon for MIME types with no specific icon. + */ getDefaultMimeTypeIcon(): string { return this.thumbnailService.getDefaultMimeTypeIcon(); } + /** + * Checks if a node has the specified permission. + * @param node Target node + * @param permission Permission level to query + */ hasPermission(node: any, permission: PermissionsEnum|string): boolean { return this.contentService.hasPermission(node, permission); } diff --git a/lib/core/services/content.service.ts b/lib/core/services/content.service.ts index 50c7a606de..fada7fdfbc 100644 --- a/lib/core/services/content.service.ts +++ b/lib/core/services/content.service.ts @@ -133,7 +133,7 @@ export class ContentService { /** * Get thumbnail URL for the given document node. * - * @param {string|MinimalNodeEntity} nodeId or node to get URL for. + * @param {string|MinimalNodeEntity} node Node to get URL for. * @param {boolean} [attachment] Retrieve content as an attachment for download * @param {string} [ticket] Custom ticket to use for authentication * @returns {string} The URL address pointing to the content. @@ -166,7 +166,7 @@ export class ContentService { /** * Get content for the given node. - * @param nodeId {string}. + * @param nodeId ID of the target node * * @returns {Observable} URL address. */ @@ -178,7 +178,9 @@ export class ContentService { /** * Create a folder - * @param name - the folder name + * @param relativePath Location to create the folder + * @param name Folder name + * @param parentId Node ID of parent folder */ createFolder(relativePath: string, name: string, parentId?: string): Observable { return Observable.fromPromise(this.apiService.getInstance().nodes.createFolder(name, relativePath, parentId)) @@ -195,8 +197,8 @@ export class ContentService { /** * Check if the user has permissions on that node - * @param MinimalNode - node to check allowableOperations - * @param PermissionsEnum - create, delete, update, updatePermissions, !create, !delete, !update, !updatePermissions + * @param node Node to check allowableOperations + * @param permission Create, delete, update, updatePermissions, !create, !delete, !update, !updatePermissions * * @returns {boolean} has permission */ @@ -221,7 +223,7 @@ export class ContentService { /** * Check if the node has the properties allowableOperations - * @param MinimalNode - node to check allowableOperations + * @param node Node to check allowableOperations * * @returns {boolean} has AllowableOperations */ diff --git a/lib/core/services/cookie.service.ts b/lib/core/services/cookie.service.ts index 1eb749b1e6..6e031aa576 100644 --- a/lib/core/services/cookie.service.ts +++ b/lib/core/services/cookie.service.ts @@ -20,6 +20,9 @@ import { Injectable } from '@angular/core'; @Injectable() export class CookieService { + /** + * Checks if cookies are enabled. + */ isEnabled(): boolean { // for certain scenarios Chrome may say 'true' but have cookies still disabled if (navigator.cookieEnabled === false) { @@ -31,8 +34,8 @@ export class CookieService { } /** - * Retrieve cookie by key. - * + * Retrieves a cookie by its key. + * @param key Key to identify the cookie * @returns {string | null} */ getItem(key: string): string | null { @@ -43,10 +46,10 @@ export class CookieService { /** * Set a cookie. - * @param key - * @param data - * @param expiration - * @param path + * @param key Key to identify the cookie + * @param data Data value to set for the cookie + * @param expiration Expiration date of the data + * @param path "Pathname" to store the cookie * * @returns {boolean} */ diff --git a/lib/core/services/deleted-nodes-api.service.ts b/lib/core/services/deleted-nodes-api.service.ts index 958de36c51..46290fb18d 100644 --- a/lib/core/services/deleted-nodes-api.service.ts +++ b/lib/core/services/deleted-nodes-api.service.ts @@ -33,6 +33,10 @@ export class DeletedNodesApiService { return this.apiService.getInstance().core.nodesApi; } + /** + * Gets a list of nodes in the trash. + * @param options Options for JSAPI call + */ getDeletedNodes(options?: Object): Observable { const { nodesApi, handleError } = this; const defaultOptions = { diff --git a/lib/core/services/discovery-api.service.ts b/lib/core/services/discovery-api.service.ts index d03bfa8baf..0362f12ea0 100644 --- a/lib/core/services/discovery-api.service.ts +++ b/lib/core/services/discovery-api.service.ts @@ -28,6 +28,9 @@ export class DiscoveryApiService { constructor(private apiService: AlfrescoApiService) { } + /** + * Gets product information for Content Services. + */ public getEcmProductInfo() { return Observable.fromPromise( this.apiService.getInstance().discovery.discoveryApi.getRepositoryInformation()) @@ -35,6 +38,9 @@ export class DiscoveryApiService { .catch(this.handleError); } + /** + * Gets product information for Process Services. + */ public getBpmProductInfo() { return Observable.fromPromise( this.apiService.getInstance().activiti.aboutApi.getAppVersion()) diff --git a/lib/core/userinfo/services/ecm-user.service.ts b/lib/core/userinfo/services/ecm-user.service.ts index 531d4852ae..170226d399 100644 --- a/lib/core/userinfo/services/ecm-user.service.ts +++ b/lib/core/userinfo/services/ecm-user.service.ts @@ -33,8 +33,8 @@ export class EcmUserService { } /** - * get User Information via ECM - * @param userName - the user name + * Gets information about a user identified by their username. + * @param userName Target username */ getUserInfo(userName: string): Observable { return Observable.fromPromise(this.apiService.getInstance().core.peopleApi.getPerson(userName)) @@ -42,10 +42,17 @@ export class EcmUserService { .catch(err => this.handleError(err)); } + /** + * Gets information about the user who is currently logged-in. + */ getCurrentUserInfo() { return this.getUserInfo('-me-'); } + /** + * Returns a profile image as a URL. + * @param avatarId Target avatar + */ getUserProfileImage(avatarId: string) { if (avatarId) { let nodeObj = {entry: {id: avatarId}};