[ADF-1769] Added JSDocs for services (#2961)

docs/tag.service.md

@@ -4,17 +4,20 @@ Manages tags in Content Services.
 
 ## Methods
 
-`getTagsByNodeId(nodeId: string): any`<br/>
+-   `getTagsByNodeId(nodeId: string): any`  
     Gets a list of tags added to a node.  
-
+    -   `nodeId` - ID of the target node
-`getAllTheTags()`<br/>
+-   `getAllTheTags(): any`  
     Gets a list of all the tags already defined in the repository.   
 
-`addTag(nodeId: string, tagName: string): any`<br/>
+-   `addTag(nodeId: string, tagName: string): any`  
     Adds a tag to a node.  
-
+    -   `nodeId` - ID of the target node
-`removeTag(nodeId: string, tag: string): any`<br/>
+    -   `tagName` - Name of the tag to add
+-   `removeTag(nodeId: string, tag: string): any`  
     Removes a tag from a node.  
+    -   `nodeId` - ID of the target node
+    -   `tag` - Name of the tag to remove
 
 ## Details
 

docs/thumbnail.service.md

@@ -4,15 +4,16 @@ Retrieves an SVG thumbnail image to represent a document type.
 
 ## Methods
 
-`public getDocumentThumbnailUrl(document: any): string`<br/>
+-   `getDocumentThumbnailUrl(node: any): string`  
-Gets a thumbnail URL for a document node.
+    Gets a thumbnail URL for the given document node.  
-
+    -   `node` - Node to get URL for.
-`public getMimeTypeIcon(mimeType: string): string`<br/>
+-   `getMimeTypeIcon(mimeType: string): string`  
     Gets a thumbnail URL for a MIME type.  
-
+    -   `mimeType` - MIME type for the thumbnail
-`public getDefaultMimeTypeIcon(): string`<br/>
+-   `getDefaultMimeTypeIcon(): string`  
     Gets a "miscellaneous" thumbnail URL for types with no other icon defined.  
 
+
 ## Details
 
 The service can locate a thumbnail icon (in SVG format) for either

docs/translation.service.md

@@ -4,17 +4,21 @@ Supports localisation.
 
 ## Methods
 
-`addTranslationFolder(name: string = '', path: string = '')`<br/>
+-   `addTranslationFolder(name: string = '', path: string = '')`  
     Adds a new folder of translation source files.  
-
+    -   `name` - Name for the translation provider
-`use(lang: string): Observable<any>`<br/>
+    -   `path` - Path to the folder
+-   `use(lang: string): Observable<any>`  
     Sets the target language for translations.  
-
+    -   `lang` - Code name for the language
-`get(key: string|Array<string>, interpolateParams?: Object): Observable<string|any>`<br/>
+-   `get(key: string|Array<string>, interpolateParams?: Object): Observable<any>`  
     Gets the translation for the supplied key.  
-
+    -   `key` - Key to translate
-`instant(key: string | Array<string>, interpolateParams?: Object): string | any`<br/>
+    -   `interpolateParams` - (Optional) String(s) to be interpolated into the main message
+-   `instant(key: string | Array<string>, interpolateParams?: Object): any`  
     Directly returns the translation for the supplied key.  
+    -   `key` - Key to translate
+    -   `interpolateParams` - (Optional) String(s) to be interpolated into the main message
 
 ## Details
 

docs/upload.service.md

@@ -2,13 +2,35 @@
 
 Provides access to various APIs related to file upload features.
 
-## Basic Usage
+## Methods
 
-### Events
+-   `isUploading(): boolean`  
+    Checks whether the service is uploading a file.  
+
+-   `getQueue(): FileModel[]`  
+    Returns the file Queue  
+
+-   `addToQueue(files: FileModel[]): FileModel[]`  
+    Adds files to the uploading queue to be uploaded  
+    -   `files` - One or more separate parameters or an array of files to queue
+-   `uploadFilesInTheQueue(emitter: EventEmitter<any>)`  
+    Finds all the files in the queue that are not yet uploaded and uploads them into the directory folder.  
+    -   `emitter` - (Deprecated) Emitter to invoke on file status change
+-   `cancelUpload(files: FileModel[])`  
+    Cancels uploading of files.  
+    -   `files` - One or more separate parameters or an array of files
+-   `clearQueue()`  
+    Clears the upload queue   
+
+-   `getUploadPromise(file: FileModel): any`  
+    Gets an upload promise for a file.  
+    -   `file` - The target file
+
+## Events
 
 | Name | Type | Description |
-| --- | --- | --- |
+| ---- | ---- | ----------- |
-| queueChanged | FileModel[] | Raised every time the file queue changes. |
+| queueChanged | FileModel\[] | Raised every time the file queue changes. |
 | fileUpload | FileUploadEvent | Raised every time a File model changes its state. |
 | fileUploadStarting | FileUploadEvent | Raised when upload starts. |
 | fileUploadCancelled | FileUploadEvent | Raised when upload gets cancelled by user. |
@@ -24,8 +46,8 @@ Provides access to various APIs related to file upload features.
 ### Ignore list configuration
 
 Is possible add an ignore list for files that you don't want to allow upload on your CS.
-The configuration of this service is saved in the ***app.config.json file***.If you want more details about the configuration service follow this [link](https://github.com/Alfresco/alfresco-ng2-components/tree/master/ng2-components/ng2-alfresco-core#appconfigservice).
+The configuration of this service is saved in the **_app.config.json file_**.If you want more details about the configuration service follow this [link](https://github.com/Alfresco/alfresco-ng2-components/tree/master/ng2-components/ng2-alfresco-core#appconfigservice).
-In the example below you can see how filtered out the : '.git', '.DS_Store' and 'desktop.ini'. **Every element is a glob pattern string.** So, if you want to exclude all the txt files, you can add the "*.txt". (notice the asterisk at the beginning of the pattern!)
+In the example below you can see how filtered out the : '.git', '.DS_Store' and 'desktop.ini'. **Every element is a glob pattern string.** So, if you want to exclude all the txt files, you can add the "\*.txt". (notice the asterisk at the beginning of the pattern!)
 
 **app.config.json**
 
@@ -43,5 +65,6 @@ In the example below you can see how filtered out the : '.git', '.DS_Store' and
 ```
 
 Note:
+
 -   Standard glob patterns work.
 -   You can end patterns with a forward slash / to specify a directory.

docs/user-preferences.service.md

@@ -2,6 +2,32 @@
 
 Stores preferences for components.
 
+## Methods
+
+-   `get(property: string, defaultValue?: string): string`  
+    Gets a preference property.  
+    -   `property` - Name of the property
+    -   `defaultValue` - (Optional) Default to return if the property is not found
+-   `set(property: string, value: any)`  
+    Sets a preference property.  
+    -   `property` - Name of the property
+    -   `value` - New value for the property
+-   `getStoragePrefix(): string`  
+    Gets the active storage prefix for preferences.   
+
+-   `setStoragePrefix(value: string)`  
+    Sets the active storage prefix for preferences.  
+    -   `value` - Name of the prefix
+-   `getPropertyKey(property: string): string`  
+    Gets the full property key with prefix.  
+    -   `property` - The property name
+-   `getDifferentPageSizes(): number[]`  
+    Gets an array containing the available page sizes.   
+
+-   `getDefaultLocale(): string`  
+    Gets the default locale.   
+
+
 ## Details
 
 The preferences are bound to a particular `prefix` so the application can switch between different profiles on demand.
@@ -44,8 +70,11 @@ class AppComponent {
 }
 ```
 
-The service also provides quick access to a set of the "known" properties used across ADF components.
+The service also provides quick access to a set of the "known" properties used across ADF components:
 
-Known properties:
+| Name | Type | Description |
-
+| ---- | ---- | ----------- |
-- paginationSize (number) - gets or sets the preferred pagination size
+| authType | `string` | Authorization type (can be "ECM", "BPM" or "ALL"). |
+| disableCSRF | `boolean` | Prevents the CSRF Token from being submitted if true. Only valid for Process Services. |
+| paginationSize | `number` | Pagination size. |
+| locale | `string` | Current locale setting. |

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

@@ -30,16 +30,26 @@ export class TagService {
                 private logService: LogService) {
     }
 
+    /**
+     * Gets a list of tags added to a node.
+     * @param nodeId ID of the target node
+     */
     getTagsByNodeId(nodeId: string): any {
         return Observable.fromPromise(this.apiService.getInstance().core.tagsApi.getNodeTags(nodeId))
             .catch(err => this.handleError(err));
     }
 
+    /** Gets a list of all the tags already defined in the repository. */
     getAllTheTags() {
         return Observable.fromPromise(this.apiService.getInstance().core.tagsApi.getTags())
             .catch(err => this.handleError(err));
     }
 
+    /**
+     * Adds a tag to a node.
+     * @param nodeId ID of the target node
+     * @param tagName Name of the tag to add
+     */
     addTag(nodeId: string, tagName: string): any {
         let alfrescoApi: any = this.apiService.getInstance();
         let tagBody = new alfrescoApi.core.TagBody();
@@ -56,6 +66,11 @@ export class TagService {
         return promiseAdd;
     }
 
+    /**
+     * Removes a tag from a node.
+     * @param nodeId ID of the target node
+     * @param tag Name of the tag to remove
+     */
     removeTag(nodeId: string, tag: string): any {
         let promiseRemove = Observable.fromPromise(this.apiService.getInstance().core.tagsApi.removeTag(nodeId, tag));
 

lib/core/services/thumbnail.service.ts

@@ -156,8 +156,8 @@ export class ThumbnailService {
     }
 
     /**
-     * Get thumbnail URL for the given document node.
+     * Gets a thumbnail URL for the given document node.
-     * @param document Node to get URL for.
+     * @param node Node to get URL for.
      */
     public getDocumentThumbnailUrl(node: any): string {
         let thumbnail = this.contentService.getDocumentThumbnailUrl(node);
@@ -165,8 +165,8 @@ export class ThumbnailService {
     }
 
     /**
-     * Get mimeType SVG
+     * Gets a thumbnail URL for a MIME type.
-     * @param mimeType
+     * @param mimeType MIME type for the thumbnail
      */
     public getMimeTypeIcon(mimeType: string): string {
         let icon = this.mimeTypeIcons[mimeType];
@@ -174,7 +174,7 @@ export class ThumbnailService {
     }
 
     /**
-     * Get default SVG
+     * Gets a "miscellaneous" thumbnail URL for types with no other icon defined.
      */
     public getDefaultMimeTypeIcon(): string {
         return this.DEFAULT_ICON;

lib/core/services/translation.service.ts

@@ -62,6 +62,11 @@ export class TranslationService {
         });
     }
 
+    /**
+     * Adds a new folder of translation source files.
+     * @param name Name for the translation provider
+     * @param path Path to the folder
+     */
     addTranslationFolder(name: string = '', path: string = '') {
         if (!this.customLoader.providerRegistered(name)) {
             this.customLoader.registerProvider(name, path);
@@ -83,15 +88,29 @@ export class TranslationService {
         }
     }
 
+    /**
+     * Sets the target language for translations.
+     * @param lang Code name for the language
+     */
     use(lang: string): Observable<any> {
         this.customLoader.init(lang);
         return this.translate.use(lang);
     }
 
+    /**
+     * Gets the translation for the supplied key.
+     * @param key Key to translate
+     * @param interpolateParams String(s) to be interpolated into the main message
+     */
     get(key: string|Array<string>, interpolateParams?: Object): Observable<string|any> {
         return this.translate.get(key, interpolateParams);
     }
 
+    /**
+     * Directly returns the translation for the supplied key.
+     * @param key Key to translate
+     * @param interpolateParams String(s) to be interpolated into the main message
+     */
     instant(key: string | Array<string>, interpolateParams?: Object): string | any {
         return this.translate.instant(key, interpolateParams);
     }

lib/core/services/upload.service.ts

@@ -72,12 +72,8 @@ export class UploadService {
     }
 
     /**
-     * Add files to the uploading queue to be uploaded.
+     * Adds files to the uploading queue to be uploaded
-     *
+     * @param files One or more separate parameters or an array of files to queue
-     * Examples:
-     *  addToQueue(file); // pass one file
-     *  addToQueue(file1, file2, file3); // pass multiple files
-     *  addToQueue(...[file1, file2, file3]); // pass an array of files
      */
     addToQueue(...files: FileModel[]): FileModel[] {
         const allowedFiles = files.filter(f => this.filterElement(f));
@@ -96,9 +92,9 @@ export class UploadService {
     }
 
     /**
-     * Pick all the files in the queue that are not been uploaded yet and upload it into the directory folder.
+     * Finds all the files in the queue that are not yet uploaded and uploads them into the directory folder.
      *
-     * @param emitter @deprecated emitter to invoke on file status change
+     * @param emitter (Deprecated) Emitter to invoke on file status change
      *
      * @memberof UploadService
      */
@@ -127,6 +123,10 @@ export class UploadService {
         }
     }
 
+    /**
+     * Cancels uploading of files.
+     * @param files One or more separate parameters or an array of files
+     */
     cancelUpload(...files: FileModel[]) {
         files.forEach(file => {
             const promise = this.cache[file.id];
@@ -141,6 +141,7 @@ export class UploadService {
         });
     }
 
+    /** Clears the upload queue */
     clearQueue() {
         this.queue = [];
         this.totalComplete = 0;
@@ -148,6 +149,10 @@ export class UploadService {
         this.totalError = 0;
     }
 
+    /**
+     * Gets an upload promise for a file.
+     * @param file The target file
+     */
     getUploadPromise(file: FileModel) {
         let opts: any = {
             renditions: 'doclib'

lib/core/services/user-preferences.service.ts

@@ -48,6 +48,11 @@ export class UserPreferencesService {
         this.defaults.supportedPageSizes = this.appConfig.get('pagination.supportedPageSizes', this.defaults.supportedPageSizes);
     }
 
+    /**
+     * Gets a preference property.
+     * @param property Name of the property
+     * @param defaultValue Default to return if the property is not found
+     */
     get(property: string, defaultValue?: string): string {
         const key = this.getPropertyKey(property);
         const value = this.storage.getItem(key);
@@ -57,6 +62,11 @@ export class UserPreferencesService {
         return value;
     }
 
+    /**
+     * Sets a preference property.
+     * @param property Name of the property
+     * @param value New value for the property
+     */
     set(property: string, value: any) {
         if (!property) { return; }
 
@@ -66,22 +76,33 @@ export class UserPreferencesService {
         );
     }
 
+    /** Gets the active storage prefix for preferences. */
     getStoragePrefix(): string {
         return this.storage.getItem('USER_PROFILE') || 'GUEST';
     }
 
+    /**
+     * Sets the active storage prefix for preferences.
+     * @param value Name of the prefix
+     */
     setStoragePrefix(value: string) {
         this.storage.setItem('USER_PROFILE', value || 'GUEST');
     }
 
+    /**
+     * Gets the full property key with prefix.
+     * @param property The property name
+     */
     getPropertyKey(property: string): string {
         return `${this.getStoragePrefix()}__${property}`;
     }
 
+    /** Gets an array containing the available page sizes. */
     getDifferentPageSizes(): number[] {
         return this.defaults.supportedPageSizes;
     }
 
+    /** Authorization type (can be "ECM", "BPM" or "ALL"). */
     set authType(value: string) {
         this.storage.setItem('AUTH_TYPE', value);
         this.apiService.reset();
@@ -91,6 +112,7 @@ export class UserPreferencesService {
         return this.storage.getItem('AUTH_TYPE') || 'ALL';
     }
 
+    /** Prevents the CSRF Token from being submitted if true. Only valid for Process Services. */
     set disableCSRF(value: boolean) {
         this.set('DISABLE_CSRF', value);
         this.apiService.reset();
@@ -100,6 +122,7 @@ export class UserPreferencesService {
         return this.get('DISABLE_CSRF') === 'true';
     }
 
+    /** Pagination size. */
     set paginationSize(value: number) {
         this.set('PAGINATION_SIZE', value);
     }
@@ -108,6 +131,7 @@ export class UserPreferencesService {
         return Number(this.get('PAGINATION_SIZE')) || this.defaults.paginationSize;
     }
 
+    /** Current locale setting. */
     get locale(): string {
         const locale = this.get('LOCALE');
         return locale;
@@ -118,6 +142,7 @@ export class UserPreferencesService {
         this.set('LOCALE', value);
     }
 
+    /** Gets the default locale. */
     public getDefaultLocale(): string {
         return this.appConfig.get<string>('locale') || this.translate.getBrowserLang() || 'en';
     }