clean up exports in core-app-api

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

.changeset/twenty-cups-suffer.md

@@ -0,0 +1,5 @@
+---
+'@backstage/core-app-api': patch
+---
+
+Api cleanup, adding `@public` where necessary and tweaking some comments

packages/core-app-api/api-report.md

@@ -58,8 +58,6 @@ import { StorageApi } from '@backstage/core-plugin-api';
 import { StorageValueChange } from '@backstage/core-plugin-api';
 import { SubRouteRef } from '@backstage/core-plugin-api';
 
-// Warning: (ae-missing-release-tag) "AlertApiForwarder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class AlertApiForwarder implements AlertApi {
   // (undocumented)
@@ -68,8 +66,6 @@ export class AlertApiForwarder implements AlertApi {
   post(alert: AlertMessage): void;
 }
 
-// Warning: (ae-missing-release-tag) "ApiFactoryHolder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type ApiFactoryHolder = {
   get<T>(api: ApiRef<T>):
@@ -83,8 +79,6 @@ export type ApiFactoryHolder = {
     | undefined;
 };
 
-// Warning: (ae-missing-release-tag) "ApiFactoryRegistry" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class ApiFactoryRegistry implements ApiFactoryHolder {
   // (undocumented)
@@ -109,11 +103,9 @@ export class ApiFactoryRegistry implements ApiFactoryHolder {
   >(scope: ApiFactoryScope, factory: ApiFactory<Api, Impl, Deps>): boolean;
 }
 
-// Warning: (ae-missing-release-tag) "ApiProvider" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const ApiProvider: {
-  ({ apis, children }: PropsWithChildren<ApiProviderProps>): JSX.Element;
+  (props: PropsWithChildren<ApiProviderProps>): JSX.Element;
   propTypes: {
     apis: PropTypes.Validator<
       PropTypes.InferProps<{
@@ -124,9 +116,7 @@ export const ApiProvider: {
   };
 };
 
-// Warning: (ae-missing-release-tag) "ApiRegistry" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class ApiRegistry implements ApiHolder {
   constructor(apis: Map<string, unknown>);
   // Warning: (ae-forgotten-export) The symbol "ApiRegistryBuilder" needs to be exported by the entry point index.d.ts
@@ -134,22 +124,14 @@ export class ApiRegistry implements ApiHolder {
   // (undocumented)
   static builder(): ApiRegistryBuilder;
   // Warning: (ae-forgotten-export) The symbol "ApiImpl" needs to be exported by the entry point index.d.ts
-  //
-  // (undocumented)
   static from(apis: ApiImpl[]): ApiRegistry;
   // (undocumented)
   get<T>(api: ApiRef<T>): T | undefined;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   static with<T>(api: ApiRef<T>, impl: T): ApiRegistry;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   with<T>(api: ApiRef<T>, impl: T): ApiRegistry;
 }
 
-// Warning: (ae-missing-release-tag) "ApiResolver" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class ApiResolver implements ApiHolder {
   constructor(factories: ApiFactoryHolder);
   // (undocumented)
@@ -160,9 +142,7 @@ export class ApiResolver implements ApiHolder {
   ): void;
 }
 
-// Warning: (ae-missing-release-tag) "AppComponents" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type AppComponents = {
   NotFoundErrorPage: ComponentType<{}>;
   BootErrorPage: ComponentType<BootErrorPageProps>;
@@ -173,23 +153,17 @@ export type AppComponents = {
   SignInPage?: ComponentType<SignInPageProps>;
 };
 
-// Warning: (ae-missing-release-tag) "AppConfigLoader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type AppConfigLoader = () => Promise<AppConfig[]>;
 
-// Warning: (ae-missing-release-tag) "AppContext" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type AppContext = {
   getPlugins(): BackstagePlugin<any, any>[];
   getSystemIcon(key: string): IconComponent | undefined;
   getComponents(): AppComponents;
 };
 
-// Warning: (ae-missing-release-tag) "AppOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type AppOptions = {
   apis?: Iterable<AnyApiFactory>;
   icons?: Partial<AppIcons> & {
@@ -205,9 +179,8 @@ export type AppOptions = {
 // Warning: (ae-forgotten-export) The symbol "PartialKeys" needs to be exported by the entry point index.d.ts
 // Warning: (ae-forgotten-export) The symbol "TargetRouteMap" needs to be exported by the entry point index.d.ts
 // Warning: (ae-forgotten-export) The symbol "KeysWithType" needs to be exported by the entry point index.d.ts
-// Warning: (ae-missing-release-tag) "AppRouteBinder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export type AppRouteBinder = <
   ExternalRoutes extends {
     [name: string]: ExternalRouteRef;
@@ -220,9 +193,7 @@ export type AppRouteBinder = <
   >,
 ) => void;
 
-// Warning: (ae-missing-release-tag) "AppThemeSelector" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class AppThemeSelector implements AppThemeApi {
   constructor(themes: AppTheme[]);
   // (undocumented)
@@ -237,9 +208,7 @@ export class AppThemeSelector implements AppThemeApi {
   setActiveThemeId(themeId?: string): void;
 }
 
-// Warning: (ae-missing-release-tag) "AtlassianAuth" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class AtlassianAuth {
   // Warning: (ae-forgotten-export) The symbol "OAuthApiCreateOptions" needs to be exported by the entry point index.d.ts
   //
@@ -252,9 +221,7 @@ export class AtlassianAuth {
   }: OAuthApiCreateOptions): typeof atlassianAuthApiRef.T;
 }
 
