diff --git a/src/vs/vscode.d.ts b/src/vs/vscode.d.ts
index 584abf2eb18..60fe1cf9379 100644
--- a/src/vs/vscode.d.ts
+++ b/src/vs/vscode.d.ts
@@ -11605,12 +11605,18 @@ declare module 'vscode' {
 		readonly provider: AuthenticationProviderInformation;
 	}
 
+	/**
+	 * Namespace for authentication.
+	 */
 	export namespace authentication {
 		/**
 		 * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not
 		 * registered, or if the user does not consent to sharing authentication information with
 		 * the extension. If there are multiple sessions with the same scopes, the user will be shown a
 		 * quickpick to select which account they would like to use.
+		 *
+		 * Currently, there are only two authentication providers that are contributed from built in extensions
+		 * to VS Code that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.
 		 * @param providerId The id of the provider to use
 		 * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider
 		 * @param options The [getSessionOptions](#GetSessionOptions) to use
@@ -11623,6 +11629,9 @@ declare module 'vscode' {
 		 * registered, or if the user does not consent to sharing authentication information with
 		 * the extension. If there are multiple sessions with the same scopes, the user will be shown a
 		 * quickpick to select which account they would like to use.
+		 *
+		 * Currently, there are only two authentication providers that are contributed from built in extensions
+		 * to VS Code that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.
 		 * @param providerId The id of the provider to use
 		 * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider
 		 * @param options The [getSessionOptions](#GetSessionOptions) to use