more api fixes, in integration and theme

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

.changeset/lazy-dodos-drum.md

@@ -0,0 +1,6 @@
+---
+'@backstage/integration': patch
+'@backstage/theme': patch
+---
+
+More API fixes: mark things public, add docs, fix exports

packages/integration/api-report.md

@@ -6,15 +6,11 @@
 import { Config } from '@backstage/config';
 import { RestEndpointMethodTypes } from '@octokit/rest';
 
-// Warning: (ae-missing-release-tag) "AwsS3Integration" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class AwsS3Integration implements ScmIntegration {
   constructor(integrationConfig: AwsS3IntegrationConfig);
   // (undocumented)
   get config(): AwsS3IntegrationConfig;
-  // Warning: (ae-forgotten-export) The symbol "ScmIntegrationsFactory" needs to be exported by the entry point index.d.ts
-  //
   // (undocumented)
   static factory: ScmIntegrationsFactory<AwsS3Integration>;
   // (undocumented)
@@ -31,8 +27,6 @@ export class AwsS3Integration implements ScmIntegration {
   get type(): string;
 }
 
-// Warning: (ae-missing-release-tag) "AwsS3IntegrationConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type AwsS3IntegrationConfig = {
   host: string;
@@ -41,9 +35,7 @@ export type AwsS3IntegrationConfig = {
   roleArn?: string;
 };
 
-// Warning: (ae-missing-release-tag) "AzureIntegration" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class AzureIntegration implements ScmIntegration {
   constructor(integrationConfig: AzureIntegrationConfig);
   // (undocumented)
@@ -64,17 +56,13 @@ export class AzureIntegration implements ScmIntegration {
   get type(): string;
 }
 
-// Warning: (ae-missing-release-tag) "AzureIntegrationConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type AzureIntegrationConfig = {
   host: string;
   token?: string;
 };
 
-// Warning: (ae-missing-release-tag) "BitbucketIntegration" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class BitbucketIntegration implements ScmIntegration {
   constructor(integrationConfig: BitbucketIntegrationConfig);
   // (undocumented)
@@ -95,8 +83,6 @@ export class BitbucketIntegration implements ScmIntegration {
   get type(): string;
 }
 
-// Warning: (ae-missing-release-tag) "BitbucketIntegrationConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type BitbucketIntegrationConfig = {
   host: string;
@@ -106,8 +92,6 @@ export type BitbucketIntegrationConfig = {
   appPassword?: string;
 };
 
-// Warning: (ae-missing-release-tag) "defaultScmResolveUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function defaultScmResolveUrl(options: {
   url: string;
@@ -115,92 +99,44 @@ export function defaultScmResolveUrl(options: {
   lineNumber?: number;
 }): string;
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "getAzureCommitsUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getAzureCommitsUrl(url: string): string;
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "getAzureDownloadUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getAzureDownloadUrl(url: string): string;
 
-// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "getAzureFileFetchUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getAzureFileFetchUrl(url: string): string;
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "getAzureRequestOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getAzureRequestOptions(
   config: AzureIntegrationConfig,
   additionalHeaders?: Record<string, string>,
 ): RequestInit;
 
-// 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
-// Warning: (ae-missing-release-tag) "getBitbucketDefaultBranch" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getBitbucketDefaultBranch(
   url: string,
   config: BitbucketIntegrationConfig,
 ): Promise<string>;
 
-// 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
-// Warning: (ae-missing-release-tag) "getBitbucketDownloadUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getBitbucketDownloadUrl(
   url: string,
   config: BitbucketIntegrationConfig,
 ): Promise<string>;
 
-// 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
-// Warning: (ae-missing-release-tag) "getBitbucketFileFetchUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getBitbucketFileFetchUrl(
   url: string,
   config: BitbucketIntegrationConfig,
 ): string;
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "getBitbucketRequestOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getBitbucketRequestOptions(
   config: BitbucketIntegrationConfig,
 ): RequestInit;
 
-// 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
-// Warning: (ae-forgotten-export) The symbol "GithubCredentials" needs to be exported by the entry point index.d.ts
-// Warning: (ae-missing-release-tag) "getGitHubFileFetchUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getGitHubFileFetchUrl(
   url: string,
@@ -208,36 +144,34 @@ export function getGitHubFileFetchUrl(
   credentials: GithubCredentials,
 ): string;
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "getGitHubRequestOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public @deprecated
 export function getGitHubRequestOptions(
   config: GitHubIntegrationConfig,
   credentials: GithubCredentials,
 ): RequestInit;
 
-// 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
-// Warning: (ae-missing-release-tag) "getGitLabFileFetchUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getGitLabFileFetchUrl(
   url: string,
   config: GitLabIntegrationConfig,
 ): Promise<string>;
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "getGitLabRequestOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getGitLabRequestOptions(
   config: GitLabIntegrationConfig,
 ): RequestInit;
 
