@vscode/python-extension typings polish suggestions

[Tyriar]

I didn't know what this meant. We try to document every API in vscode.d.ts which I like for a formal API like this as then there's no ambiguity on where to stop and what's obvious or not.

    jupyter: {
        registerHooks(): void;
    };

The parameters are defined but not described.
nit: Uses JS-style typings when we should be native TS imo (don't mention the types after @param)

        /**
         * Generate an array of strings for commands to pass to the Python executable to launch the debugger for remote debugging.
         * Users can append another array of strings of what they want to execute along with relevant arguments to Python.
         * E.g `['/Users/..../pythonVSCode/pythonFiles/lib/python/debugpy', '--listen', 'localhost:57039', '--wait-for-client']`
         * @param {string} host
         * @param {number} port
         * @param {boolean} [waitUntilDebuggerAttaches=true]
         * @returns {Promise<string[]>}
         */
        getRemoteLauncherCommand(host: string, port: number, waitUntilDebuggerAttaches: boolean): Promise<string[]>;

PythonExtension is both a namespace and an interface, this would be easier to read if they differed:

export declare namespace PythonExtension {
    /**
     * Returns the API exposed by the Python extension in VS Code.
     */
    function api(): Promise<PythonExtension>;
}

[karrtikr]

We try to document every API in vscode.d.ts which I like for a formal API like this as then there's no ambiguity on where to stop and what's obvious or not.

These are APIs that're only to be used for internal use by Jupyter, hence not documented. I wonder if we should expose these at all, opened microsoft/vscode-jupyter#13982 at Jupyter to clarify.

PythonExtension is both a namespace and an interface, this would be easier to read if they differed:

Inspiration from that is taken from WASM:

"The API is exported using the same name as the namespace to access the API (e.g. both Wasm). That allows to write nice code on the usage side and will also allow to move API into VS Code extension host without breakage since I follow the same API patterns"

I personally like it as it allows for nice usage like this:

[Tyriar]

@karrtikr do you mean @vscode/python-extension is only meant for jupyter, or just the hooks call?

[karrtikr]

Just the hooks call:

jupyter: {
    registerHooks(): void;
};

[Tyriar]

I'd recommend remove them then as if it's there someone will probably use it.

Feel free to close this