touch up the catalog client docs

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

.changeset/stupid-pans-hope.md

@@ -0,0 +1,5 @@
+---
+'@backstage/catalog-client': patch
+---
+
+Minor update to catalog client docs

packages/catalog-client/src/CatalogClient.ts

@@ -535,9 +535,7 @@ export class CatalogClient implements CatalogApi {
     } while (cursor);
   }
 
-  //
-  // Private methods
-  //
+  // #region Private methods
 
   private async requestIgnored(response: Response): Promise<void> {
     if (!response.ok) {
@@ -588,4 +586,6 @@ export class CatalogClient implements CatalogApi {
     }
     return filters;
   }
+
+  // #endregion
 }

packages/catalog-client/src/types/api.ts

@@ -24,7 +24,7 @@ import { FilterPredicate } from '@backstage/filter-predicates';
 
 /**
  * This symbol can be used in place of a value when passed to filters in e.g.
- * {@link CatalogClient.getEntities}, to signify that you want to filter on the
+ * {@link CatalogApi.getEntities}, to signify that you want to filter on the
  * presence of that key no matter what its value is.
  *
  * @public
@@ -146,7 +146,7 @@ export type EntityOrderQuery =
     }>;
 
 /**
- * The request type for {@link CatalogClient.getEntities}.
+ * The request type for {@link CatalogApi.getEntities}.
  *
  * @public
  */
@@ -180,7 +180,7 @@ export interface GetEntitiesRequest {
 }
 
 /**
- * The response type for {@link CatalogClient.getEntities}.
+ * The response type for {@link CatalogApi.getEntities}.
  *
  * @public
  */
@@ -189,7 +189,7 @@ export interface GetEntitiesResponse {
 }
 
 /**
- * The request type for {@link CatalogClient.getEntitiesByRefs}.
+ * The request type for {@link CatalogApi.getEntitiesByRefs}.
  *
  * @public
  */
@@ -200,7 +200,7 @@ export interface GetEntitiesByRefsRequest {
    * @remarks
    *
    * The returned list of entities will be in the same order as the refs, and
-   * null will be returned in those positions that were not found.
+   * undefined will be returned in those positions that were not found.
    */
   entityRefs: string[];
   /**
@@ -215,7 +215,7 @@ export interface GetEntitiesByRefsRequest {
 }
 
 /**
- * The response type for {@link CatalogClient.getEntitiesByRefs}.
+ * The response type for {@link CatalogApi.getEntitiesByRefs}.
  *
  * @public
  */
@@ -226,13 +226,13 @@ export interface GetEntitiesByRefsResponse {
    * @remarks
    *
    * The list will be in the same order as the refs given in the request, and
-   * null will be returned in those positions that were not found.
+   * undefined will be returned in those positions that were not found.
    */
   items: Array<Entity | undefined>;
 }
 
 /**
- * The request type for {@link CatalogClient.getEntityAncestors}.
+ * The request type for {@link CatalogApi.getEntityAncestors}.
  *
  * @public
  */
@@ -241,7 +241,7 @@ export interface GetEntityAncestorsRequest {
 }
 
 /**
- * The response type for {@link CatalogClient.getEntityAncestors}.
+ * The response type for {@link CatalogApi.getEntityAncestors}.
  *
  * @public
  */
@@ -254,7 +254,7 @@ export interface GetEntityAncestorsResponse {
 }
 
 /**
- * The request type for {@link CatalogClient.getEntityFacets}.
+ * The request type for {@link CatalogApi.getEntityFacets}.
  *
  * @public
  */
@@ -323,7 +323,7 @@ export interface GetEntityFacetsRequest {
 }
 
 /**
- * The response type for {@link CatalogClient.getEntityFacets}.
+ * The response type for {@link CatalogApi.getEntityFacets}.
  *
  * @public
  */
@@ -355,7 +355,7 @@ export type Location = {
 };
 
 /**
- * The response type for {@link CatalogClient.getLocations}
+ * The response type for {@link CatalogApi.getLocations}
  *
  * @public
  */
@@ -364,7 +364,7 @@ export interface GetLocationsResponse {
 }
 
 /**
- * The request type for {@link CatalogClient.addLocation}.
+ * The request type for {@link CatalogApi.addLocation}.
  *
  * @public
  */
@@ -379,7 +379,7 @@ export type AddLocationRequest = {
 };
 
 /**
- * The response type for {@link CatalogClient.addLocation}.
+ * The response type for {@link CatalogApi.addLocation}.
  *
  * @public
  */
@@ -396,7 +396,7 @@ export type AddLocationResponse = {
 };
 
 /**
- * The response type for {@link CatalogClient.validateEntity}
+ * The response type for {@link CatalogApi.validateEntity}
  *
  * @public
  */
@@ -405,7 +405,7 @@ export type ValidateEntityResponse =
   | { valid: false; errors: SerializedError[] };
 
 /**
- * The request type for {@link CatalogClient.queryEntities}.
+ * The request type for {@link CatalogApi.queryEntities}.
  *
  * @public
  */
@@ -414,7 +414,7 @@ export type QueryEntitiesRequest =
   | QueryEntitiesCursorRequest;
 
 /**
- * A request type for {@link CatalogClient.queryEntities}.
+ * A request type for {@link CatalogApi.queryEntities}.
  * The method takes this type in an initial pagination request,
  * when requesting the first batch of entities.
  *
@@ -436,7 +436,7 @@ export type QueryEntitiesInitialRequest = {
 };
 
 /**
- * A request type for {@link CatalogClient.queryEntities}.
+ * A request type for {@link CatalogApi.queryEntities}.
  * The method takes this type in a pagination request, following
  * the initial request.
  *
@@ -449,7 +449,7 @@ export type QueryEntitiesCursorRequest = {
 };
 
 /**
- * The response type for {@link CatalogClient.queryEntities}.
+ * The response type for {@link CatalogApi.queryEntities}.
  *
  * @public
  */
@@ -467,7 +467,7 @@ export type QueryEntitiesResponse = {
 };
 
 /**
- * Stream entities request for {@link CatalogClient.streamEntities}.
+ * Stream entities request for {@link CatalogApi.streamEntities}.
  *
  * @public
  */

packages/catalog-client/src/types/discovery.ts

@@ -15,7 +15,7 @@
  */
 
 /**
- * This is a copy of the DiscoveryApi, to avoid importing core-plugin-api.
+ * This is a polymorphic version of `DiscoveryApi` / `DiscoveryService`.
  */
 export type DiscoveryApi = {
   getBaseUrl(pluginId: string): Promise<string>;

packages/catalog-client/src/types/fetch.ts

@@ -15,7 +15,7 @@
  */
 
 /**
- * This is a copy of FetchApi, to avoid importing core-plugin-api.
+ * This is a polymorphic version of `FetchApi`.
  */
 export type FetchApi = {
   fetch: typeof fetch;