-// Warning: (ae-missing-release-tag) "Auth0Auth" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class Auth0Auth {
   // (undocumented)
   static create({
@@ -266,9 +233,7 @@ export class Auth0Auth {
   }: OAuthApiCreateOptions): typeof auth0AuthApiRef.T;
 }
 
-// Warning: (ae-missing-release-tag) "BackstageApp" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type BackstageApp = {
   getPlugins(): BackstagePlugin<any, any>[];
   getSystemIcon(key: string): IconComponent | undefined;
@@ -276,19 +241,20 @@ export type BackstageApp = {
   getRouter(): ComponentType<{}>;
 };
 
-// Warning: (ae-missing-release-tag) "BackstagePluginWithAnyOutput" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type BackstagePluginWithAnyOutput = Omit<
   BackstagePlugin<any, any>,
   'output'
 > & {
-  output(): (PluginOutput | UnknownPluginOutput)[];
+  output(): (
+    | PluginOutput
+    | {
+        type: string;
+      }
+  )[];
 };
 
-// Warning: (ae-missing-release-tag) "BitbucketAuth" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class BitbucketAuth {
   // (undocumented)
   static create({
@@ -300,9 +266,7 @@ export class BitbucketAuth {
   }: OAuthApiCreateOptions): typeof bitbucketAuthApiRef.T;
 }
 
-// Warning: (ae-missing-release-tag) "BitbucketSession" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type BitbucketSession = {
   providerInfo: {
     accessToken: string;
@@ -313,9 +277,7 @@ export type BitbucketSession = {
   backstageIdentity: BackstageIdentity;
 };
 
-// Warning: (ae-missing-release-tag) "BootErrorPageProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type BootErrorPageProps = {
   step: 'load-config' | 'load-chunk';
   error: Error;
@@ -324,18 +286,13 @@ export type BootErrorPageProps = {
 export { ConfigReader };
 
 // Warning: (ae-forgotten-export) The symbol "PrivateAppImpl" needs to be exported by the entry point index.d.ts
-// Warning: (ae-missing-release-tag) "createApp" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public
 export function createApp(options?: AppOptions): PrivateAppImpl;
 
-// Warning: (ae-missing-release-tag) "defaultConfigLoader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const defaultConfigLoader: AppConfigLoader;
 
-// Warning: (ae-missing-release-tag) "ErrorAlerter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class ErrorAlerter implements ErrorApi {
   constructor(alertApi: AlertApi, errorApi: ErrorApi);
@@ -352,8 +309,6 @@ export class ErrorAlerter implements ErrorApi {
   post(error: Error, context?: ErrorContext): void;
 }
 
-// Warning: (ae-missing-release-tag) "ErrorApiForwarder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class ErrorApiForwarder implements ErrorApi {
   // (undocumented)
@@ -365,23 +320,17 @@ export class ErrorApiForwarder implements ErrorApi {
   post(error: Error, context?: ErrorContext): void;
 }
 
-// Warning: (ae-missing-release-tag) "ErrorBoundaryFallbackProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type ErrorBoundaryFallbackProps = {
   plugin?: BackstagePlugin;
   error: Error;
   resetError: () => void;
 };
 
-// Warning: (ae-missing-release-tag) "FeatureFlagged" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const FeatureFlagged: (props: FeatureFlaggedProps) => JSX.Element;
 
-// Warning: (ae-missing-release-tag) "FeatureFlaggedProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type FeatureFlaggedProps = {
   children: ReactNode;
 } & (
@@ -393,15 +342,15 @@ export type FeatureFlaggedProps = {
     }
 );
 
-// Warning: (ae-forgotten-export) The symbol "FlatRoutesProps" needs to be exported by the entry point index.d.ts
-// Warning: (ae-missing-release-tag) "FlatRoutes" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const FlatRoutes: (props: FlatRoutesProps) => JSX.Element | null;
 
