Merge pull request #3684 from adamdmharvey/jsdocs

Update Core API JS doc comments

packages/core-api/src/apis/definitions/ConfigApi.ts

@@ -16,7 +16,10 @@
 import { ApiRef, createApiRef } from '../system';
 import { Config } from '@backstage/config';
 
-// Using interface to make the ConfigApi name show up in docs
+/**
+ * The Config API is used to provide a mechanism to access the
+ * runtime configuration of the system.
+ */
 export type ConfigApi = Config;
 
 export const configApiRef: ApiRef<ConfigApi> = createApiRef({

packages/core-api/src/apis/definitions/DiscoveryApi.ts

@@ -31,7 +31,7 @@ export type DiscoveryApi = {
   /**
    * Returns the HTTP base backend URL for a given plugin, without a trailing slash.
    *
-   * This method must always be called just before making a request. as opposed to
+   * This method must always be called just before making a request, as opposed to
    * fetching the URL when constructing an API client. That is to ensure that more
    * flexible routing patterns can be supported.
    *

packages/core-api/src/apis/definitions/ErrorApi.ts

@@ -42,10 +42,10 @@ export type ErrorContext = {
  * to report errors for collection by error reporting services.
  *
  * If an error can be displayed inline, e.g. as feedback in a form, that should be
- * preferred over relying on this API to display the error. The main use of this api
+ * preferred over relying on this API to display the error. The main use of this API
  * for displaying errors should be for asynchronous errors, such as a failing background process.
  *
- * Even if an error is displayed inline, it should still be reported through this api
+ * Even if an error is displayed inline, it should still be reported through this API
  * if it would be useful to collect or log it for debugging purposes, but with
  * the hidden flag set. For example, an error arising from form field validation
  * should probably not be reported, while a failed REST call would be useful to report.

packages/core-api/src/apis/definitions/IdentityApi.ts

@@ -30,6 +30,7 @@ export type IdentityApi = {
    */
   getUserId(): string;
 
+  // TODO: getProfile(): Promise<Profile> - We want this to be async when added, but needs more work.
   /**
    * The profile of the signed in user.
    */
@@ -43,8 +44,6 @@ export type IdentityApi = {
    */
   getIdToken(): Promise<string | undefined>;
 
-  // TODO: getProfile(): Promise<Profile> - We want this to be async when added, but needs more work.
-
   /**
    * Sign out the current user
    */

packages/core-api/src/apis/definitions/index.ts

@@ -25,9 +25,9 @@ export * from './auth';
 export * from './AlertApi';
 export * from './AppThemeApi';
 export * from './ConfigApi';
+export * from './DiscoveryApi';
 export * from './ErrorApi';
 export * from './FeatureFlagsApi';
-export * from './DiscoveryApi';
 export * from './IdentityApi';
 export * from './OAuthRequestApi';
 export * from './StorageApi';