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

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[] = [];