-// Warning: (ae-missing-release-tag) "GithubAppCredentialsMux" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
+export type GithubAppConfig = {
+  appId: number;
+  privateKey: string;
+  webhookSecret: string;
+  clientId: string;
+  clientSecret: string;
+  allowedInstallationOwners?: string[];
+};
+
+// @public
 export class GithubAppCredentialsMux {
   constructor(config: GitHubIntegrationConfig);
   // (undocumented)
@@ -248,33 +182,26 @@ export class GithubAppCredentialsMux {
   getAppToken(owner: string, repo?: string): Promise<string | undefined>;
 }
 
-// Warning: (ae-missing-release-tag) "GithubCredentialsProvider" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
+export type GithubCredentials = {
+  headers?: {
+    [name: string]: string;
+  };
+  token?: string;
+  type: GithubCredentialType;
+};
+
+// @public
 export class GithubCredentialsProvider {
   // (undocumented)
   static create(config: GitHubIntegrationConfig): GithubCredentialsProvider;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-  // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-  // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-  // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-  // Warning: (tsdoc-undefined-tag) The TSDoc tag "@type" is not defined in this configuration
-  // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-  // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-  // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-  // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
   getCredentials(opts: { url: string }): Promise<GithubCredentials>;
 }
 
-// Warning: (ae-missing-release-tag) "GithubCredentialType" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type GithubCredentialType = 'app' | 'token';
 
-// Warning: (ae-missing-release-tag) "GitHubIntegration" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class GitHubIntegration implements ScmIntegration {
   constructor(integrationConfig: GitHubIntegrationConfig);
   // (undocumented)
@@ -295,8 +222,6 @@ export class GitHubIntegration implements ScmIntegration {
   get type(): string;
 }
 
-// Warning: (ae-missing-release-tag) "GitHubIntegrationConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type GitHubIntegrationConfig = {
   host: string;
@@ -306,9 +231,7 @@ export type GitHubIntegrationConfig = {
   apps?: GithubAppConfig[];
 };
 
-// Warning: (ae-missing-release-tag) "GitLabIntegration" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class GitLabIntegration implements ScmIntegration {
   constructor(integrationConfig: GitLabIntegrationConfig);
   // (undocumented)
@@ -329,8 +252,6 @@ export class GitLabIntegration implements ScmIntegration {
   get type(): string;
 }
 
-// Warning: (ae-missing-release-tag) "GitLabIntegrationConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type GitLabIntegrationConfig = {
   host: string;
@@ -339,114 +260,89 @@ export type GitLabIntegrationConfig = {
   baseUrl: string;
 };
 
-// Warning: (ae-missing-release-tag) "GoogleGcsIntegrationConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type GoogleGcsIntegrationConfig = {
   clientEmail?: string;
   privateKey?: string;
 };
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "readAwsS3IntegrationConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
+// @public
+export interface IntegrationsByType {
+  // (undocumented)
+  awsS3: ScmIntegrationsGroup<AwsS3Integration>;
+  // (undocumented)
+  azure: ScmIntegrationsGroup<AzureIntegration>;
+  // (undocumented)
+  bitbucket: ScmIntegrationsGroup<BitbucketIntegration>;
+  // (undocumented)
+  github: ScmIntegrationsGroup<GitHubIntegration>;
+  // (undocumented)
+  gitlab: ScmIntegrationsGroup<GitLabIntegration>;
+}
+
 // @public
 export function readAwsS3IntegrationConfig(
   config: Config,
 ): AwsS3IntegrationConfig;
 
-// Warning: (ae-missing-release-tag) "readAwsS3IntegrationConfigs" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export function readAwsS3IntegrationConfigs(
   configs: Config[],
 ): AwsS3IntegrationConfig[];
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "readAzureIntegrationConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function readAzureIntegrationConfig(
   config: Config,
 ): AzureIntegrationConfig;
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "readAzureIntegrationConfigs" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function readAzureIntegrationConfigs(
   configs: Config[],
 ): AzureIntegrationConfig[];
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "readBitbucketIntegrationConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function readBitbucketIntegrationConfig(
   config: Config,
 ): BitbucketIntegrationConfig;
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "readBitbucketIntegrationConfigs" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function readBitbucketIntegrationConfigs(
   configs: Config[],
 ): BitbucketIntegrationConfig[];
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "readGitHubIntegrationConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function readGitHubIntegrationConfig(
   config: Config,
 ): GitHubIntegrationConfig;
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "readGitHubIntegrationConfigs" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function readGitHubIntegrationConfigs(
   configs: Config[],
 ): GitHubIntegrationConfig[];
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "readGitLabIntegrationConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function readGitLabIntegrationConfig(
   config: Config,
 ): GitLabIntegrationConfig;
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "readGitLabIntegrationConfigs" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function readGitLabIntegrationConfigs(
   configs: Config[],
 ): GitLabIntegrationConfig[];
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "readGoogleGcsIntegrationConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function readGoogleGcsIntegrationConfig(
   config: Config,
 ): GoogleGcsIntegrationConfig;
 
-// Warning: (ae-missing-release-tag) "replaceUrlType" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export function replaceGitHubUrlType(
   url: string,
   type: 'blob' | 'tree' | 'edit',
 ): string;
 
-// Warning: (ae-missing-release-tag) "ScmIntegration" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export interface ScmIntegration {
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   resolveEditUrl(url: string): string;
   // Warning: (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters
   // Warning: (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters
@@ -460,8 +356,6 @@ export interface ScmIntegration {
   type: string;
 }
 
