Chore: document exposed interop functions

vscode/microsoft-kiota/src/kiotaInterop/lib/generateClient.ts

@@ -1,3 +1,26 @@
+/**
+ * Options for generating a client.
+ *
+ * @param {boolean} clearCache - Whether to clear the cache before generating the client.
+ * @param {boolean} cleanOutput - Whether to clean the output directory before generating the client.
+ * @param {string} clientClassName - The name of the client class to generate.
+ * @param {string} clientNamespaceName - The namespace name for the generated client.
+ * @param {string[]} deserializers - The list of deserializers to use.
+ * @param {string[]} disabledValidationRules - The list of validation rules to disable.
+ * @param {boolean} excludeBackwardCompatible - Whether to exclude backward-compatible changes.
+ * @param {string[]} excludePatterns - The list of patterns to exclude from generation.
+ * @param {boolean} includeAdditionalData - Whether to include additional data in the generated client.
+ * @param {string[]} includePatterns - The list of patterns to include in generation.
+ * @param {KiotaGenerationLanguage} language - The programming language for the generated client.
+ * @param {string} openAPIFilePath - The file path to the OpenAPI specification.
+ * @param {string} outputPath - The output path for the generated client.
+ * @param {string[]} serializers - The list of serializers to use.
+ * @param {string[]} structuredMimeTypes - The list of structured MIME types to support.
+ * @param {boolean} usesBackingStore - Whether the generated client uses a backing store.
+ * @param {ConsumerOperation} operation - The consumer operation to perform.
+ * @param {string} workingDirectory - The working directory for the generation process.
+ *
+ */
 import * as rpc from "vscode-jsonrpc/node";
 
 import { checkForSuccess, ConsumerOperation, GenerationConfiguration, KiotaLogEntry } from "..";
@@ -26,6 +49,34 @@ interface ClientGenerationOptions {
   workingDirectory: string;
 }
 
