Deprecated LocationEntityProcessor, added doc comments

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

.changeset/four-pans-sin.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Marked the `LocationEntityProcessor` as deprecated, as it is no longer used internally since way back and can even be harmful at this point.

.changeset/heavy-forks-tie.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-node': patch
+---
+
+Added docs to `processingResult`

plugins/catalog-backend/api-report.md

@@ -365,7 +365,7 @@ export type LocationAnalyzer = {
   ): Promise<AnalyzeLocationResponse>;
 };
 
-// @public (undocumented)
+// @public @deprecated
 export class LocationEntityProcessor implements CatalogProcessor_2 {
   constructor(options: LocationEntityProcessorOptions);
   // (undocumented)
@@ -378,7 +378,7 @@ export class LocationEntityProcessor implements CatalogProcessor_2 {
   ): Promise<Entity>;
 }
 
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export type LocationEntityProcessorOptions = {
   integrations: ScmIntegrationRegistry;
 };

plugins/catalog-backend/src/modules/core/LocationEntityProcessor.ts

@@ -42,12 +42,26 @@ export function toAbsoluteUrl(
   }
 }
 
-/** @public */
+/**
+ * @public
+ * @deprecated This processor should no longer be used
+ */
 export type LocationEntityProcessorOptions = {
   integrations: ScmIntegrationRegistry;
 };
 
-/** @public */
+/**
+ * Legacy processor, should not be used.
+ *
+ * @remarks
+ *
+ * In the old catalog architecture, this processor translated Location entities
+ * into URLs that should be fetched. This is no longer needed since the engine
+ * handles this internally.
+ *
+ * @public
+ * @deprecated This processor should no longer be used
+ */
 export class LocationEntityProcessor implements CatalogProcessor {
   constructor(private readonly options: LocationEntityProcessorOptions) {}
 

plugins/catalog-node/src/api/processingResult.ts

@@ -26,6 +26,9 @@ import { LocationSpec } from '@backstage/plugin-catalog-common';
  * @public
  */
 export const processingResult = Object.freeze({
+  /**
+   * Associates a NotFoundError with the processing state of the current entity.
+   */
   notFoundError(
     atLocation: LocationSpec,
     message: string,
@@ -37,6 +40,9 @@ export const processingResult = Object.freeze({
     };
   },
 
+  /**
+   * Associates an InputError with the processing state of the current entity.
+   */
   inputError(
     atLocation: LocationSpec,
     message: string,
@@ -48,6 +54,9 @@ export const processingResult = Object.freeze({
     };
   },
 
+  /**
+   * Associates a general Error with the processing state of the current entity.
+   */
   generalError(
     atLocation: LocationSpec,
     message: string,
@@ -55,18 +64,36 @@ export const processingResult = Object.freeze({
     return { type: 'error', location: atLocation, error: new Error(message) };
   },
 
+  /**
+   * Emits a location. In effect, this is analogous to emitting a Location kind
+   * child entity. This is commonly used in discovery processors. Do not use
+   * this while processing Location entities.
+   */
   location(newLocation: LocationSpec): CatalogProcessorResult {
     return { type: 'location', location: newLocation };
   },
 
+  /**
+   * Emits a child of the current entity, associated with a certain location.
+   */
   entity(atLocation: LocationSpec, newEntity: Entity): CatalogProcessorResult {
     return { type: 'entity', location: atLocation, entity: newEntity };
   },
 
+  /**
+   * Emits a relation owned by the current entity. The relation does not have to
+   * start or end at the current entity. The relation only lives for as long as
+   * the current entity lives.
+   */
   relation(spec: EntityRelationSpec): CatalogProcessorResult {
     return { type: 'relation', relation: spec };
   },
 
+  /**
+   * Associates the given refresh key with the current entity. The effect of
+   * this is that the entity will be marked for refresh when such requests are
+   * made.
+   */
   refresh(key: string): CatalogProcessorResult {
     return { type: 'refresh', key };
   },