-// Warning: (ae-missing-release-tag) "ScmIntegrationRegistry" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export interface ScmIntegrationRegistry
   extends ScmIntegrationsGroup<ScmIntegration> {
@@ -475,7 +369,6 @@ export interface ScmIntegrationRegistry
   github: ScmIntegrationsGroup<GitHubIntegration>;
   // (undocumented)
   gitlab: ScmIntegrationsGroup<GitLabIntegration>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   resolveEditUrl(url: string): string;
   // Warning: (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters
   // Warning: (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters
@@ -487,11 +380,8 @@ export interface ScmIntegrationRegistry
   }): string;
 }
 
-// Warning: (ae-missing-release-tag) "ScmIntegrations" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class ScmIntegrations implements ScmIntegrationRegistry {
-  // Warning: (ae-forgotten-export) The symbol "IntegrationsByType" needs to be exported by the entry point index.d.ts
   constructor(integrationsByType: IntegrationsByType);
   // (undocumented)
   get awsS3(): ScmIntegrationsGroup<AwsS3Integration>;
@@ -521,20 +411,20 @@ export class ScmIntegrations implements ScmIntegrationRegistry {
   }): string;
 }
 
-// Warning: (ae-missing-release-tag) "ScmIntegrationsGroup" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
+// @public
+export type ScmIntegrationsFactory<T extends ScmIntegration> = (options: {
+  config: Config;
+}) => ScmIntegrationsGroup<T>;
+
 // @public
 export interface ScmIntegrationsGroup<T extends ScmIntegration> {
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   byHost(host: string): T | undefined;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   byUrl(url: string | URL): T | undefined;
   list(): T[];
 }
 
 // Warnings were encountered during analysis:
 //