+/**
+ * Generates a client based on the provided client generation options.
+ *
+ * @param {ClientGenerationOptions} clientGenerationOptions - The options for generating the client.
+ *  * Options for generating a client.
+ *
+ * @param {boolean} clientGenerationOptions.clearCache - Whether to clear the cache before generating the client.
+ * @param {boolean} clientGenerationOptions.cleanOutput - Whether to clean the output directory before generating the client.
+ * @param {string} clientGenerationOptions.clientClassName - The name of the client class to generate.
+ * @param {string} clientGenerationOptions.clientNamespaceName - The namespace name for the generated client.
+ * @param {string[]} clientGenerationOptions.deserializers - The list of deserializers to use.
+ * @param {string[]} clientGenerationOptions.disabledValidationRules - The list of validation rules to disable.
+ * @param {boolean} clientGenerationOptions.excludeBackwardCompatible - Whether to exclude backward-compatible changes.
+ * @param {string[]} clientGenerationOptions.excludePatterns - The list of patterns to exclude from generation.
+ * @param {boolean} clientGenerationOptions.includeAdditionalData - Whether to include additional data in the generated client.
+ * @param {string[]} clientGenerationOptions.includePatterns - The list of patterns to include in generation.
+ * @param {KiotaGenerationLanguage} clientGenerationOptions.language - The programming language for the generated client.
+ * @param {string} clientGenerationOptions.openAPIFilePath - The file path to the OpenAPI specification.
+ * @param {string} clientGenerationOptions.outputPath - The output path for the generated client.
+ * @param {string[]} clientGenerationOptions.serializers - The list of serializers to use.
+ * @param {string[]} clientGenerationOptions.structuredMimeTypes - The list of structured MIME types to support.
+ * @param {boolean} clientGenerationOptions.usesBackingStore - Whether the generated client uses a backing store.
+ * @param {ConsumerOperation} clientGenerationOptions.operation - The consumer operation to perform.
+ * @param {string} clientGenerationOptions.workingDirectory - The working directory for the generation process.
+
+ * @returns {Promise<KiotaResult | undefined>} A promise that resolves to a KiotaResult if successful, or undefined if not.
+ * @throws {Error} If an error occurs during the client generation process.
+ */
 export async function generateClient(clientGenerationOptions: ClientGenerationOptions): Promise<KiotaResult | undefined> {
   const result = await connectToKiota<KiotaLogEntry[]>(async (connection) => {
     const request = new rpc.RequestType1<GenerationConfiguration, KiotaLogEntry[], void>(

vscode/microsoft-kiota/src/kiotaInterop/lib/generatePlugin.ts

@@ -21,6 +21,29 @@ interface PluginGenerationOptions {
   workingDirectory: string;
 }
 
+/**
+ * Generates a plugin based on the provided options.
+ *
+ * @param {PluginGenerationOptions} pluginGenerationOptions - The options for generating the plugin.
+ * @param {string} pluginGenerationOptions.openAPIFilePath - The file path to the OpenAPI specification.
+ * @param {string} pluginGenerationOptions.outputPath - The output path where the generated plugin will be saved.
+ * @param {KiotaPluginType[]} pluginGenerationOptions.pluginTypes - The types of plugins to generate.
+ * @param {string[]} pluginGenerationOptions.includePatterns - The patterns to include in the generation process.
+ * @param {string[]} pluginGenerationOptions.excludePatterns - The patterns to exclude from the generation process.
+ * @param {string} pluginGenerationOptions.clientClassName - The name of the client class to generate.
+ * @param {boolean} pluginGenerationOptions.clearCache - Whether to clear the cache before generation.
+ * @param {boolean} pluginGenerationOptions.cleanOutput - Whether to clean the output directory before generation.
+ * @param {string[]} pluginGenerationOptions.disabledValidationRules - The validation rules to disable during generation.
+ * @param {ConsumerOperation} pluginGenerationOptions.operation - The operation to perform during generation.
+ * @param {PluginAuthType | null} [pluginGenerationOptions.pluginAuthType] - The authentication type for the plugin, if any.
+ * @param {string} [pluginGenerationOptions.pluginAuthRefid] - The reference ID for the plugin authentication, if any.
+ * @param {string} pluginGenerationOptions.workingDirectory - The working directory for the generation process.
+ * @returns {Promise<KiotaResult | undefined>} A promise that resolves to a KiotaResult if successful, or undefined if not.
+ * @throws {Error} If an error occurs during the generation process.
+ *
+ * The function connects to Kiota and sends a request to generate a plugin using the provided options.
+ * It handles the response and checks for success, returning the result or throwing an error if one occurs.
+ */
 export async function generatePlugin(pluginGenerationOptions: PluginGenerationOptions
 ): Promise<KiotaResult | undefined> {
   const result = await connectToKiota<KiotaLogEntry[]>(async (connection) => {

vscode/microsoft-kiota/src/kiotaInterop/lib/getKiotaTree.ts

@@ -10,6 +10,17 @@ interface KiotaResultOptions {
   clearCache: boolean;
 }
 
+/**
+ * Shows the Kiota result based on the provided options.
+ *
+ * @param {KiotaResultOptions} options - The options to configure the Kiota result.
+ * @param {string[]} options.includeFilters - Filters to include in the result.
+ * @param {string} options.descriptionPath - The path to the description file.
+ * @param {string[]} options.excludeFilters - Filters to exclude from the result.
+ * @param {boolean} options.clearCache - Whether to clear the cache before showing the result.
+ * @returns {Promise<KiotaTreeResult | undefined>} A promise that resolves to the Kiota show result or undefined if an error occurs.
+ * @throws {Error} Throws an error if the result is an instance of Error.
+ */
 export async function getKiotaTree({ includeFilters, descriptionPath, excludeFilters, clearCache }: KiotaResultOptions): Promise<KiotaTreeResult | undefined> {
   const result = await connectToKiota(async (connection) => {
     const request = new rpc.RequestType<KiotaShowConfiguration, KiotaTreeResult, void>('Show');

vscode/microsoft-kiota/src/kiotaInterop/lib/getKiotaVersion.ts

@@ -2,6 +2,12 @@ import * as rpc from "vscode-jsonrpc/node";
 
 import connectToKiota from '../connect';
 
+/**
+ * Retrieves the version of Kiota by connecting to the Kiota service.
+ *
+ * @returns {Promise<string | undefined>} A promise that resolves to the Kiota version string if available, otherwise undefined.
+ * @throws {Error} If an error occurs while connecting to the Kiota service or retrieving the version.
+ */
 export async function getKiotaVersion(): Promise<string | undefined> {
 
   const result = await connectToKiota<string>(async (connection) => {

vscode/microsoft-kiota/src/kiotaInterop/lib/getManifestDetails.ts

@@ -9,6 +9,16 @@ interface ManifestOptions {
   apiIdentifier?: string;
 }
 
+/**
+ * Retrieves the manifest details for a given API.
+ *
+ * @param {ManifestOptions} options - The options for retrieving the manifest details.
+ * @param {string} options.manifestPath - The path to the manifest file.
+ * @param {boolean} options.clearCache - Whether to clear the cache before retrieving the manifest details.
+ * @param {string} [options.apiIdentifier] - The identifier of the API.
+ * @returns {Promise<KiotaManifestResult | undefined>} A promise that resolves to the manifest details or undefined if not found.
+ * @throws {Error} Throws an error if the request fails.
+ */
 export async function getManifestDetails({ manifestPath, clearCache, apiIdentifier }: ManifestOptions): Promise<KiotaManifestResult | undefined> {
   const result = await connectToKiota(async (connection) => {
     const request = new rpc.RequestType<KiotaGetManifestDetailsConfiguration, KiotaManifestResult, void>('GetManifestDetails');

vscode/microsoft-kiota/src/kiotaInterop/lib/languageInformation.ts

@@ -7,6 +7,16 @@ interface LanguageInformationConfiguration {
   descriptionUrl: string; clearCache: boolean;
 }
 
+/**
+ * Retrieves language information by connecting to Kiota.
+ *
+ * This function establishes a connection to Kiota and sends a request to retrieve
+ * language information. If the request is successful, it returns the language information.
+ * If an error occurs during the request, the error is thrown.
+ *
+ * @returns {Promise<LanguagesInformation | undefined>} A promise that resolves to the language information or undefined if an error occurs.
+ * @throws {Error} Throws an error if the request fails.
+ */
 export async function getLanguageInformationInternal(): Promise<LanguagesInformation | undefined> {
   const result = await connectToKiota<LanguagesInformation>(async (connection) => {
     const request = new rpc.RequestType0<LanguagesInformation, void>(
@@ -24,6 +34,17 @@ export async function getLanguageInformationInternal(): Promise<LanguagesInforma
   return result;
 };
 
+/**
+ * Retrieves language information based on the provided description URL.
+ * 
+ * @param {LanguageInformationConfiguration} config - The configuration object containing the description URL and cache clearing option.
+ * @param {string} config.descriptionUrl - The URL of the description to retrieve language information for.
+ * @param {boolean} config.clearCache - A flag indicating whether to clear the cache before retrieving the information.
+ * 
+ * @returns {Promise<LanguagesInformation | undefined>} A promise that resolves to the language information or undefined if an error occurs.
+ * 
+ * @throws {Error} Throws an error if the request fails.
+ */
 export async function getLanguageInformationForDescription({ descriptionUrl, clearCache }: LanguageInformationConfiguration):
   Promise<LanguagesInformation | undefined> {
   const result = await connectToKiota<LanguagesInformation>(async (connection) => {

vscode/microsoft-kiota/src/kiotaInterop/lib/migrateFromLockFile.ts

@@ -3,6 +3,17 @@ import * as rpc from "vscode-jsonrpc/node";
 import { KiotaLogEntry } from "..";
 import connectToKiota from "../connect";
 
+/**
+ * Migrates data from a lock file located in the specified directory.
+ *
+ * This function connects to the Kiota service and sends a request to migrate data from the lock file.
+ * If the migration is successful, it returns an array of `KiotaLogEntry` objects.
+ * If an error occurs during the migration, the error is thrown.
+ *
+ * @param {string} lockFileDirectory - The directory where the lock file is located.
+ * @returns {Promise<KiotaLogEntry[] | undefined>} A promise that resolves to an array of `KiotaLogEntry` objects if the migration is successful, or `undefined` if no data is migrated.
+ * @throws {Error} If an error occurs during the migration process.
+ */
 export async function migrateFromLockFile(lockFileDirectory: string): Promise<KiotaLogEntry[] | undefined> {
   const result = await connectToKiota(async (connection) => {
     const request = new rpc.RequestType1<string, KiotaLogEntry[], void>(

vscode/microsoft-kiota/src/kiotaInterop/lib/removeItem.ts

@@ -16,6 +16,16 @@ interface RemoveClientConfiguration extends RemoveItemConfiguration {
   clientName: string;
 }
 
+/**
+ * Removes a plugin from the Kiota environment.
+ *
+ * @param {RemovePluginConfiguration} config - The configuration for removing the plugin.
+ * @param {string} config.pluginName - The name of the plugin to remove.
+ * @param {boolean} config.cleanOutput - Whether to clean the output directory after removal.
+ * @param {string} config.workingDirectory - The working directory where the operation should be performed.
+ * @returns {Promise<KiotaResult | undefined>} A promise that resolves to a KiotaResult if the operation is successful, or undefined if no result is returned.
+ * @throws {Error} Throws an error if the operation fails.
+ */
 export async function removePlugin({ pluginName, cleanOutput, workingDirectory }: RemovePluginConfiguration): Promise<KiotaResult | undefined> {
   const result = await connectToKiota(async (connection) => {
     const request = new rpc.RequestType2<string, boolean, KiotaLogEntry[], void>(
@@ -42,10 +52,16 @@ export async function removePlugin({ pluginName, cleanOutput, workingDirectory }
   return undefined;
 };
 
-
-
-
-
+/**
+ * Removes a client using the provided configuration.
+ *
+ * @param {RemoveClientConfiguration} config - The configuration for removing the client.
+ * @param {string} config.clientName - The name of the client to be removed.
+ * @param {boolean} config.cleanOutput - A flag indicating whether to clean the output.
+ * @param {string} config.workingDirectory - The working directory for the operation.
+ * @returns {Promise<KiotaResult | undefined>} A promise that resolves to a KiotaResult if the client was removed successfully, or undefined if no result is returned.
+ * @throws {Error} Throws an error if the result is an instance of Error.
+ */
 export async function removeClient({ clientName, cleanOutput, workingDirectory }: RemoveClientConfiguration): Promise<KiotaResult | undefined> {
   const result = await connectToKiota(async (connection) => {
     const request = new rpc.RequestType2<string, boolean, KiotaLogEntry[], void>(

vscode/microsoft-kiota/src/kiotaInterop/lib/searchDescription.ts

@@ -8,6 +8,15 @@ interface SearchConfiguration {
   clearCache: boolean;
 }
 
+/**
+ * Searches for a description based on the provided search term and cache settings.
+ *
+ * @param {SearchConfiguration} config - The search configuration object.
+ * @param {string} config.searchTerm - The term to search for.
+ * @param {boolean} config.clearCache - Whether to clear the cache before searching.
+ * @returns {Promise<Record<string, KiotaSearchResultItem> | undefined>} A promise that resolves to a record of search results or undefined if no results are found.
+ * @throws {Error} Throws an error if the search operation fails.
+ */
 export async function searchDescription({ searchTerm, clearCache }: SearchConfiguration): Promise<Record<string, KiotaSearchResultItem> | undefined> {
   const result = await connectToKiota(async (connection) => {
     const request = new rpc.RequestType2<string, boolean, KiotaSearchResult, void>(

vscode/microsoft-kiota/src/kiotaInterop/lib/updateClients.ts

@@ -9,6 +9,18 @@ interface UpdateClientsConfiguration {
   workspacePath: string;
 }
 
+/**
+ * Updates the clients by connecting to Kiota and sending a request to update.
+ * 
+ * @param {UpdateClientsConfiguration} config - The configuration object containing the following properties:
+ * @param {boolean} config.cleanOutput - Whether to clean the output directory before updating.
+ * @param {boolean} config.clearCache - Whether to clear the cache before updating.
+ * @param {string} config.workspacePath - The path to the workspace where the clients are located.
+ * 
+ * @returns {Promise<KiotaLogEntry[] | undefined>} A promise that resolves to an array of Kiota log entries if the update is successful, or undefined if there is an error.
+ * 
+ * @throws {Error} Throws an error if the result of the update is an instance of Error.
+ */
 export async function updateClients({ cleanOutput, clearCache, workspacePath }: UpdateClientsConfiguration): Promise<KiotaLogEntry[] | undefined> {
   const result = await connectToKiota(async (connection) => {
     const request = new rpc.RequestType3<string, boolean, boolean, KiotaLogEntry[], void>(

vscode/microsoft-kiota/src/kiotaInterop/readme.md

@@ -0,0 +1,59 @@
+# Kiota Interop Library
+
+This library provides various functions to interact with Kiota, a client generator for HTTP REST APIs described by OpenAPI.
+
+## Installation
+Provide instructions on how to install the project.
+
+```bash
+npm install kiota-Interop
+```
+
+## Usage
+
+### [`getKiotaTree`](/kiotaInterop./lib/getKiotaTree.ts )
+Returns a tree of the open api description.
+
+### [`generateClient`](./lib/generateClient.ts )
+
+Generates a client based on the provided client generation options.
+
+### [`generatePlugin`](./lib/generatePlugin.ts )
+
+The function connects to Kiota and sends a request to generate a plugin using the provided options.
+It handles the response and checks for success, returning the result or throwing an error if one occurs.
+
+### [`getKiotaVersion`](./lib/getKiotaVersion.ts )
+
+Retrieves the version of Kiota by connecting to the Kiota service.
+
+
+### [`getManifestDetails`](./lib/getManifestDetails.ts )
+
+Retrieves the manifest details for a given API.
+
+### [`getLanguageInformationInternal`](./lib/languageInformation.ts )
+
+Retrieves language information by connecting to Kiota
+
+### [`getLanguageInformationForDescription`](./lib/languageInformation.ts )
+
+Retrieves language information based on the provided description URL.
+
+### [`migrateFromLockFile`](./lib/migrateFromLockFile.ts )
+
+Migrates data from a lock file located in the specified directory.
+
+### [`removePlugin`](./lib/removeItem.ts )
+
+Removes a plugin from the Kiota environment.
+
+### [`removeClient`](./lib/removeItem.ts )
+Removes a client using the provided configuration.
+
+### [`searchDescription`](./lib/searchDescription.ts )
+Searches for a description based on the provided search term and cache settings.
+
+### [`updateClients`](./lib/updateClients.ts )
+Updates the clients in the Kiota environment.
+