Removed warnings from msal-node.api.md (#7376)

JSDocs improvements to eliminate most warnings in msal-node.api.md

change/@azure-msal-node-4d1288f5-51f1-41c5-90c9-fbbe85ed7454.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Removed warnings from msal-node-api.md #7376",
+  "packageName": "@azure/msal-node",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

lib/msal-node/src/cache/NodeStorage.ts

@@ -227,7 +227,7 @@ export class NodeStorage extends CacheManager {
 
     /**
      * Reads account from cache, builds it into an account entity and returns it.
-     * @param accountKey
+     * @param accountKey - lookup key to fetch cache type AccountEntity
      * @returns
      */
     getCachedAccountEntity(accountKey: string): AccountEntity | null {
@@ -462,7 +462,7 @@ export class NodeStorage extends CacheManager {
 
     /**
      * Remove account entity from the platform cache if it's outdated
-     * @param accountKey
+     * @param accountKey - lookup key to fetch cache type AccountEntity
      */
     removeOutdatedAccount(accountKey: string): void {
         this.removeItem(accountKey);

lib/msal-node/src/cache/distributed/DistributedCachePlugin.ts

@@ -12,6 +12,10 @@ import { TokenCache } from "../TokenCache.js";
 import { IPartitionManager } from "./IPartitionManager.js";
 import { ICacheClient } from "./ICacheClient.js";
 
+/**
+ * Cache plugin that serializes data to the cache and deserializes data from the cache
+ * @public
+ */
 export class DistributedCachePlugin implements ICachePlugin {
     private client: ICacheClient;
     private partitionManager: IPartitionManager;
@@ -21,6 +25,10 @@ export class DistributedCachePlugin implements ICachePlugin {
         this.partitionManager = partitionManager;
     }
 
+    /**
+     * Deserializes the cache before accessing it
+     * @param cacheContext - TokenCacheContext
+     */
     public async beforeCacheAccess(
         cacheContext: TokenCacheContext
     ): Promise<void> {
@@ -29,6 +37,10 @@ export class DistributedCachePlugin implements ICachePlugin {
         cacheContext.tokenCache.deserialize(cacheData);
     }
 
+    /**
+     * Serializes the cache after accessing it
+     * @param cacheContext - TokenCacheContext
+     */
     public async afterCacheAccess(
         cacheContext: TokenCacheContext
     ): Promise<void> {

lib/msal-node/src/cache/distributed/ICacheClient.ts

@@ -3,20 +3,24 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * Interface for the cache that defines a getter and setter
+ * @public
+ */
 export interface ICacheClient {
     /**
      * Retrieve the value from the cache
      *
-     * @param key string
+     * @param key - key of item in the cache
      * @returns Promise<string>
      */
     get(key: string): Promise<string>;
 
     /**
      * Save the required value using the provided key to cache
      *
-     * @param key string
-     * @param value string
+     * @param key - key of item in the cache
+     * @param value - value of item to be saved in the cache
      * @returns Promise<string>
      */
     set(key: string, value: string): Promise<string>;

lib/msal-node/src/cache/distributed/IPartitionManager.ts

@@ -5,6 +5,10 @@
 
 import { AccountEntity } from "@azure/msal-common/node";
 
+/**
+ * Interface that defines getter methods to get keys used to identity data in the cache
+ * @public
+ */
 export interface IPartitionManager {
     /**
      * This function should return the correct key from which to read
@@ -28,7 +32,7 @@ export interface IPartitionManager {
      * this function would return the homeAccountId from
      * the provided AccountEntity
      *
-     * @param accountEntity: AccountEntity
+     * @param accountEntity - AccountEntity
      * @returns Promise<string>
      */
     extractKey(accountEntity: AccountEntity): Promise<string>;

lib/msal-node/src/cache/serializer/Deserializer.ts

@@ -28,12 +28,13 @@ import {
 } from "./SerializerTypes.js";
 
 /**
- * This class deserializes cache entities read from the file into in memory object types defined internally
+ * This class deserializes cache entities read from the file into in-memory object types defined internally
+ * @internal
  */
 export class Deserializer {
     /**
      * Parse the JSON blob in memory and deserialize the content
-     * @param cachedJson
+     * @param cachedJson - JSON blob cache
      */
     static deserializeJSONBlob(jsonFile: string): JsonCache {
         const deserializedCache = !jsonFile ? {} : JSON.parse(jsonFile);
@@ -42,7 +43,7 @@ export class Deserializer {
 
     /**
      * Deserializes accounts to AccountEntity objects
-     * @param accounts
+     * @param accounts - accounts of type SerializedAccountEntity
      */
     static deserializeAccounts(
         accounts: Record<string, SerializedAccountEntity>
@@ -79,7 +80,7 @@ export class Deserializer {
 
     /**
      * Deserializes id tokens to IdTokenEntity objects
-     * @param idTokens
+     * @param idTokens - credentials of type SerializedIdTokenEntity
      */
     static deserializeIdTokens(
         idTokens: Record<string, SerializedIdTokenEntity>
@@ -105,7 +106,7 @@ export class Deserializer {
 
     /**
      * Deserializes access tokens to AccessTokenEntity objects
-     * @param accessTokens
+     * @param accessTokens - access tokens of type SerializedAccessTokenEntity
      */
     static deserializeAccessTokens(
         accessTokens: Record<string, SerializedAccessTokenEntity>
@@ -142,7 +143,7 @@ export class Deserializer {
 
     /**
      * Deserializes refresh tokens to RefreshTokenEntity objects
-     * @param refreshTokens
+     * @param refreshTokens - refresh tokens of type SerializedRefreshTokenEntity
      */
     static deserializeRefreshTokens(
         refreshTokens: Record<string, SerializedRefreshTokenEntity>
@@ -171,7 +172,7 @@ export class Deserializer {
 
     /**
      * Deserializes appMetadata to AppMetaData objects
-     * @param appMetadata
+     * @param appMetadata - app metadata of type SerializedAppMetadataEntity
      */
     static deserializeAppMetadata(
         appMetadata: Record<string, SerializedAppMetadataEntity>
@@ -193,7 +194,7 @@ export class Deserializer {
 
     /**
      * Deserialize an inMemory Cache
-     * @param jsonCache
+     * @param jsonCache - JSON blob cache
      */
     static deserializeAllCache(jsonCache: JsonCache): InMemoryCache {
         return {

lib/msal-node/src/cache/serializer/Serializer.ts

@@ -20,18 +20,22 @@ import {
     SerializedAppMetadataEntity,
 } from "./SerializerTypes.js";
 
+/**
+ * This class serializes cache entities to be saved into in-memory object types defined internally
+ * @internal
+ */
 export class Serializer {
     /**
      * serialize the JSON blob
-     * @param data
+     * @param data - JSON blob cache
      */
     static serializeJSONBlob(data: JsonCache): string {
         return JSON.stringify(data);
     }
 
     /**
      * Serialize Accounts
-     * @param accCache
+     * @param accCache - cache of accounts
      */
     static serializeAccounts(
         accCache: AccountCache
@@ -63,7 +67,7 @@ export class Serializer {
 
     /**
      * Serialize IdTokens
-     * @param idTCache
+     * @param idTCache - cache of ID tokens
      */
     static serializeIdTokens(
         idTCache: IdTokenCache
@@ -86,7 +90,7 @@ export class Serializer {
 
     /**
      * Serializes AccessTokens
-     * @param atCache
+     * @param atCache - cache of access tokens
      */
     static serializeAccessTokens(
         atCache: AccessTokenCache
@@ -119,7 +123,7 @@ export class Serializer {
 
     /**
      * Serialize refreshTokens
-     * @param rtCache
+     * @param rtCache - cache of refresh tokens
      */
     static serializeRefreshTokens(
         rtCache: RefreshTokenCache
@@ -144,7 +148,7 @@ export class Serializer {
 
     /**
      * Serialize amdtCache
-     * @param amdtCache
+     * @param amdtCache - cache of app metadata
      */
     static serializeAppMetadata(
         amdtCache: AppMetadataCache
@@ -164,7 +168,7 @@ export class Serializer {
 
     /**
      * Serialize the cache
-     * @param jsonContent
+     * @param inMemCache - itemised cache read from the JSON
      */
     static serializeAllCache(inMemCache: InMemoryCache): JsonCache {
         return {

lib/msal-node/src/client/ClientApplication.ts

@@ -372,8 +372,8 @@ export abstract class ClientApplication {
      * This API is provided for scenarios where you would use OAuth2.0 state parameter to mitigate against
      * CSRF attacks.
      * For more information about state, visit https://datatracker.ietf.org/doc/html/rfc6819#section-3.6.
-     * @param state
-     * @param cachedState
+     * @param state - Unique GUID generated by the user that is cached by the user and sent to the server during the first leg of the flow
+     * @param cachedState - This string is sent back by the server with the authorization code
      */
     protected validateState(state: string, cachedState: string): void {
         if (!state) {

lib/msal-node/src/client/ClientCredentialClient.ts

@@ -42,6 +42,7 @@ import {
 
 /**
  * OAuth2.0 client credential grant
+ * @public
  */
 export class ClientCredentialClient extends BaseClient {
     private readonly appTokenProvider?: IAppTokenProvider;
@@ -56,7 +57,7 @@ export class ClientCredentialClient extends BaseClient {
 
     /**
      * Public API to acquire a token with ClientCredential Flow for Confidential clients
-     * @param request
+     * @param request - CommonClientCredentialRequest provided by the developer
      */
     public async acquireToken(
         request: CommonClientCredentialRequest
@@ -232,8 +233,8 @@ export class ClientCredentialClient extends BaseClient {
 
     /**
      * Makes a network call to request the token from the service
-     * @param request
-     * @param authority
+     * @param request - CommonClientCredentialRequest provided by the developer
+     * @param authority - authority object
      */
     private async executeTokenRequest(
         request: CommonClientCredentialRequest,
@@ -330,7 +331,7 @@ export class ClientCredentialClient extends BaseClient {
 
     /**
      * generate the request to the server in the acceptable format
-     * @param request
+     * @param request - CommonClientCredentialRequest provided by the developer
      */
     private async createTokenRequestBody(
         request: CommonClientCredentialRequest

lib/msal-node/src/client/DeviceCodeClient.ts

@@ -27,6 +27,7 @@ import {
 
 /**
  * OAuth2.0 Device code client
+ * @public
  */
 export class DeviceCodeClient extends BaseClient {
     constructor(configuration: ClientConfiguration) {
@@ -36,7 +37,7 @@ export class DeviceCodeClient extends BaseClient {
     /**
      * Gets device code from device code endpoint, calls back to with device code response, and
      * polls token endpoint to exchange device code for tokens
-     * @param request
+     * @param request - developer provided CommonDeviceCodeRequest
      */
     public async acquireToken(
         request: CommonDeviceCodeRequest
@@ -70,7 +71,7 @@ export class DeviceCodeClient extends BaseClient {
 
     /**
      * Creates device code request and executes http GET
-     * @param request
+     * @param request - developer provided CommonDeviceCodeRequest
      */
     private async getDeviceCode(
         request: CommonDeviceCodeRequest
@@ -104,9 +105,11 @@ export class DeviceCodeClient extends BaseClient {
 
     /**
      * Creates query string for the device code request
-     * @param request
+     * @param request - developer provided CommonDeviceCodeRequest
      */
-    createExtraQueryParameters(request: CommonDeviceCodeRequest): string {
+    public createExtraQueryParameters(
+        request: CommonDeviceCodeRequest
+    ): string {
         const parameterBuilder = new RequestParameterBuilder();
 
         if (request.extraQueryParameters) {
@@ -120,9 +123,10 @@ export class DeviceCodeClient extends BaseClient {
 
     /**
      * Executes POST request to device code endpoint
-     * @param deviceCodeEndpoint
-     * @param queryString
-     * @param headers
+     * @param deviceCodeEndpoint - token endpoint
+     * @param queryString - string to be used in the body of the request
+     * @param headers - headers for the request
+     * @param thumbprint - unique request thumbprint
      */
     private async executePostRequestToDeviceCodeEndpoint(
         deviceCodeEndpoint: string,
@@ -160,6 +164,7 @@ export class DeviceCodeClient extends BaseClient {
 
     /**
      * Create device code endpoint query parameters and returns string
+     * @param request - developer provided CommonDeviceCodeRequest
      */
     private createQueryString(request: CommonDeviceCodeRequest): string {
         const parameterBuilder: RequestParameterBuilder =
@@ -189,9 +194,10 @@ export class DeviceCodeClient extends BaseClient {
     }
 
     /**
-     * Breaks the polling with specific conditions.
-     * @param request CommonDeviceCodeRequest
-     * @param deviceCodeResponse DeviceCodeResponse
+     * Breaks the polling with specific conditions
+     * @param deviceCodeExpirationTime - expiration time for the device code request
+     * @param userSpecifiedTimeout - developer provided timeout, to be compared against deviceCodeExpirationTime
+     * @param userSpecifiedCancelFlag - boolean indicating the developer would like to cancel the request
      */
     private continuePolling(
         deviceCodeExpirationTime: number,
@@ -231,10 +237,9 @@ export class DeviceCodeClient extends BaseClient {
     }
 
     /**
-     * Creates token request with device code response and polls token endpoint at interval set by the device code
-     * response
-     * @param request
-     * @param deviceCodeResponse
+     * Creates token request with device code response and polls token endpoint at interval set by the device code response
+     * @param request - developer provided CommonDeviceCodeRequest
+     * @param deviceCodeResponse - DeviceCodeResponse returned by the security token service device code endpoint
      */
     private async acquireTokenWithDeviceCode(
         request: CommonDeviceCodeRequest,
@@ -326,8 +331,8 @@ export class DeviceCodeClient extends BaseClient {
 
     /**
      * Creates query parameters and converts to string.
-     * @param request
-     * @param deviceCodeResponse
+     * @param request - developer provided CommonDeviceCodeRequest
+     * @param deviceCodeResponse - DeviceCodeResponse returned by the security token service device code endpoint
      */
     private createTokenRequestBody(
         request: CommonDeviceCodeRequest,