Update incorrect JSDoc annotations (#12101)

* Update incorrect JSDoc annotations

* Create 12101.md

* Update src/client/common/utils/cacheUtils.ts

Co-authored-by: Kim-Adeline Miguel <[email protected]>

* Update src/client/datascience/jupyter/kernels/kernelSelector.ts

Co-authored-by: Kim-Adeline Miguel <[email protected]>

* Update src/client/datascience/jupyter/kernels/kernelSelections.ts

Co-authored-by: Kim-Adeline Miguel <[email protected]>

* Update src/test/mocks/vsc/uri.ts

Co-authored-by: Kim-Adeline Miguel <[email protected]>

* Update news/3 Code Health/12101.md

Co-authored-by: Kim-Adeline Miguel <[email protected]>
Co-authored-by: Kartik Raj <[email protected]>

Author: 3 people

news/3 Code Health/12101.md

@@ -0,0 +1 @@
+Update JSDoc annotations for many of the APIs (thanks [tonybaloney](https://github.com/tonybaloney))

src/client/common/process/pythonDaemonPool.ts

@@ -106,6 +106,7 @@ export class PythonDaemonExecutionServicePool extends PythonDaemonFactory implem
      * @private
      * @template T
      * @param {(daemon: IPythonExecutionService) => Promise<T>} cb
+     * @param daemonLogMessage
      * @returns {Promise<T>}
      * @memberof PythonDaemonExecutionServicePool
      */
@@ -130,6 +131,7 @@ export class PythonDaemonExecutionServicePool extends PythonDaemonFactory implem
      *
      * @private
      * @param {(daemon: IPythonExecutionService) => ObservableExecutionResult<string>} cb
+     * @param daemonLogMessage
      * @returns {ObservableExecutionResult<string>}
      * @memberof PythonDaemonExecutionServicePool
      */

src/client/common/terminal/environmentActivationProviders/condaActivationProvider.ts

@@ -129,7 +129,7 @@ export class CondaActivationCommandProvider implements ITerminalActivationComman
      * This configuration is documented on Conda.
      * Extension will not attempt to work around issues by trying to setup shell for user.
      *
-     * @param {string} envName
+     * @param {string} condaEnv
      * @returns {(Promise<string[] | undefined>)}
      * @memberof CondaActivationCommandProvider
      */

src/client/common/types.ts

@@ -571,6 +571,7 @@ export interface ICryptoUtils {
      * @returns hash as number, or string
      * @param data The string to hash
      * @param hashFormat Return format of the hash, number or string
+     * @param [algorithm]
      */
     createHash<E extends keyof IHashFormat>(
         data: string,

src/client/common/utils/cacheUtils.ts

@@ -23,9 +23,9 @@ const resourceSpecificCacheStores = new Map<string, Map<string, CacheData>>();
  * Get a cache key specific to a resource (i.e. workspace)
  * This key will be used to cache interpreter related data, hence the Python Path
  *  used in a workspace will affect the cache key.
- * @param {String} keyPrefix
  * @param {Resource} resource
  * @param {VSCodeType} [vscode=require('vscode')]
+ * @param serviceContainer
  * @returns
  */
 function getCacheKey(
@@ -70,9 +70,9 @@ function getCacheKey(
 }
 /**
  * Gets the cache store for a resource that's specific to the interpreter.
- * @param {string} keyPrefix
  * @param {Resource} resource
  * @param {VSCodeType} [vscode=require('vscode')]
+ * @param serviceContainer
  * @returns
  */
 function getCacheStore(

src/client/datascience/jupyter/interpreter/jupyterInterpreterDependencyService.ts

@@ -57,6 +57,7 @@ function sortProductsInOrderForInstallation(products: Product[]) {
  *
  * @export
  * @param {Product[]} products
+ * @param {string} [interpreterName]
  * @returns {string}
  */
 export function getMessageForLibrariesNotInstalled(products: Product[], interpreterName?: string): string {
@@ -291,7 +292,7 @@ export class JupyterInterpreterDependencyService {
      *
      * @private
      * @param {PythonInterpreter} interpreter
-     * @param {CancellationToken} [token]
+     * @param {CancellationToken} [_token]
      * @returns {Promise<boolean>}
      * @memberof JupyterInterpreterConfigurationService
      */

src/client/datascience/jupyter/jupyterDebugger.ts

@@ -243,7 +243,7 @@ export class JupyterDebugger implements IJupyterDebugger, ICellHashListener {
      * (temporary to hard-code and use these in here).
      * The old debugger will soon go away into oblivion...
      * @private
-     * @param {INotebook} notebook
+     * @param {INotebook} _notebook
      * @returns {Promise<string>}
      * @memberof JupyterDebugger
      */

src/client/datascience/jupyter/kernels/kernelSelections.ts

@@ -23,6 +23,7 @@ import { IKernelSelectionListProvider, IKernelSpecQuickPickItem, LiveKernelModel
  * Given a kernel spec, this will return a quick pick item with appropriate display names and the like.
  *
  * @param {IJupyterKernelSpec} kernelSpec
+ * @param {IPathUtils} pathUtils
  * @returns {IKernelSpecQuickPickItem}
  */
 function getQuickPickItemForKernelSpec(
@@ -41,6 +42,7 @@ function getQuickPickItemForKernelSpec(
  * Given an active kernel, this will return a quick pick item with appropriate display names and the like.
  *
  * @param {(LiveKernelModel)} kernel
+ * @param {IPathUtils} pathUtils
  * @returns {IKernelSpecQuickPickItem}
  */
 function getQuickPickItemForActiveKernel(kernel: LiveKernelModel, pathUtils: IPathUtils): IKernelSpecQuickPickItem {
@@ -185,6 +187,7 @@ export class KernelSelectionProvider {
     /**
      * Gets a selection of kernel specs from a remote session.
      *
+     * @param {Resource} resource
      * @param {IJupyterSessionManager} sessionManager
      * @param {CancellationToken} [cancelToken]
      * @returns {Promise<IKernelSpecQuickPickItem[]>}
@@ -222,6 +225,8 @@ export class KernelSelectionProvider {
     /**
      * Gets a selection of kernel specs for a local session.
      *
+     * @param {Resource} resource
+     * @param type
      * @param {IJupyterSessionManager} [sessionManager]
      * @param {CancellationToken} [cancelToken]
      * @returns {Promise<IKernelSelectionListProvider>}

src/client/datascience/jupyter/kernels/kernelSelector.ts

@@ -88,8 +88,11 @@ export class KernelSelector {
     /**
      * Selects a kernel from a remote session.
      *
+     * @param {Resource} resource
+     * @param {StopWatch} stopWatch
      * @param {IJupyterSessionManager} session
      * @param {CancellationToken} [cancelToken]
+     * @param {IJupyterKernelSpec | LiveKernelModel} [currentKernel]
      * @returns {Promise<KernelSpecInterpreter>}
      * @memberof KernelSelector
      */
@@ -120,8 +123,12 @@ export class KernelSelector {
     /**
      * Select a kernel from a local session.
      *
+     * @param {Resource} resource
+     * @param type
+     * @param {StopWatch} stopWatch
      * @param {IJupyterSessionManager} [session]
      * @param {CancellationToken} [cancelToken]
+     * @param {IJupyterKernelSpec | LiveKernelModel} [currentKernel]
      * @returns {Promise<KernelSpecInterpreter>}
      * @memberof KernelSelector
      */
@@ -155,8 +162,11 @@ export class KernelSelector {
      * Gets a kernel that needs to be used with a local session.
      * (will attempt to find the best matching kernel, or prompt user to use current interpreter or select one).
      *
+     * @param {Resource} resource
+     * @param type
      * @param {IJupyterSessionManager} [sessionManager]
      * @param {nbformat.INotebookMetadata} [notebookMetadata]
+     * @param {boolean} [disableUI]
      * @param {CancellationToken} [cancelToken]
      * @returns {Promise<KernelSpecInterpreter>}
      * @memberof KernelSelector
@@ -213,6 +223,7 @@ export class KernelSelector {
      * Gets a kernel that needs to be used with a remote session.
      * (will attempt to find the best matching kernel, or prompt user to use current interpreter or select one).
      *
+     * @param {Resource} resource
      * @param {IJupyterSessionManager} [sessionManager]
      * @param {nbformat.INotebookMetadata} [notebookMetadata]
      * @param {CancellationToken} [cancelToken]
@@ -439,9 +450,12 @@ export class KernelSelector {
      * Otherwise, if not provided user is changing the kernel after starting a notebook.
      *
      * @private
+     * @param {Resource} resource
      * @param {PythonInterpreter} interpreter
+     * @param type
      * @param {string} [displayNameOfKernelNotFound]
      * @param {IJupyterSessionManager} [session]
+     * @param {boolean} [disableUI]
      * @param {CancellationToken} [cancelToken]
      * @returns {Promise<KernelSpecInterpreter>}
      * @memberof KernelSelector

src/client/datascience/jupyter/kernels/kernelService.ts

@@ -276,6 +276,7 @@ export class KernelService {
      * - env = Will have environment variables of the activated environment.
      *
      * @param {PythonInterpreter} interpreter
+     * @param {boolean} [disableUI]
      * @param {CancellationToken} [cancelToken]
      * @returns {Promise<IJupyterKernelSpec>}
      * @memberof KernelService

src/client/debugger/extension/configuration/launch.json/updaterService.ts

@@ -68,9 +68,9 @@ export class LaunchJsonUpdaterServiceHelper {
     /**
      * Gets the string representation of the debug config for insertion in the document.
      * Adds necessary leading or trailing commas (remember the text is added into an array).
-     * @param {TextDocument} document
-     * @param {Position} position
      * @param {DebugConfiguration} config
+     * @param {PositionOfCursor} cursorPosition
+     * @param {PositionOfComma} [commaPosition]
      * @returns
      * @memberof LaunchJsonCompletionItemProvider
      */

src/client/interpreter/activation/wrapperEnvironmentActivationService.ts

@@ -95,7 +95,7 @@ export class WrapperEnvironmentActivationService implements IEnvironmentActivati
      * If a cached entry already exists, then ignore the implementation.
      *
      * @private
-     * @param {string} key
+     * @param {string} cacheKey
      * @param {(() => Promise<NodeJS.ProcessEnv | undefined>)} implementation
      * @returns {(Promise<NodeJS.ProcessEnv | undefined>)}
      * @memberof WrapperEnvironmentActivationService

src/client/interpreter/interpreterService.ts

@@ -216,6 +216,7 @@ export class InterpreterService implements Disposable, IInterpreterService {
      * The format is `Python <Version> <bitness> (<env name>: <env type>)`
      * E.g. `Python 3.5.1 32-bit (myenv2: virtualenv)`
      * @param {Partial<PythonInterpreter>} info
+     * @param {Uri} [resource]
      * @returns {string}
      * @memberof InterpreterService
      */

src/client/linters/linterAvailability.ts

@@ -96,7 +96,7 @@ export class AvailableLinterActivator implements IAvailableLinterActivator {
      * Check if the linter itself is available in the workspace's Python environment or
      * not.
      *
-     * @param linterProduct Linter to check in the current workspace environment.
+     * @param linterInfo Linter to check in the current workspace environment.
      * @param resource Context information for workspace.
      */
     public async isLinterAvailable(linterInfo: ILinterInfo, resource: Resource): Promise<boolean | undefined> {

src/client/testing/common/services/discoveredTestParser.ts

@@ -218,6 +218,7 @@ export class TestDiscoveredTestParser implements discovery.ITestDiscoveredTestPa
      *
      * @protected
      * @param {TestFolder} rootFolder
+     * @param {TestFile | TestSuite} parent
      * @param {TestFunction} parentFunction
      * @param {DiscoveredTests} discoveredTests
      * @param {Tests} tests

src/client/testing/pytest/services/testMessageService.ts

@@ -21,6 +21,7 @@ export class TestMessageService implements ITestMessageService {
      * Condense the test details down to just the potentially relevant information. Messages
      * should only be created for tests that were actually run.
      *
+     * @param rootDirectory
      * @param testResults Details about all known tests.
      */
     public async getFilteredTestMessages(rootDirectory: string, testResults: Tests): Promise<IPythonTestMessage[]> {

src/client/testing/unittest/services/parserService.ts

@@ -56,7 +56,8 @@ export class TestsParser implements ITestsParser {
      * Where tone_test = folder, Failing2Tests = class/suite, test_failure = method.
      * @private
      * @param {string} rootDirectory
-     * @param {string[]} testIds
+     * @param {string} testId
+     * @param {TestFile[]} testFiles
      * @returns {Tests}
      * @memberof TestsParser
      */

src/ipywidgets/src/embed.ts

@@ -55,7 +55,7 @@ function moduleNameToCDNUrl(moduleName: string, moduleVersion: string): string {
  * Load an amd module locally and fall back to specified CDN if unavailable.
  *
  * @param moduleName The name of the module to load..
- * @param version The semver range for the module, if loaded from a CDN.
+ * @param moduleVersion The semver range for the module, if loaded from a CDN.
  *
  * By default, the CDN service used is unpkg.com. However, this default can be
  * overriden by specifying another URL via the HTML attribute

src/ipywidgets/src/libembed.ts

@@ -40,6 +40,7 @@ export async function renderWidgets(
  *
  * @param element The DOM element to search for widget view state script tags
  * @param widgetState The widget manager state
+ * @param managerFactory The widget manager factory
  *
  * #### Notes
  *

src/test/mocks/vsc/uri.ts

@@ -311,6 +311,7 @@ export namespace vscUri {
          * `file:///usr/home`, or `scheme:with/path`.
          *
          * @param value A string which represents an URI (see `URI#toString`).
+         * @param {boolean} [_strict=false]
          */
         static parse(value: string, _strict: boolean = false): URI {
             const match = _regexp.exec(value);

src/test/testing/explorer/explorerTestData.ts

@@ -220,10 +220,11 @@ export function createMockWorkspaceService(): typemoq.IMock<IWorkspaceService> {
  * Create a testable mocked up version of the TestExplorerViewProvider. Creates any
  * mocked dependencies not provided in the parameters.
  *
- * @param testStore Test storage service, provides access to the Tests structure that the view is built from.
- * @param unitTestMgmtService Unit test management service that provides the 'onTestStatusUpdated' event.
- * @param workspaceService Workspace service used to determine the current workspace that the test view is showing.
- * @param disposableReg Disposable registry used to dispose of items in the view.
+ * @param {ITestCollectionStorageService} [testStore] Test storage service, provides access to the Tests structure that the view is built from.
+ * @param {Tests} [testsData]
+ * @param {ITestManagementService} [unitTestMgmtService] Unit test management service that provides the 'onTestStatusUpdated' event.
+ * @param {IWorkspaceService} [workspaceService] Workspace service used to determine the current workspace that the test view is showing.
+ * @param {ICommandManager} [commandManager]
  */
 export function createMockTestExplorer(
     testStore?: ITestCollectionStorageService,

src/test/testing/pytest/pytest.run.test.ts

@@ -243,6 +243,7 @@ function getRelevantSkippedIssuesFromTestDetailsForFile(testDetails: ITestDetail
 /**
  * Get the FlattenedTestFunction from the test results that's associated with the given testDetails object.
  *
+ * @param ioc IOC Test Container
  * @param results Results of the test run.
  * @param testFileUri The Uri of the test file that was run.
  * @param testDetails The details of a particular test.

types/@msrvida-python-program-analysis/rewrite-magics.d.ts

@@ -34,7 +34,7 @@ export interface LineMagicRewriter {
      * Rewrite the line magic.
      * @param matchedText the original matched text from the program
      * @param magicStmt the line magic text with newlines and continuations removed
-     * @param postion ((start_line, start_col),(end_line, end_col)) of `matchedText` within the cell
+     * @param position ((start_line, start_col),(end_line, end_col)) of `matchedText` within the cell
      * @return rewrite operation. Leave text empty if you want to use default rewrites.
      */
     rewrite(matchedText: string, magicStmt: string, position: MatchPosition): Rewrite;