-// Warning: (ae-missing-release-tag) "GithubAuth" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
+export type FlatRoutesProps = {
+  children: ReactNode;
+};
+
+// @public
 export class GithubAuth implements OAuthApi, SessionApi {
   // Warning: (ae-forgotten-export) The symbol "SessionManager" needs to be exported by the entry point index.d.ts
   constructor(sessionManager: SessionManager<GithubSession>);
@@ -431,9 +380,7 @@ export class GithubAuth implements OAuthApi, SessionApi {
   signOut(): Promise<void>;
 }
 
-// Warning: (ae-missing-release-tag) "GithubSession" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type GithubSession = {
   providerInfo: {
     accessToken: string;
@@ -444,9 +391,7 @@ export type GithubSession = {
   backstageIdentity: BackstageIdentity;
 };
 
-// Warning: (ae-missing-release-tag) "GitlabAuth" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class GitlabAuth {
   // (undocumented)
   static create({
@@ -458,9 +403,7 @@ export class GitlabAuth {
   }: OAuthApiCreateOptions): typeof gitlabAuthApiRef.T;
 }
 
-// Warning: (ae-missing-release-tag) "GoogleAuth" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class GoogleAuth {
   // (undocumented)
   static create({
@@ -472,8 +415,6 @@ export class GoogleAuth {
   }: OAuthApiCreateOptions): typeof googleAuthApiRef.T;
 }
 
-// Warning: (ae-missing-release-tag) "LocalStorageFeatureFlags" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class LocalStorageFeatureFlags implements FeatureFlagsApi {
   // (undocumented)
@@ -486,9 +427,7 @@ export class LocalStorageFeatureFlags implements FeatureFlagsApi {
   save(options: FeatureFlagsSaveOptions): void;
 }
 
-// Warning: (ae-missing-release-tag) "MicrosoftAuth" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class MicrosoftAuth {
   // (undocumented)
   static create({
@@ -500,17 +439,13 @@ export class MicrosoftAuth {
   }: OAuthApiCreateOptions): typeof microsoftAuthApiRef.T;
 }
 
-// Warning: (ae-missing-release-tag) "NoOpAnalyticsApi" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class NoOpAnalyticsApi implements AnalyticsApi {
   // (undocumented)
   captureEvent(_event: AnalyticsEvent): void;
 }
 
-// Warning: (ae-missing-release-tag) "OAuth2" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class OAuth2
   implements
     OAuthApi,
@@ -519,8 +454,10 @@ export class OAuth2
     BackstageIdentityApi,
     SessionApi
 {
-  // Warning: (ae-forgotten-export) The symbol "Options" needs to be exported by the entry point index.d.ts
-  constructor(options: Options);
+  constructor(options: {
+    sessionManager: SessionManager<OAuth2Session>;
+    scopeTransform: (scopes: string[]) => string[];
+  });
   // Warning: (ae-forgotten-export) The symbol "CreateOptions" needs to be exported by the entry point index.d.ts
   //
   // (undocumented)
@@ -553,9 +490,7 @@ export class OAuth2
   signOut(): Promise<void>;
 }
 
-// Warning: (ae-missing-release-tag) "OAuth2Session" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type OAuth2Session = {
   providerInfo: {
     idToken: string;
@@ -567,8 +502,6 @@ export type OAuth2Session = {
   backstageIdentity: BackstageIdentity;
 };
 
-// Warning: (ae-missing-release-tag) "OAuthRequestManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class OAuthRequestManager implements OAuthRequestApi {
   // (undocumented)
@@ -577,9 +510,7 @@ export class OAuthRequestManager implements OAuthRequestApi {
   createAuthRequester<T>(options: AuthRequesterOptions<T>): AuthRequester<T>;
 }
 
-// Warning: (ae-missing-release-tag) "OktaAuth" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class OktaAuth {
   // (undocumented)
   static create({
@@ -591,9 +522,7 @@ export class OktaAuth {
   }: OAuthApiCreateOptions): typeof oktaAuthApiRef.T;
 }
 
-// Warning: (ae-missing-release-tag) "OneLoginAuth" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class OneLoginAuth {
   // Warning: (ae-forgotten-export) The symbol "CreateOptions" needs to be exported by the entry point index.d.ts
   //
@@ -606,9 +535,7 @@ export class OneLoginAuth {
   }: CreateOptions_2): typeof oneloginAuthApiRef.T;
 }
 
-// Warning: (ae-missing-release-tag) "SamlAuth" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class SamlAuth
   implements ProfileInfoApi, BackstageIdentityApi, SessionApi
 {
@@ -636,16 +563,12 @@ export class SamlAuth
   signOut(): Promise<void>;
 }
 
-// Warning: (ae-missing-release-tag) "SignInPageProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type SignInPageProps = {
   onResult(result: SignInResult): void;
 };
 
-// Warning: (ae-missing-release-tag) "SignInResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type SignInResult = {
   userId: string;
   profile: ProfileInfo;
@@ -653,15 +576,11 @@ export type SignInResult = {
   signOut?: () => Promise<void>;
 };
 
-// Warning: (ae-missing-release-tag) "UnhandledErrorForwarder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class UnhandledErrorForwarder {
   static forward(errorApi: ErrorApi, errorContext: ErrorContext): void;
 }
 
-// Warning: (ae-missing-release-tag) "UrlPatternDiscovery" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class UrlPatternDiscovery implements DiscoveryApi {
   static compile(pattern: string): UrlPatternDiscovery;
@@ -669,15 +588,14 @@ export class UrlPatternDiscovery implements DiscoveryApi {
   getBaseUrl(pluginId: string): Promise<string>;
 }
 
-// Warning: (ae-missing-release-tag) "WebStorage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class WebStorage implements StorageApi {
   constructor(namespace: string, errorApi: ErrorApi);
-  // Warning: (ae-forgotten-export) The symbol "CreateStorageApiOptions" needs to be exported by the entry point index.d.ts
-  //
   // (undocumented)
-  static create(options: CreateStorageApiOptions): WebStorage;
+  static create(options: {
+    errorApi: ErrorApi;
+    namespace?: string;
+  }): WebStorage;
   // (undocumented)
   forBucket(name: string): WebStorage;
   // (undocumented)
