packages/core: added some basic docs for OAuthRequestManager

packages/core/src/api/apis/implementations/OAuthRequestManager/BasicOAuthScopes.ts

@@ -16,6 +16,10 @@
 
 import { OAuthScopes, OAuthScopeLike } from '../../definitions/oauthrequest';
 
+/**
+ * The BasicOAuthScopes class is an implementation of OAuthScopes that
+ * works for any simple comma- or space-separated format of scope.
+ */
 export class BasicOAuthScopes implements OAuthScopes {
   static from(scopes: OAuthScopeLike, normalizer?: (scope: string) => string) {
     const normalized = BasicOAuthScopes.asStrings(scopes, normalizer);

packages/core/src/api/apis/implementations/OAuthRequestManager/OAuthPendingRequests.ts

@@ -36,6 +36,11 @@ export type OAuthPendingRequestsApi<ResultType> = {
   pending(): Observable<PendingRequest<ResultType>>;
 };
 
+/**
+ * The OAuthPendingRequests class is a utility for managing and observing
+ * a stream of requests for oauth scopes, and resolving them correctly once
+ * requests are fulfilled.
+ */
 export class OAuthPendingRequests<ResultType>
   implements OAuthPendingRequestsApi<ResultType> {
   private requests: RequestQueueEntry<ResultType>[] = [];

packages/core/src/api/apis/implementations/OAuthRequestManager/OAuthRequestManager.ts

@@ -24,6 +24,13 @@ import {
 import Observable from 'zen-observable';
 import { OAuthPendingRequests, PendingRequest } from './OAuthPendingRequests';
 
+/**
+ * The OAuthRequestManager is an implementation of the OAuthRequestApi.
+ *
+ * The purpose of this class and the API is to read a stream of incoming requests
+ * of OAuth access tokens from different providers with varying scope, and funnel
+ * them all together into a single requests for each OAuth provider.
+ */
 export class OAuthRequestManager implements OAuthRequestApi {
   private readonly requests$: Observable<AuthRequest[]>;
   private readonly observers = new Set<