-// src/github/config.d.ts:41:5 - (ae-forgotten-export) The symbol "GithubAppConfig" needs to be exported by the entry point index.d.ts
-// src/gitlab/config.d.ts:27:68 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-// src/gitlab/config.d.ts:27:63 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+// src/gitlab/config.d.ts:29:68 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+// src/gitlab/config.d.ts:29:63 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
 ```

packages/integration/src/ScmIntegrations.ts

@@ -24,14 +24,24 @@ import { defaultScmResolveUrl } from './helpers';
 import { ScmIntegration, ScmIntegrationsGroup } from './types';
 import { ScmIntegrationRegistry } from './registry';
 
-type IntegrationsByType = {
+/**
+ * The set of supported integrations.
+ *
+ * @public
+ */
+export interface IntegrationsByType {
   awsS3: ScmIntegrationsGroup<AwsS3Integration>;
   azure: ScmIntegrationsGroup<AzureIntegration>;
   bitbucket: ScmIntegrationsGroup<BitbucketIntegration>;
   github: ScmIntegrationsGroup<GitHubIntegration>;
   gitlab: ScmIntegrationsGroup<GitLabIntegration>;
-};
+}
 
+/**
+ * Exposes the set of supported integrations.
+ *
+ * @public
+ */
 export class ScmIntegrations implements ScmIntegrationRegistry {
   private readonly byType: IntegrationsByType;
 

packages/integration/src/awsS3/AwsS3Integration.ts

@@ -18,6 +18,11 @@ import { basicIntegrations, defaultScmResolveUrl } from '../helpers';
 import { ScmIntegration, ScmIntegrationsFactory } from '../types';
 import { AwsS3IntegrationConfig, readAwsS3IntegrationConfigs } from './config';
 
+/**
+ * Integrates with AWS S3 or compatible solutions.
+ *
+ * @public
+ */
 export class AwsS3Integration implements ScmIntegration {
   static factory: ScmIntegrationsFactory<AwsS3Integration> = ({ config }) => {
     const configs = readAwsS3IntegrationConfigs(
@@ -42,6 +47,7 @@ export class AwsS3Integration implements ScmIntegration {
   }
 
   constructor(private readonly integrationConfig: AwsS3IntegrationConfig) {}
+
   resolveUrl(options: {
     url: string;
     base: string;

packages/integration/src/awsS3/config.ts

@@ -21,8 +21,9 @@ const AMAZON_AWS_HOST = 'amazonaws.com';
 
 /**
  * The configuration parameters for a single AWS S3 provider.
+ *
+ * @public
  */
-
 export type AwsS3IntegrationConfig = {
   /**
    * The host of the target that this matches on, e.g. "amazonaws.com"
@@ -50,7 +51,8 @@ export type AwsS3IntegrationConfig = {
 /**
  * Reads a single Aws S3 integration config.
  *
- * @param config The config object of a single integration
+ * @param config - The config object of a single integration
+ * @public
  */
 
 export function readAwsS3IntegrationConfig(
@@ -70,6 +72,13 @@ export function readAwsS3IntegrationConfig(
   return { host, accessKeyId, secretAccessKey, roleArn };
 }
 
+/**
+ * Reads a set of AWS S3 integration configs, and inserts some defaults for
+ * public Amazon AWS if not specified.
+ *
+ * @param configs - The config objects of the integrations
+ * @public
+ */
 export function readAwsS3IntegrationConfigs(
   configs: Config[],
 ): AwsS3IntegrationConfig[] {

packages/integration/src/azure/AzureIntegration.ts

@@ -19,6 +19,11 @@ import { ScmIntegration, ScmIntegrationsFactory } from '../types';
 import { AzureUrl } from './AzureUrl';
 import { AzureIntegrationConfig, readAzureIntegrationConfigs } from './config';
 
+/**
+ * Microsoft Azure based integration.
+ *
+ * @public
+ */
 export class AzureIntegration implements ScmIntegration {
   static factory: ScmIntegrationsFactory<AzureIntegration> = ({ config }) => {
     const configs = readAzureIntegrationConfigs(

packages/integration/src/azure/config.ts

@@ -21,6 +21,8 @@ const AZURE_HOST = 'dev.azure.com';
 
 /**
  * The configuration parameters for a single Azure provider.
+ *
+ * @public
  */
 export type AzureIntegrationConfig = {
   /**
@@ -41,7 +43,8 @@ export type AzureIntegrationConfig = {
 /**
  * Reads a single Azure integration config.
  *
- * @param config The config object of a single integration
+ * @param config - The config object of a single integration
+ * @public
  */
 export function readAzureIntegrationConfig(
   config: Config,
@@ -62,7 +65,8 @@ export function readAzureIntegrationConfig(
  * Reads a set of Azure integration configs, and inserts some defaults for
  * public Azure if not specified.
  *
- * @param configs All of the integration config objects
+ * @param configs - All of the integration config objects
+ * @public
  */
 export function readAzureIntegrationConfigs(
   configs: Config[],

packages/integration/src/azure/core.ts

@@ -21,11 +21,14 @@ import { AzureIntegrationConfig } from './config';
  * Given a URL pointing to a file on a provider, returns a URL that is suitable
  * for fetching the contents of the data.
  *
- * Converts
- * from: https://dev.azure.com/{organization}/{project}/_git/reponame?path={path}&version=GB{commitOrBranch}&_a=contents
- * to:   https://dev.azure.com/{organization}/{project}/_apis/git/repositories/reponame/items?path={path}&version={commitOrBranch}
+ * @remarks
  *
- * @param url A URL pointing to a file
+ * Converts
+ * - from: `https://dev.azure.com/{organization}/{project}/_git/reponame?path={path}&version=GB{commitOrBranch}&_a=contents`
+ * - to:   `https://dev.azure.com/{organization}/{project}/_apis/git/repositories/reponame/items?path={path}&version={commitOrBranch}`
+ *
+ * @param url - A URL pointing to a file
+ * @public
  */
 export function getAzureFileFetchUrl(url: string): string {
   return AzureUrl.fromRepoUrl(url).toFileUrl();
@@ -35,7 +38,8 @@ export function getAzureFileFetchUrl(url: string): string {
  * Given a URL pointing to a path on a provider, returns a URL that is suitable
  * for downloading the subtree.
  *
- * @param url A URL pointing to a path
+ * @param url - A URL pointing to a path
+ * @public
  */
 export function getAzureDownloadUrl(url: string): string {
   return AzureUrl.fromRepoUrl(url).toArchiveUrl();
@@ -44,7 +48,8 @@ export function getAzureDownloadUrl(url: string): string {
 /**
  * Given a URL, return the API URL to fetch commits on the branch.
  *
- * @param url A URL pointing to a repository or a sub-path
+ * @param url - A URL pointing to a repository or a sub-path
+ * @public
  */
 export function getAzureCommitsUrl(url: string): string {
   return AzureUrl.fromRepoUrl(url).toCommitsUrl();
@@ -53,7 +58,8 @@ export function getAzureCommitsUrl(url: string): string {
 /**
  * Gets the request options necessary to make requests to a given provider.
  *
- * @param config The relevant provider config
+ * @param config - The relevant provider config
+ * @public
  */
 export function getAzureRequestOptions(
   config: AzureIntegrationConfig,

packages/integration/src/bitbucket/BitbucketIntegration.ts

@@ -22,6 +22,11 @@ import {
   readBitbucketIntegrationConfigs,
 } from './config';
 
+/**
+ * A Bitbucket based integration.
+ *
+ * @public
+ */
 export class BitbucketIntegration implements ScmIntegration {
   static factory: ScmIntegrationsFactory<BitbucketIntegration> = ({
     config,

packages/integration/src/bitbucket/config.ts

@@ -23,6 +23,8 @@ const BITBUCKET_API_BASE_URL = 'https://api.bitbucket.org/2.0';
 
 /**
  * The configuration parameters for a single Bitbucket API provider.
+ *
+ * @public
  */
 export type BitbucketIntegrationConfig = {
   /**
@@ -66,7 +68,8 @@ export type BitbucketIntegrationConfig = {
 /**
  * Reads a single Bitbucket integration config.
  *
- * @param config The config object of a single integration
+ * @param config - The config object of a single integration
+ * @public
  */
 export function readBitbucketIntegrationConfig(
   config: Config,
@@ -102,7 +105,8 @@ export function readBitbucketIntegrationConfig(
  * Reads a set of Bitbucket integration configs, and inserts some defaults for
  * public Bitbucket if not specified.
  *
- * @param configs All of the integration config objects
+ * @param configs - All of the integration config objects
+ * @public
  */
 export function readBitbucketIntegrationConfigs(
   configs: Config[],

packages/integration/src/bitbucket/core.ts

@@ -21,8 +21,9 @@ import { BitbucketIntegrationConfig } from './config';
 /**
  * Given a URL pointing to a path on a provider, returns the default branch.
  *
- * @param url A URL pointing to a path
- * @param config The relevant provider config
+ * @param url - A URL pointing to a path
+ * @param config - The relevant provider config
+ * @public
  */
 export async function getBitbucketDefaultBranch(
   url: string,
@@ -71,8 +72,9 @@ export async function getBitbucketDefaultBranch(
  * Given a URL pointing to a path on a provider, returns a URL that is suitable
  * for downloading the subtree.
  *
- * @param url A URL pointing to a path
- * @param config The relevant provider config
+ * @param url - A URL pointing to a path
+ * @param config - The relevant provider config
+ * @public
  */
 export async function getBitbucketDownloadUrl(
   url: string,
@@ -108,12 +110,15 @@ export async function getBitbucketDownloadUrl(
  * Given a URL pointing to a file on a provider, returns a URL that is suitable
  * for fetching the contents of the data.
  *
+ * @remarks
+ *
  * Converts
  * from: https://bitbucket.org/orgname/reponame/src/master/file.yaml
  * to:   https://api.bitbucket.org/2.0/repositories/orgname/reponame/src/master/file.yaml
  *
- * @param url A URL pointing to a file
- * @param config The relevant provider config
+ * @param url - A URL pointing to a file
+ * @param config - The relevant provider config
+ * @public
  */
 export function getBitbucketFileFetchUrl(
   url: string,
@@ -148,7 +153,8 @@ export function getBitbucketFileFetchUrl(
 /**
  * Gets the request options necessary to make requests to a given provider.
  *
- * @param config The relevant provider config
+ * @param config - The relevant provider config
+ * @public
  */
 export function getBitbucketRequestOptions(
   config: BitbucketIntegrationConfig,

packages/integration/src/github/GitHubIntegration.test.ts

@@ -15,7 +15,7 @@
  */
 
 import { ConfigReader } from '@backstage/config';
-import { GitHubIntegration, replaceUrlType } from './GitHubIntegration';
+import { GitHubIntegration, replaceGitHubUrlType } from './GitHubIntegration';
 
 describe('GitHubIntegration', () => {
   it('has a working factory', () => {
@@ -80,25 +80,28 @@ describe('GitHubIntegration', () => {
   });
 });
 
-describe('replaceUrlType', () => {
+describe('replaceGitHubUrlType', () => {
   it('should replace with expected type', () => {
     expect(
-      replaceUrlType(
+      replaceGitHubUrlType(
         'https://github.com/backstage/backstage/blob/master/README.md',
         'edit',
       ),
     ).toBe('https://github.com/backstage/backstage/edit/master/README.md');
     expect(
-      replaceUrlType(
+      replaceGitHubUrlType(
         'https://github.com/webmodules/blob/blob/master/test',
         'tree',
       ),
     ).toBe('https://github.com/webmodules/blob/tree/master/test');
     expect(
-      replaceUrlType('https://github.com/blob/blob/blob/master/test', 'tree'),
+      replaceGitHubUrlType(
+        'https://github.com/blob/blob/blob/master/test',
+        'tree',
+      ),
     ).toBe('https://github.com/blob/blob/tree/master/test');
     expect(
-      replaceUrlType(
+      replaceGitHubUrlType(
         'https://github.com/backstage/backstage/edit/tree/README.md',
         'blob',
       ),

packages/integration/src/github/GitHubIntegration.ts

@@ -21,6 +21,11 @@ import {
   readGitHubIntegrationConfigs,
 } from './config';
 
+/**
+ * A GitHub based integration.
+ *
+ * @public
+ */
 export class GitHubIntegration implements ScmIntegration {
   static factory: ScmIntegrationsFactory<GitHubIntegration> = ({ config }) => {
     const configs = readGitHubIntegrationConfigs(
@@ -54,15 +59,22 @@ export class GitHubIntegration implements ScmIntegration {
     // GitHub uses blob URLs for files and tree urls for directory listings. But
     // there is a redirect from tree to blob for files, so we can always return
     // tree urls here.
-    return replaceUrlType(defaultScmResolveUrl(options), 'tree');
+    return replaceGitHubUrlType(defaultScmResolveUrl(options), 'tree');
   }
 
   resolveEditUrl(url: string): string {
-    return replaceUrlType(url, 'edit');
+    return replaceGitHubUrlType(url, 'edit');
   }
 }
 
-export function replaceUrlType(
+/**
+ * Takes a GitHub URL and replaces the type part (blob, tree etc).
+ *
+ * @param url - The original URL
+ * @param type - The desired type, e.g. "blob"
+ * @public
+ */
+export function replaceGitHubUrlType(
   url: string,
   type: 'blob' | 'tree' | 'edit',
 ): string {

packages/integration/src/github/GithubCredentialsProvider.ts

@@ -159,7 +159,11 @@ class GithubAppManager {
   }
 }
 
-// GithubAppCredentialsMux corresponds to a Github installation which internally could hold several GitHub Apps.
+/**
+ * Corresponds to a Github installation which internally could hold several GitHub Apps.
+ *
+ * @public
+ */
 export class GithubAppCredentialsMux {
   private readonly apps: GithubAppManager[];
 
@@ -211,15 +215,32 @@ export class GithubAppCredentialsMux {
   }
 }
 
+/**
+ * The type of credentials produced by the credential provider.
+ *
+ * @public
+ */
 export type GithubCredentialType = 'app' | 'token';
 
+/**
+ * A set of credentials information for a GitHub integration.
+ *
+ * @public
+ */
 export type GithubCredentials = {
   headers?: { [name: string]: string };
   token?: string;
   type: GithubCredentialType;
 };
 
-// TODO: Possibly move this to a backend only package so that it's not used in the frontend by mistake
+/**
+ * Handles the creation and caching of credentials for GitHub integrations.
+ *
+ * @public
+ * @remarks
+ *
+ * TODO: Possibly move this to a backend only package so that it's not used in the frontend by mistake
+ */
 export class GithubCredentialsProvider {
   static create(config: GitHubIntegrationConfig): GithubCredentialsProvider {
     return new GithubCredentialsProvider(
@@ -234,13 +255,24 @@ export class GithubCredentialsProvider {
   ) {}
 
   /**
-   * Returns GithubCredentials for requested url.
-   * Consecutive calls to this method with the same url will return cached credentials.
+   * Returns {@link GithubCredentials} for a given URL.
+   *
+   * @remarks
+   *
+   * Consecutive calls to this method with the same URL will return cached
+   * credentials.
+   *
    * The shortest lifetime for a token returned is 10 minutes.
-   * @param opts containing the organization or repository url
-   * @returns {Promise} of @type {GithubCredentials}.
+   *
    * @example
-   * const { token, headers } = await getCredentials({url: 'github.com/backstage/foobar'})
+   * ```ts
+   * const { token, headers } = await getCredentials({
+   *   url: 'github.com/backstage/foobar'
+   * })
+   * ```
+   *
+   * @param opts - The organization or repository URL
+   * @returns A promise of {@link GithubCredentials}.
    */
   async getCredentials(opts: { url: string }): Promise<GithubCredentials> {
     const parsed = parseGitUrl(opts.url);

packages/integration/src/github/config.ts

@@ -24,6 +24,8 @@ const GITHUB_RAW_BASE_URL = 'https://raw.githubusercontent.com';
 
 /**
  * The configuration parameters for a single GitHub integration.
+ *
+ * @public
  */
 export type GitHubIntegrationConfig = {
   /**
@@ -70,7 +72,12 @@ export type GitHubIntegrationConfig = {
 
 /**
  * The configuration parameters for authenticating a GitHub Application.
- * A Github Apps configuration can be generated using the `backstage-cli create-github-app` command.
+ *
+ * @remarks
+ *
+ * A GitHub Apps configuration can be generated using the `backstage-cli create-github-app` command.
+ *
+ * @public
  */
 export type GithubAppConfig = {
   /**
@@ -107,7 +114,8 @@ export type GithubAppConfig = {
 /**
  * Reads a single GitHub integration config.
  *
- * @param config The config object of a single integration
+ * @param config - The config object of a single integration
+ * @public
  */
 export function readGitHubIntegrationConfig(
   config: Config,
@@ -152,7 +160,8 @@ export function readGitHubIntegrationConfig(
  * Reads a set of GitHub integration configs, and inserts some defaults for
  * public GitHub if not specified.
  *
- * @param configs All of the integration config objects
+ * @param configs - All of the integration config objects
+ * @public
  */
 export function readGitHubIntegrationConfigs(
   configs: Config[],

packages/integration/src/github/core.ts

@@ -22,13 +22,16 @@ import { GithubCredentials } from './GithubCredentialsProvider';
  * Given a URL pointing to a file on a provider, returns a URL that is suitable
  * for fetching the contents of the data.
  *
+ * @remarks
+ *
  * Converts
  * from: https://github.com/a/b/blob/branchname/path/to/c.yaml
  * to:   https://api.github.com/repos/a/b/contents/path/to/c.yaml?ref=branchname
  * or:   https://raw.githubusercontent.com/a/b/branchname/c.yaml
  *
- * @param url A URL pointing to a file
- * @param config The relevant provider config
+ * @param url - A URL pointing to a file
+ * @param config - The relevant provider config
+ * @public
  */
 export function getGitHubFileFetchUrl(
   url: string,
@@ -64,7 +67,8 @@ export function getGitHubFileFetchUrl(
  * Gets the request options necessary to make requests to a given provider.
  *
  * @deprecated This function is no longer used internally
- * @param config The relevant provider config
+ * @param config - The relevant provider config
+ * @public
  */
 export function getGitHubRequestOptions(
   config: GitHubIntegrationConfig,

packages/integration/src/github/index.ts

@@ -18,14 +18,14 @@ export {
   readGitHubIntegrationConfig,
   readGitHubIntegrationConfigs,
 } from './config';
-export type { GitHubIntegrationConfig } from './config';
+export type { GithubAppConfig, GitHubIntegrationConfig } from './config';
 export { getGitHubFileFetchUrl, getGitHubRequestOptions } from './core';
 export {
   GithubAppCredentialsMux,
   GithubCredentialsProvider,
 } from './GithubCredentialsProvider';
-export type { GithubCredentialType } from './GithubCredentialsProvider';
-export {
-  GitHubIntegration,
-  replaceUrlType as replaceGitHubUrlType,
-} from './GitHubIntegration';
+export type {
+  GithubCredentials,
+  GithubCredentialType,
+} from './GithubCredentialsProvider';
+export { GitHubIntegration, replaceGitHubUrlType } from './GitHubIntegration';

packages/integration/src/gitlab/GitLabIntegration.ts

@@ -21,6 +21,11 @@ import {
   readGitLabIntegrationConfigs,
 } from './config';
 
+/**
+ * A GitLab based integration.
+ *
+ * @public
+ */
 export class GitLabIntegration implements ScmIntegration {
   static factory: ScmIntegrationsFactory<GitLabIntegration> = ({ config }) => {
     const configs = readGitLabIntegrationConfigs(

packages/integration/src/gitlab/config.ts

@@ -23,6 +23,8 @@ const GITLAB_API_BASE_URL = 'https://gitlab.com/api/v4';
 
 /**
  * The configuration parameters for a single GitLab integration.
+ *
+ * @public
  */
 export type GitLabIntegrationConfig = {
   /**
@@ -57,7 +59,8 @@ export type GitLabIntegrationConfig = {
 /**
  * Reads a single GitLab integration config.
  *
- * @param config The config object of a single integration
+ * @param config - The config object of a single integration
+ * @public
  */
 export function readGitLabIntegrationConfig(
   config: Config,
@@ -104,7 +107,8 @@ export function readGitLabIntegrationConfig(
  * Reads a set of GitLab integration configs, and inserts some defaults for
  * public GitLab if not specified.
  *
- * @param configs All of the integration config objects
+ * @param configs - All of the integration config objects
+ * @public
  */
 export function readGitLabIntegrationConfigs(
   configs: Config[],

packages/integration/src/gitlab/core.ts

@@ -21,6 +21,8 @@ import fetch from 'cross-fetch';
  * Given a URL pointing to a file on a provider, returns a URL that is suitable
  * for fetching the contents of the data.
  *
+ * @remarks
+ *
  * Converts
  * from: https://gitlab.example.com/a/b/blob/master/c.yaml
  * to:   https://gitlab.example.com/a/b/raw/master/c.yaml
@@ -28,8 +30,9 @@ import fetch from 'cross-fetch';
  * from: https://gitlab.com/groupA/teams/teamA/subgroupA/repoA/-/blob/branch/filepath
  * to:   https://gitlab.com/api/v4/projects/projectId/repository/files/filepath?ref=branch
  *
- * @param url A URL pointing to a file
- * @param config The relevant provider config
+ * @param url - A URL pointing to a file
+ * @param config - The relevant provider config
+ * @public
  */
 export async function getGitLabFileFetchUrl(
   url: string,
@@ -48,7 +51,8 @@ export async function getGitLabFileFetchUrl(
 /**
  * Gets the request options necessary to make requests to a given provider.
  *
- * @param config The relevant provider config
+ * @param config - The relevant provider config
+ * @public
  */
 export function getGitLabRequestOptions(
   config: GitLabIntegrationConfig,

packages/integration/src/googleGcs/config.ts

@@ -18,6 +18,8 @@ import { Config } from '@backstage/config';
 
 /**
  * The configuration parameters for a single Google Cloud Storage provider.
+ *
+ * @public
  */
 export type GoogleGcsIntegrationConfig = {
   /**
@@ -33,7 +35,8 @@ export type GoogleGcsIntegrationConfig = {
 /**
  * Reads a single Google GCS integration config.
  *
- * @param config The config object of a single integration
+ * @param config - The config object of a single integration
+ * @public
  */
 export function readGoogleGcsIntegrationConfig(
   config: Config,

packages/integration/src/helpers.ts

@@ -59,8 +59,10 @@ export function basicIntegrations<T extends ScmIntegration>(
 }
 
 /**
- * Default implementation of ScmIntegration.resolveUrl, that only works with
- * URL pathname based providers.
+ * Default implementation of {@link ScmIntegration} `resolveUrl`, that only
+ * works with URL pathname based providers.
+ *
+ * @public
  */
 export function defaultScmResolveUrl(options: {
   url: string;

packages/integration/src/index.ts

@@ -28,5 +28,10 @@ export * from './googleGcs';
 export * from './awsS3';
 export { defaultScmResolveUrl } from './helpers';
 export { ScmIntegrations } from './ScmIntegrations';
-export type { ScmIntegration, ScmIntegrationsGroup } from './types';
+export type { IntegrationsByType } from './ScmIntegrations';
+export type {
+  ScmIntegration,
+  ScmIntegrationsFactory,
+  ScmIntegrationsGroup,
+} from './types';
 export type { ScmIntegrationRegistry } from './registry';

packages/integration/src/registry.ts

@@ -23,6 +23,8 @@ import { GitLabIntegration } from './gitlab/GitLabIntegration';
 
 /**
  * Holds all registered SCM integrations, of all types.
+ *
+ * @public
  */
 export interface ScmIntegrationRegistry
   extends ScmIntegrationsGroup<ScmIntegration> {
@@ -44,9 +46,9 @@ export interface ScmIntegrationRegistry
    * not resolve to `https://hostname/b.yaml` but rather to
    * `<repo root url>/b.yaml` inside the file tree of that same repo.
    *
-   * @param options.url The (absolute or relative) URL or path to resolve
-   * @param options.base The base URL onto which this resolution happens
-   * @param options.lineNumber The line number in the target file to link to, starting with 1. Only applicable when linking to files.
+   * @param options.url - The (absolute or relative) URL or path to resolve
+   * @param options.base - The base URL onto which this resolution happens
+   * @param options.lineNumber - The line number in the target file to link to, starting with 1. Only applicable when linking to files.
    */
   resolveUrl(options: {
     url: string;
@@ -63,7 +65,7 @@ export interface ScmIntegrationRegistry
    * If this is not possible, the integration can fall back to a URL to view
    * the file in the web interface.
    *
-   * @param url The absolute URL to the file that should be edited.
+   * @param url - The absolute URL to the file that should be edited.
    */
   resolveEditUrl(url: string): string;
 }

packages/integration/src/types.ts

@@ -18,6 +18,8 @@ import { Config } from '@backstage/config';
 
 /**
  * Encapsulates a single SCM integration.
+ *
+ * @public
  */
 export interface ScmIntegration {
   /**
@@ -43,9 +45,9 @@ export interface ScmIntegration {
    * not resolve to `https://hostname/b.yaml` but rather to
    * `<repo root url>/b.yaml` inside the file tree of that same repo.
    *
-   * @param options.url The (absolute or relative) URL or path to resolve
-   * @param options.base The base URL onto which this resolution happens
-   * @param options.lineNumber The line number in the target file to link to, starting with 1. Only applicable when linking to files.
+   * @param options.url - The (absolute or relative) URL or path to resolve
+   * @param options.base - The base URL onto which this resolution happens
+   * @param options.lineNumber - The line number in the target file to link to, starting with 1. Only applicable when linking to files.
    */
   resolveUrl(options: {
     url: string;
@@ -62,13 +64,15 @@ export interface ScmIntegration {
    * If this is not possible, the integration can fall back to a URL to view
    * the file in the web interface.
    *
-   * @param url The absolute URL to the file that should be edited.
+   * @param url - The absolute URL to the file that should be edited.
    */
   resolveEditUrl(url: string): string;
 }
 
 /**
  * Encapsulates several integrations, that are all of the same type.
+ *
+ * @public
  */
 export interface ScmIntegrationsGroup<T extends ScmIntegration> {
   /**
@@ -79,18 +83,23 @@ export interface ScmIntegrationsGroup<T extends ScmIntegration> {
   /**
    * Fetches an integration of this type by URL.
    *
-   * @param url A URL that matches a registered integration of this type
+   * @param url - A URL that matches a registered integration of this type
    */
   byUrl(url: string | URL): T | undefined;
 
   /**
    * Fetches an integration of this type by host name.
    *
-   * @param url A host name that matches a registered integration of this type
+   * @param host - A host name that matches a registered integration of this type
    */
   byHost(host: string): T | undefined;
 }
 
+/**
+ * A factory function that creates an integration group based on configuration.
+ *
+ * @public
+ */
 export type ScmIntegrationsFactory<T extends ScmIntegration> = (options: {
   config: Config;
 }) => ScmIntegrationsGroup<T>;

packages/theme/api-report.md

@@ -9,16 +9,71 @@ import { PaletteOptions } from '@material-ui/core/styles/createPalette';
 import { Theme } from '@material-ui/core';
 import { ThemeOptions } from '@material-ui/core';
 
-// Warning: (ae-forgotten-export) The symbol "PaletteAdditions" needs to be exported by the entry point index.d.ts
 // Warning: (ae-missing-release-tag) "BackstagePalette" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
-export type BackstagePalette = Palette & PaletteAdditions;
+export type BackstagePalette = Palette & BackstagePaletteAdditions;
+
+// @public
+export type BackstagePaletteAdditions = {
+  status: {
+    ok: string;
+    warning: string;
+    error: string;
+    pending: string;
+    running: string;
+    aborted: string;
+  };
+  border: string;
+  textContrast: string;
+  textVerySubtle: string;
+  textSubtle: string;
+  highlight: string;
+  errorBackground: string;
+  warningBackground: string;
+  infoBackground: string;
+  errorText: string;
+  infoText: string;
+  warningText: string;
+  linkHover: string;
+  link: string;
+  gold: string;
+  navigation: {
+    background: string;
+    indicator: string;
+    color: string;
+    selectedColor: string;
+  };
+  tabbar: {
+    indicator: string;
+  };
+  bursts: {
+    fontColor: string;
+    slackChannelText: string;
+    backgroundColor: {
+      default: string;
+    };
+    gradient: {
+      linear: string;
+    };
+  };
+  pinSidebarButton: {
+    icon: string;
+    background: string;
+  };
+  banner: {
+    info: string;
+    error: string;
+    text: string;
+    link: string;
+  };
+};
 
 // Warning: (ae-missing-release-tag) "BackstagePaletteOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
-export type BackstagePaletteOptions = PaletteOptions & PaletteAdditions;
+export type BackstagePaletteOptions = PaletteOptions &
+  BackstagePaletteAdditions;
 
 // Warning: (ae-missing-release-tag) "BackstageTheme" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //

packages/theme/src/types.ts

@@ -20,7 +20,12 @@ import {
   Palette,
 } from '@material-ui/core/styles/createPalette';
 
-type PaletteAdditions = {
+/**
+ * Backstage specific additions to the material-ui palette.
+ *
+ * @public
+ */
+export type BackstagePaletteAdditions = {
   status: {
     ok: string;
     warning: string;
@@ -74,8 +79,9 @@ type PaletteAdditions = {
   };
 };
 
-export type BackstagePalette = Palette & PaletteAdditions;
-export type BackstagePaletteOptions = PaletteOptions & PaletteAdditions;
+export type BackstagePalette = Palette & BackstagePaletteAdditions;
+export type BackstagePaletteOptions = PaletteOptions &
+  BackstagePaletteAdditions;
 
 export type PageThemeSelector = {
   themeId: string;