@@ -692,7 +610,6 @@ export class WebStorage implements StorageApi {
 
 // Warnings were encountered during analysis:
 //
-// src/apis/system/ApiProvider.d.ts:9:5 - (ae-forgotten-export) The symbol "ApiProviderProps" needs to be exported by the entry point index.d.ts
-// src/app/types.d.ts:89:5 - (ae-forgotten-export) The symbol "UnknownPluginOutput" needs to be exported by the entry point index.d.ts
-// src/app/types.d.ts:100:5 - (ae-forgotten-export) The symbol "AppIcons" needs to be exported by the entry point index.d.ts
+// src/apis/system/ApiProvider.d.ts:15:5 - (ae-forgotten-export) The symbol "ApiProviderProps" needs to be exported by the entry point index.d.ts
+// src/app/types.d.ts:152:5 - (ae-forgotten-export) The symbol "AppIcons" needs to be exported by the entry point index.d.ts
 ```

packages/core-app-api/src/apis/implementations/AlertApi/AlertApiForwarder.ts

@@ -20,6 +20,8 @@ import { PublishSubject } from '../../../lib/subjects';
 
 /**
  * Base implementation for the AlertApi that simply forwards alerts to consumers.
+ *
+ * @public
  */
 export class AlertApiForwarder implements AlertApi {
   private readonly subject = new PublishSubject<AlertMessage>();

packages/core-app-api/src/apis/implementations/AnalyticsApi/NoOpAnalyticsApi.ts

@@ -17,6 +17,8 @@ import { AnalyticsApi, AnalyticsEvent } from '@backstage/core-plugin-api';
 
 /**
  * Base implementation for the AnalyticsApi that does nothing.
+ *
+ * @public
  */
 export class NoOpAnalyticsApi implements AnalyticsApi {
   captureEvent(_event: AnalyticsEvent): void {}

packages/core-app-api/src/apis/implementations/AppThemeApi/AppThemeSelector.ts

@@ -20,6 +20,12 @@ import { BehaviorSubject } from '../../../lib/subjects';
 
 const STORAGE_KEY = 'theme';
 
+/**
+ * Exposes the themes installed in the app, and permits switching the currently
+ * active theme.
+ *
+ * @public
+ */
 export class AppThemeSelector implements AppThemeApi {
   static createWithStorage(themes: AppTheme[]) {
     const selector = new AppThemeSelector(themes);

packages/core-app-api/src/apis/implementations/DiscoveryApi/UrlPatternDiscovery.ts

@@ -21,6 +21,8 @@ const ERROR_PREFIX = 'Invalid discovery URL pattern,';
 /**
  * UrlPatternDiscovery is a lightweight DiscoveryApi implementation.
  * It uses a single template string to construct URLs for each plugin.
+ *
+ * @public
  */
 export class UrlPatternDiscovery implements DiscoveryApi {
   /**

packages/core-app-api/src/apis/implementations/ErrorApi/ErrorAlerter.ts

@@ -18,6 +18,8 @@ import { ErrorApi, ErrorContext, AlertApi } from '@backstage/core-plugin-api';
 /**
  * Decorates an ErrorApi by also forwarding error messages
  * to the alertApi with an 'error' severity.
+ *
+ * @public
  */
 export class ErrorAlerter implements ErrorApi {
   constructor(

packages/core-app-api/src/apis/implementations/ErrorApi/ErrorApiForwarder.ts

@@ -20,6 +20,8 @@ import { PublishSubject } from '../../../lib/subjects';
 
 /**
  * Base implementation for the ErrorApi that simply forwards errors to consumers.
+ *
+ * @public
  */
 export class ErrorApiForwarder implements ErrorApi {
   private readonly subject = new PublishSubject<{

packages/core-app-api/src/apis/implementations/ErrorApi/UnhandledErrorForwarder.ts

@@ -16,6 +16,11 @@ import { ErrorApi, ErrorContext } from '@backstage/core-plugin-api';
  * limitations under the License.
  */
 
+/**
+ * Utility class that helps with error forwarding.
+ *
+ * @public
+ */
 export class UnhandledErrorForwarder {
   /**
    * Add event listener, such that unhandled errors can be forwarded using an given `ErrorApi` instance

packages/core-app-api/src/apis/implementations/FeatureFlagsApi/LocalStorageFeatureFlags.tsx

@@ -43,7 +43,10 @@ export function validateFlagName(name: string): void {
 }
 
 /**
- * Create the FeatureFlags implementation based on the API.
+ * A feature flags implementation that stores the flags in the browser's local
+ * storage.
+ *
+ * @public
  */
 export class LocalStorageFeatureFlags implements FeatureFlagsApi {
   private registeredFeatureFlags: FeatureFlag[] = [];

packages/core-app-api/src/apis/implementations/OAuthRequestApi/OAuthRequestManager.ts

@@ -30,6 +30,8 @@ import { BehaviorSubject } from '../../../lib/subjects';
  * 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 request for each OAuth provider.
+ *
+ * @public
  */
 export class OAuthRequestManager implements OAuthRequestApi {
   private readonly subject = new BehaviorSubject<PendingAuthRequest[]>([]);

packages/core-app-api/src/apis/implementations/StorageApi/WebStorage.test.ts

@@ -13,13 +13,16 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { CreateStorageApiOptions, WebStorage } from './WebStorage';
-import { StorageApi } from '@backstage/core-plugin-api';
+import { WebStorage } from './WebStorage';
+import { ErrorApi, StorageApi } from '@backstage/core-plugin-api';
 
 describe('WebStorage Storage API', () => {
   const mockErrorApi = { post: jest.fn(), error$: jest.fn() };
   const createWebStorage = (
-    args?: Partial<CreateStorageApiOptions>,
+    args?: Partial<{
+      errorApi: ErrorApi;
+      namespace?: string;
+    }>,
   ): StorageApi => {
     return WebStorage.create({
       errorApi: mockErrorApi,

packages/core-app-api/src/apis/implementations/StorageApi/WebStorage.ts

@@ -24,18 +24,21 @@ import ObservableImpl from 'zen-observable';
 
 const buckets = new Map<string, WebStorage>();
 
-export type CreateStorageApiOptions = {
-  errorApi: ErrorApi;
-  namespace?: string;
-};
-
+/**
+ * An implementation of the storage API, that uses the browser's local storage.
+ *
+ * @public
+ */
 export class WebStorage implements StorageApi {
   constructor(
     private readonly namespace: string,
     private readonly errorApi: ErrorApi,
   ) {}
 
-  static create(options: CreateStorageApiOptions): WebStorage {
+  static create(options: {
+    errorApi: ErrorApi;
+    namespace?: string;
+  }): WebStorage {
     return new WebStorage(options.namespace ?? '', options.errorApi);
   }
 

packages/core-app-api/src/apis/implementations/auth/atlassian/AtlassianAuth.ts

@@ -25,7 +25,12 @@ const DEFAULT_PROVIDER = {
   icon: AtlassianIcon,
 };
 
-class AtlassianAuth {
+/**
+ * Implements the OAuth flow to Atlassian products.
+ *
+ * @public
+ */
+export default class AtlassianAuth {
   static create({
     discoveryApi,
     environment = 'development',
@@ -40,5 +45,3 @@ class AtlassianAuth {
     });
   }
 }
-
-export default AtlassianAuth;

packages/core-app-api/src/apis/implementations/auth/auth0/Auth0Auth.ts

@@ -25,7 +25,12 @@ const DEFAULT_PROVIDER = {
   icon: Auth0Icon,
 };
 
-class Auth0Auth {
+/**
+ * Implements the OAuth flow to Auth0 products.
+ *
+ * @public
+ */
+export default class Auth0Auth {
   static create({
     discoveryApi,
     environment = 'development',
@@ -42,5 +47,3 @@ class Auth0Auth {
     });
   }
 }
-
-export default Auth0Auth;

packages/core-app-api/src/apis/implementations/auth/bitbucket/BitbucketAuth.ts

@@ -40,7 +40,12 @@ const DEFAULT_PROVIDER = {
   icon: BitbucketIcon,
 };
 
-class BitbucketAuth {
+/**
+ * Implements the OAuth flow to Bitbucket products.
+ *
+ * @public
+ */
+export default class BitbucketAuth {
   static create({
     discoveryApi,
     environment = 'development',
@@ -57,5 +62,3 @@ class BitbucketAuth {
     });
   }
 }
-
-export default BitbucketAuth;

packages/core-app-api/src/apis/implementations/auth/bitbucket/types.ts

@@ -16,6 +16,11 @@
 
 import { ProfileInfo, BackstageIdentity } from '@backstage/core-plugin-api';
 
+/**
+ * Session information for Bitbucket auth.
+ *
+ * @public
+ */
 export type BitbucketSession = {
   providerInfo: {
     accessToken: string;

packages/core-app-api/src/apis/implementations/auth/github/GithubAuth.ts

@@ -51,7 +51,12 @@ const DEFAULT_PROVIDER = {
   icon: GithubIcon,
 };
 
-class GithubAuth implements OAuthApi, SessionApi {
+/**
+ * Implements the OAuth flow to GitHub products.
+ *
+ * @public
+ */
+export default class GithubAuth implements OAuthApi, SessionApi {
   static create({
     discoveryApi,
     environment = 'development',
@@ -158,4 +163,3 @@ class GithubAuth implements OAuthApi, SessionApi {
     return new Set(scopeList);
   }
 }
-export default GithubAuth;

packages/core-app-api/src/apis/implementations/auth/github/types.ts

@@ -16,6 +16,11 @@
 
 import { ProfileInfo, BackstageIdentity } from '@backstage/core-plugin-api';
 
+/**
+ * Session information for GitHub auth.
+ *
+ * @public
+ */
 export type GithubSession = {
   providerInfo: {
     accessToken: string;

packages/core-app-api/src/apis/implementations/auth/gitlab/GitlabAuth.ts

@@ -25,7 +25,12 @@ const DEFAULT_PROVIDER = {
   icon: GitlabIcon,
 };
 
-class GitlabAuth {
+/**
+ * Implements the OAuth flow to GitLab products.
+ *
+ * @public
+ */
+export default class GitlabAuth {
   static create({
     discoveryApi,
     environment = 'development',
@@ -42,4 +47,3 @@ class GitlabAuth {
     });
   }
 }
-export default GitlabAuth;

packages/core-app-api/src/apis/implementations/auth/google/GoogleAuth.ts

@@ -27,7 +27,12 @@ const DEFAULT_PROVIDER = {
 
 const SCOPE_PREFIX = 'https://www.googleapis.com/auth/';
 
-class GoogleAuth {
+/**
+ * Implements the OAuth flow to Google products.
+ *
+ * @public
+ */
+export default class GoogleAuth {
   static create({
     discoveryApi,
     oauthRequestApi,
@@ -65,4 +70,3 @@ class GoogleAuth {
     });
   }
 }
-export default GoogleAuth;

packages/core-app-api/src/apis/implementations/auth/microsoft/MicrosoftAuth.ts

@@ -25,7 +25,12 @@ const DEFAULT_PROVIDER = {
   icon: MicrosoftIcon,
 };
 
-class MicrosoftAuth {
+/**
+ * Implements the OAuth flow to Microsoft products.
+ *
+ * @public
+ */
+export default class MicrosoftAuth {
   static create({
     environment = 'development',
     provider = DEFAULT_PROVIDER,
@@ -48,5 +53,3 @@ class MicrosoftAuth {
     });
   }
 }
-
-export default MicrosoftAuth;

packages/core-app-api/src/apis/implementations/auth/oauth2/OAuth2.ts

@@ -33,11 +33,6 @@ import { Observable } from '@backstage/types';
 import { OAuth2Session } from './types';
 import { OAuthApiCreateOptions } from '../types';
 
-type Options = {
-  sessionManager: SessionManager<OAuth2Session>;
-  scopeTransform: (scopes: string[]) => string[];
-};
-
 type CreateOptions = OAuthApiCreateOptions & {
   scopeTransform?: (scopes: string[]) => string[];
 };
@@ -59,7 +54,12 @@ const DEFAULT_PROVIDER = {
   icon: OAuth2Icon,
 };
 
-class OAuth2
+/**
+ * Implements a generic OAuth2 flow for auth.
+ *
+ * @public
+ */
+export default class OAuth2
   implements
     OAuthApi,
     OpenIdConnectApi,
@@ -115,7 +115,10 @@ class OAuth2
   private readonly sessionManager: SessionManager<OAuth2Session>;
   private readonly scopeTransform: (scopes: string[]) => string[];
 
-  constructor(options: Options) {
+  constructor(options: {
+    sessionManager: SessionManager<OAuth2Session>;
+    scopeTransform: (scopes: string[]) => string[];
+  }) {
     this.sessionManager = options.sessionManager;
     this.scopeTransform = options.scopeTransform;
   }
@@ -176,5 +179,3 @@ class OAuth2
     return new Set(scopeTransform(scopeList));
   }
 }
-
-export default OAuth2;

packages/core-app-api/src/apis/implementations/auth/oauth2/types.ts

@@ -16,6 +16,11 @@
 
 import { ProfileInfo, BackstageIdentity } from '@backstage/core-plugin-api';
 
+/**
+ * Session information for generic OAuth2 auth.
+ *
+ * @public
+ */
 export type OAuth2Session = {
   providerInfo: {
     idToken: string;

packages/core-app-api/src/apis/implementations/auth/okta/OktaAuth.ts

@@ -37,7 +37,12 @@ const OKTA_OIDC_SCOPES: Set<String> = new Set([
 
 const OKTA_SCOPE_PREFIX: string = 'okta.';
 
-class OktaAuth {
+/**
+ * Implements the OAuth flow to Okta products.
+ *
+ * @public
+ */
+export default class OktaAuth {
   static create({
     discoveryApi,
     environment = 'development',
@@ -67,5 +72,3 @@ class OktaAuth {
     });
   }
 }
-
-export default OktaAuth;

packages/core-app-api/src/apis/implementations/auth/onelogin/OneLoginAuth.ts

@@ -26,7 +26,6 @@ import { OAuth2 } from '../oauth2';
 type CreateOptions = {
   discoveryApi: DiscoveryApi;
   oauthRequestApi: OAuthRequestApi;
-
   environment?: string;
   provider?: AuthProvider & { id: string };
 };
@@ -49,7 +48,12 @@ const OIDC_SCOPES: Set<String> = new Set([
 
 const SCOPE_PREFIX: string = 'onelogin.';
 
-class OneLoginAuth {
+/**
+ * Implements a OneLogin OAuth flow.
+ *
+ * @public
+ */
+export default class OneLoginAuth {
   static create({
     discoveryApi,
     environment = 'development',
@@ -78,5 +82,3 @@ class OneLoginAuth {
     });
   }
 }
-
-export default OneLoginAuth;

packages/core-app-api/src/apis/implementations/auth/saml/SamlAuth.ts

@@ -45,7 +45,14 @@ const DEFAULT_PROVIDER = {
   icon: SamlIcon,
 };
 
-class SamlAuth implements ProfileInfoApi, BackstageIdentityApi, SessionApi {
+/**
+ * Implements a general SAML based auth flow.
+ *
+ * @public
+ */
+export default class SamlAuth
+  implements ProfileInfoApi, BackstageIdentityApi, SessionApi
+{
   static create({
     discoveryApi,
     environment = 'development',
@@ -94,5 +101,3 @@ class SamlAuth implements ProfileInfoApi, BackstageIdentityApi, SessionApi {
     return session?.profile;
   }
 }
-
-export default SamlAuth;

packages/core-app-api/src/apis/implementations/auth/saml/types.ts

@@ -15,6 +15,11 @@
  */
 import { ProfileInfo, BackstageIdentity } from '@backstage/core-plugin-api';
 
+/**
+ * Session information for SAML auth.
+ *
+ * @public
+ */
 export type SamlSession = {
   userId: string;
   profile: ProfileInfo;

packages/core-app-api/src/apis/system/ApiFactoryRegistry.ts

@@ -44,6 +44,8 @@ type FactoryTuple = {
  *
  * Each scope has an assigned priority, where factories registered with
  * higher priority scopes override ones with lower priority.
+ *
+ * @public
  */
 export class ApiFactoryRegistry implements ApiFactoryHolder {
   private readonly factories = new Map<string, FactoryTuple>();

packages/core-app-api/src/apis/system/ApiProvider.tsx

@@ -30,10 +30,14 @@ type ApiProviderProps = {
 
 const ApiContext = createVersionedContext<{ 1: ApiHolder }>('api-context');
 
-export const ApiProvider = ({
-  apis,
-  children,
-}: PropsWithChildren<ApiProviderProps>) => {
+/**
+ * Provides an {@link @backstage/core-plugin-api#ApiHolder} for consumption in
+ * the React tree.
+ *
+ * @public
+ */
+export const ApiProvider = (props: PropsWithChildren<ApiProviderProps>) => {
+  const { apis, children } = props;
   const parentHolder = useContext(ApiContext)?.atVersion(1);
   const holder = parentHolder ? new ApiAggregator(apis, parentHolder) : apis;
 

packages/core-app-api/src/apis/system/ApiRegistry.ts

@@ -32,11 +32,21 @@ class ApiRegistryBuilder {
   }
 }
 
+/**
+ * A registry for utility APIs.
+ *
+ * @public
+ */
 export class ApiRegistry implements ApiHolder {
   static builder() {
     return new ApiRegistryBuilder();
   }
 
+  /**
+   * Creates a new ApiRegistry with a list of API implementations.
+   *
+   * @param apis - A list of pairs mapping an ApiRef to its respective implementation
+   */
   static from(apis: ApiImpl[]) {
     return new ApiRegistry(new Map(apis.map(([api, impl]) => [api.id, impl])));
   }
@@ -44,8 +54,8 @@ export class ApiRegistry implements ApiHolder {
   /**
    * Creates a new ApiRegistry with a single API implementation.
    *
-   * @param api ApiRef for the API to add
-   * @param impl Implementation of the API to add
+   * @param api - ApiRef for the API to add
+   * @param impl - Implementation of the API to add
    */
   static with<T>(api: ApiRef<T>, impl: T): ApiRegistry {
     return new ApiRegistry(new Map([[api.id, impl]]));
@@ -56,8 +66,8 @@ export class ApiRegistry implements ApiHolder {
   /**
    * Returns a new ApiRegistry with the provided API added to the existing ones.
    *
-   * @param api ApiRef for the API to add
-   * @param impl Implementation of the API to add
+   * @param api - ApiRef for the API to add
+   * @param impl - Implementation of the API to add
    */
   with<T>(api: ApiRef<T>, impl: T): ApiRegistry {
     return new ApiRegistry(new Map([...this.apis, [api.id, impl]]));

packages/core-app-api/src/apis/system/ApiResolver.ts

@@ -22,6 +22,12 @@ import {
 } from '@backstage/core-plugin-api';
 import { ApiFactoryHolder } from './types';
 
+/**
+ * Handles the actual on-demand instantiation and memoization of APIs out of
+ * an {@link ApiFactoryHolder}.
+ *
+ * @public
+ */
 export class ApiResolver implements ApiHolder {
   /**
    * Validate factories by making sure that each of the apis can be created

packages/core-app-api/src/apis/system/types.ts

@@ -16,6 +16,9 @@
 
 import { ApiFactory, ApiRef } from '@backstage/core-plugin-api';
 
+/**
+ * @public
+ */
 export type ApiFactoryHolder = {
   get<T>(
     api: ApiRef<T>,

packages/core-app-api/src/app/createApp.tsx

@@ -48,6 +48,8 @@ import { BackstagePlugin } from '@backstage/core-plugin-api';
  * which can be rewritten at runtime to contain an additional JSON config object.
  * If runtime config is present, it will be placed first in the config array, overriding
  * other config values.
+ *
+ * @public
  */
 export const defaultConfigLoader: AppConfigLoader = async (
   // This string may be replaced at runtime to provide additional config.
@@ -100,6 +102,8 @@ export function OptionallyWrapInRouter({ children }: PropsWithChildren<{}>) {
 
 /**
  * Creates a new Backstage App.
+ *
+ * @public
  */
 export function createApp(options?: AppOptions) {
   const DefaultNotFoundPage = () => (

packages/core-app-api/src/app/types.ts

@@ -29,11 +29,21 @@ import {
 import { AppConfig } from '@backstage/config';
 import { AppIcons } from './icons';
 
+/**
+ * Props for the `BootErrorPage` component of {@link AppComponents}.
+ *
+ * @public
+ */
 export type BootErrorPageProps = {
   step: 'load-config' | 'load-chunk';
   error: Error;
 };
 
+/**
+ * The outcome of signing in on the sign-in page.
+ *
+ * @public
+ */
 export type SignInResult = {
   /**
    * User ID that will be returned by the IdentityApi
@@ -53,6 +63,11 @@ export type SignInResult = {
   signOut?: () => Promise<void>;
 };
 
+/**
+ * Props for the `SignInPage` component of {@link AppComponents}.
+ *
+ * @public
+ */
 export type SignInPageProps = {
   /**
    * Set the sign-in result for the app. This should only be called once.
@@ -60,12 +75,22 @@ export type SignInPageProps = {
   onResult(result: SignInResult): void;
 };
 
+/**
+ * Props for the fallback error boundary.
+ *
+ * @public
+ */
 export type ErrorBoundaryFallbackProps = {
   plugin?: BackstagePlugin;
   error: Error;
   resetError: () => void;
 };
 
+/**
+ * A set of replaceable core components that are part of every Backstage app.
+ *
+ * @public
+ */
 export type AppComponents = {
   NotFoundErrorPage: ComponentType<{}>;
   BootErrorPage: ComponentType<BootErrorPageProps>;
@@ -91,6 +116,8 @@ export type AppComponents = {
  *
  * If multiple config objects are returned in the array, values in the earlier configs
  * will override later ones.
+ *
+ * @public
  */
 export type AppConfigLoader = () => Promise<AppConfig[]>;
 
@@ -123,6 +150,12 @@ type TargetRouteMap<
     : never;
 };
 
+/**
+ * A function that can bind from external routes of a given plugin, to concrete
+ * routes of other plugins. See {@link createApp}.
+ *
+ * @public
+ */
 export type AppRouteBinder = <
   ExternalRoutes extends { [name: string]: ExternalRouteRef },
 >(
@@ -133,21 +166,33 @@ export type AppRouteBinder = <
   >,
 ) => void;
 
-// Output from newer or older plugin API versions that might not be supported by
-// this version of the app API, but we don't want to break at the type checking level.
-// We only use this more permissive type for the `createApp` options, as we otherwise
-// want to stick to using the type for the outputs that we know about in this version
-// of the app api.
-type UnknownPluginOutput = {
-  type: string;
-};
+/**
+ * Internal helper type that represents a plugin with any type of output.
+ *
+ * @public
+ * @remarks
+ *
+ * The `type: string` type is there to handle output from newer or older plugin
+ * API versions that might not be supported by this version of the app API, but
+ * we don't want to break at the type checking level. We only use this more
+ * permissive type for the `createApp` options, as we otherwise want to stick
+ * to using the type for the outputs that we know about in this version of the
+ * app api.
+ *
+ * TODO(freben): This should be marked internal but that's not supported by the api report generation tools yet
+ */
 export type BackstagePluginWithAnyOutput = Omit<
   BackstagePlugin<any, any>,
   'output'
 > & {
-  output(): (PluginOutput | UnknownPluginOutput)[];
+  output(): (PluginOutput | { type: string })[];
 };
 
+/**
+ * The options accepted by {@link createApp}.
+ *
+ * @public
+ */
 export type AppOptions = {
   /**
    * A collection of ApiFactories to register in the application to either
@@ -226,6 +271,11 @@ export type AppOptions = {
   bindRoutes?(context: { bind: AppRouteBinder }): void;
 };
 
+/**
+ * The public API of the output of {@link createApp}.
+ *
+ * @public
+ */
 export type BackstageApp = {
   /**
    * Returns all plugins registered for the app.
@@ -250,6 +300,12 @@ export type BackstageApp = {
   getRouter(): ComponentType<{}>;
 };
 
+/**
+ * The central context providing runtime app specific state that plugin views
+ * want to consume.
+ *
+ * @public
+ */
 export type AppContext = {
   /**
    * Get a list of all plugins that are installed in the app.

packages/core-app-api/src/routing/FeatureFlagged.tsx

@@ -21,11 +21,22 @@ import {
 } from '@backstage/core-plugin-api';
 import React, { ReactNode } from 'react';
 
+/**
+ * Props for the {@link FeatureFlagged} component.
+ *
+ * @public
+ */
 export type FeatureFlaggedProps = { children: ReactNode } & (
   | { with: string }
   | { without: string }
 );
 
+/**
+ * Enables or disables rendering of its children based on the state of a given
+ * feature flag.
+ *
+ * @public
+ */
 export const FeatureFlagged = (props: FeatureFlaggedProps) => {
   const { children } = props;
   const featureFlagApi = useApi(featureFlagsApiRef);

packages/core-app-api/src/routing/FlatRoutes.tsx

@@ -24,10 +24,26 @@ type RouteObject = {
   children?: RouteObject[];
 };
 
-type FlatRoutesProps = {
+/**
+ * Props for the {@link FlatRoutes} component.
+ *
+ * @public
+ */
+export type FlatRoutesProps = {
   children: ReactNode;
 };
 
+/**
+ * A wrapper around a set of routes.
+ *
+ * @remarks
+ *
+ * The root of the routing hierarchy in your app should use this component,
+ * instead of the one from `react-router-dom`. This ensures that all of the
+ * plugin route and utility API wiring happens under the hood.
+ *
+ * @public
+ */
 export const FlatRoutes = (props: FlatRoutesProps): JSX.Element | null => {
   const app = useApp();
   const { NotFoundErrorPage } = app.getComponents();

packages/core-app-api/src/routing/index.ts

@@ -15,5 +15,6 @@
  */
 
 export { FlatRoutes } from './FlatRoutes';
+export type { FlatRoutesProps } from './FlatRoutes';
 export { FeatureFlagged } from './FeatureFlagged';
 export type { FeatureFlaggedProps } from './FeatureFlagged';