From a98be63c7bb9c1205e2c3754ceca4dc2e930e139 Mon Sep 17 00:00:00 2001 From: Anthony Shaw Date: Fri, 19 Jun 2020 06:16:34 +1000 Subject: [PATCH] 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 <51720070+kimadeline@users.noreply.github.com> * Update src/client/datascience/jupyter/kernels/kernelSelector.ts Co-authored-by: Kim-Adeline Miguel <51720070+kimadeline@users.noreply.github.com> * Update src/client/datascience/jupyter/kernels/kernelSelections.ts Co-authored-by: Kim-Adeline Miguel <51720070+kimadeline@users.noreply.github.com> * Update src/test/mocks/vsc/uri.ts Co-authored-by: Kim-Adeline Miguel <51720070+kimadeline@users.noreply.github.com> * Update news/3 Code Health/12101.md Co-authored-by: Kim-Adeline Miguel <51720070+kimadeline@users.noreply.github.com> Co-authored-by: Kartik Raj --- news/3 Code Health/12101.md | 1 + src/client/common/process/pythonDaemonPool.ts | 2 ++ .../condaActivationProvider.ts | 2 +- src/client/common/types.ts | 1 + src/client/common/utils/cacheUtils.ts | 4 ++-- .../jupyterInterpreterDependencyService.ts | 3 ++- src/client/datascience/jupyter/jupyterDebugger.ts | 2 +- .../jupyter/kernels/kernelSelections.ts | 5 +++++ .../datascience/jupyter/kernels/kernelSelector.ts | 14 ++++++++++++++ .../datascience/jupyter/kernels/kernelService.ts | 1 + .../configuration/launch.json/updaterService.ts | 4 ++-- .../wrapperEnvironmentActivationService.ts | 2 +- src/client/interpreter/interpreterService.ts | 1 + src/client/linters/linterAvailability.ts | 2 +- .../common/services/discoveredTestParser.ts | 1 + .../testing/pytest/services/testMessageService.ts | 1 + .../testing/unittest/services/parserService.ts | 3 ++- src/ipywidgets/src/embed.ts | 2 +- src/ipywidgets/src/libembed.ts | 1 + src/test/mocks/vsc/uri.ts | 1 + src/test/testing/explorer/explorerTestData.ts | 9 +++++---- src/test/testing/pytest/pytest.run.test.ts | 1 + .../rewrite-magics.d.ts | 2 +- 23 files changed, 49 insertions(+), 16 deletions(-) create mode 100644 news/3 Code Health/12101.md diff --git a/news/3 Code Health/12101.md b/news/3 Code Health/12101.md new file mode 100644 index 000000000000..2f8790192773 --- /dev/null +++ b/news/3 Code Health/12101.md @@ -0,0 +1 @@ +Update JSDoc annotations for many of the APIs (thanks [tonybaloney](https://github.com/tonybaloney)) diff --git a/src/client/common/process/pythonDaemonPool.ts b/src/client/common/process/pythonDaemonPool.ts index 204c9ab33961..a436918c7e71 100644 --- a/src/client/common/process/pythonDaemonPool.ts +++ b/src/client/common/process/pythonDaemonPool.ts @@ -106,6 +106,7 @@ export class PythonDaemonExecutionServicePool extends PythonDaemonFactory implem * @private * @template T * @param {(daemon: IPythonExecutionService) => Promise} cb + * @param daemonLogMessage * @returns {Promise} * @memberof PythonDaemonExecutionServicePool */ @@ -130,6 +131,7 @@ export class PythonDaemonExecutionServicePool extends PythonDaemonFactory implem * * @private * @param {(daemon: IPythonExecutionService) => ObservableExecutionResult} cb + * @param daemonLogMessage * @returns {ObservableExecutionResult} * @memberof PythonDaemonExecutionServicePool */ diff --git a/src/client/common/terminal/environmentActivationProviders/condaActivationProvider.ts b/src/client/common/terminal/environmentActivationProviders/condaActivationProvider.ts index fa49afb2a29e..3f4b5cfaa809 100644 --- a/src/client/common/terminal/environmentActivationProviders/condaActivationProvider.ts +++ b/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)} * @memberof CondaActivationCommandProvider */ diff --git a/src/client/common/types.ts b/src/client/common/types.ts index 2a819b27a3c0..655cc86d6c7b 100644 --- a/src/client/common/types.ts +++ b/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( data: string, diff --git a/src/client/common/utils/cacheUtils.ts b/src/client/common/utils/cacheUtils.ts index 0f57303d75bf..2f6895b4e5a8 100644 --- a/src/client/common/utils/cacheUtils.ts +++ b/src/client/common/utils/cacheUtils.ts @@ -23,9 +23,9 @@ const resourceSpecificCacheStores = new Map>(); * 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( diff --git a/src/client/datascience/jupyter/interpreter/jupyterInterpreterDependencyService.ts b/src/client/datascience/jupyter/interpreter/jupyterInterpreterDependencyService.ts index 7d7dfd479ef6..fb6e38e85082 100644 --- a/src/client/datascience/jupyter/interpreter/jupyterInterpreterDependencyService.ts +++ b/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} * @memberof JupyterInterpreterConfigurationService */ diff --git a/src/client/datascience/jupyter/jupyterDebugger.ts b/src/client/datascience/jupyter/jupyterDebugger.ts index 7093b7f052cc..e3ef10f4b68a 100644 --- a/src/client/datascience/jupyter/jupyterDebugger.ts +++ b/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} * @memberof JupyterDebugger */ diff --git a/src/client/datascience/jupyter/kernels/kernelSelections.ts b/src/client/datascience/jupyter/kernels/kernelSelections.ts index 0797f75f1b93..496347eb3748 100644 --- a/src/client/datascience/jupyter/kernels/kernelSelections.ts +++ b/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} @@ -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} diff --git a/src/client/datascience/jupyter/kernels/kernelSelector.ts b/src/client/datascience/jupyter/kernels/kernelSelector.ts index d0e4c10e59ac..fa96571574f8 100644 --- a/src/client/datascience/jupyter/kernels/kernelSelector.ts +++ b/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} * @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} * @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} * @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} * @memberof KernelSelector diff --git a/src/client/datascience/jupyter/kernels/kernelService.ts b/src/client/datascience/jupyter/kernels/kernelService.ts index 2babf7909e54..5d47ebe2bdf0 100644 --- a/src/client/datascience/jupyter/kernels/kernelService.ts +++ b/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} * @memberof KernelService diff --git a/src/client/debugger/extension/configuration/launch.json/updaterService.ts b/src/client/debugger/extension/configuration/launch.json/updaterService.ts index e615ca9ecf36..199cd0ecffa1 100644 --- a/src/client/debugger/extension/configuration/launch.json/updaterService.ts +++ b/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 */ diff --git a/src/client/interpreter/activation/wrapperEnvironmentActivationService.ts b/src/client/interpreter/activation/wrapperEnvironmentActivationService.ts index 2540a8164ba1..e9aa7a789b4e 100644 --- a/src/client/interpreter/activation/wrapperEnvironmentActivationService.ts +++ b/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)} implementation * @returns {(Promise)} * @memberof WrapperEnvironmentActivationService diff --git a/src/client/interpreter/interpreterService.ts b/src/client/interpreter/interpreterService.ts index 6fa05f296bb1..6eb3abc5cc0f 100644 --- a/src/client/interpreter/interpreterService.ts +++ b/src/client/interpreter/interpreterService.ts @@ -216,6 +216,7 @@ export class InterpreterService implements Disposable, IInterpreterService { * The format is `Python (: )` * E.g. `Python 3.5.1 32-bit (myenv2: virtualenv)` * @param {Partial} info + * @param {Uri} [resource] * @returns {string} * @memberof InterpreterService */ diff --git a/src/client/linters/linterAvailability.ts b/src/client/linters/linterAvailability.ts index f03643ecceb2..834a86284610 100644 --- a/src/client/linters/linterAvailability.ts +++ b/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 { diff --git a/src/client/testing/common/services/discoveredTestParser.ts b/src/client/testing/common/services/discoveredTestParser.ts index c3b88a298790..200c50cd88bd 100644 --- a/src/client/testing/common/services/discoveredTestParser.ts +++ b/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 diff --git a/src/client/testing/pytest/services/testMessageService.ts b/src/client/testing/pytest/services/testMessageService.ts index 1c6a1df595f2..049833c001e9 100644 --- a/src/client/testing/pytest/services/testMessageService.ts +++ b/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 { diff --git a/src/client/testing/unittest/services/parserService.ts b/src/client/testing/unittest/services/parserService.ts index c097acc6a7cd..41ad7c9fa28c 100644 --- a/src/client/testing/unittest/services/parserService.ts +++ b/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 */ diff --git a/src/ipywidgets/src/embed.ts b/src/ipywidgets/src/embed.ts index d72c2cc14923..ecafca9e9810 100644 --- a/src/ipywidgets/src/embed.ts +++ b/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 diff --git a/src/ipywidgets/src/libembed.ts b/src/ipywidgets/src/libembed.ts index b840c477dc6a..9c1938407d03 100644 --- a/src/ipywidgets/src/libembed.ts +++ b/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 * diff --git a/src/test/mocks/vsc/uri.ts b/src/test/mocks/vsc/uri.ts index 5c3f4c63a655..6e57fee0d9c7 100644 --- a/src/test/mocks/vsc/uri.ts +++ b/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); diff --git a/src/test/testing/explorer/explorerTestData.ts b/src/test/testing/explorer/explorerTestData.ts index 6034beb617d6..bd8acf2b17c1 100644 --- a/src/test/testing/explorer/explorerTestData.ts +++ b/src/test/testing/explorer/explorerTestData.ts @@ -220,10 +220,11 @@ export function createMockWorkspaceService(): typemoq.IMock { * 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, diff --git a/src/test/testing/pytest/pytest.run.test.ts b/src/test/testing/pytest/pytest.run.test.ts index e23b28db1ccc..89508ade19a9 100644 --- a/src/test/testing/pytest/pytest.run.test.ts +++ b/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. diff --git a/types/@msrvida-python-program-analysis/rewrite-magics.d.ts b/types/@msrvida-python-program-analysis/rewrite-magics.d.ts index 384cab09cb3a..536b848eb91b 100644 --- a/types/@msrvida-python-program-analysis/rewrite-magics.d.ts +++ b/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;