Merge pull request #7610 from jluk-box/catalog-model-doc

Improve API docs in @backstage/catalog-model

.changeset/two-ties-eat.md

@@ -0,0 +1,5 @@
+---
+'@backstage/catalog-model': patch
+---
+
+Improved documentation for exported symbols.

packages/catalog-model/api-report.md

@@ -9,12 +9,12 @@ import { JsonValue } from '@backstage/config';
 import { SerializedError } from '@backstage/errors';
 import * as yup from 'yup';
 
-// @public @deprecated (undocumented)
+// @public @deprecated
 export const analyzeLocationSchema: yup.SchemaOf<{
   location: LocationSpec;
 }>;
 
-// @public (undocumented)
+// @public
 interface ApiEntityV1alpha1 extends Entity {
   // (undocumented)
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
@@ -32,7 +32,7 @@ interface ApiEntityV1alpha1 extends Entity {
 export { ApiEntityV1alpha1 as ApiEntity };
 export { ApiEntityV1alpha1 };
 
-// @public (undocumented)
+// @public
 export const apiEntityV1alpha1Validator: KindValidator;
 
 // @public
@@ -58,7 +58,7 @@ export function compareEntityToRef(
   context?: EntityRefContext,
 ): boolean;
 
-// @public (undocumented)
+// @public
 interface ComponentEntityV1alpha1 extends Entity {
   // (undocumented)
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
@@ -79,7 +79,7 @@ interface ComponentEntityV1alpha1 extends Entity {
 export { ComponentEntityV1alpha1 as ComponentEntity };
 export { ComponentEntityV1alpha1 };
 
-// @public (undocumented)
+// @public
 export const componentEntityV1alpha1Validator: KindValidator;
 
 // @public
@@ -89,7 +89,7 @@ export class DefaultNamespaceEntityPolicy implements EntityPolicy {
   enforce(entity: Entity): Promise<Entity>;
 }
 
-// @public (undocumented)
+// @public
 interface DomainEntityV1alpha1 extends Entity {
   // (undocumented)
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
@@ -103,10 +103,10 @@ interface DomainEntityV1alpha1 extends Entity {
 export { DomainEntityV1alpha1 as DomainEntity };
 export { DomainEntityV1alpha1 };
 
-// @public (undocumented)
+// @public
 export const domainEntityV1alpha1Validator: KindValidator;
 
-// @public (undocumented)
+// @public
 export const EDIT_URL_ANNOTATION = 'backstage.io/edit-url';
 
 // @public
@@ -181,7 +181,7 @@ export type EntityName = {
   name: string;
 };
 
-// @public (undocumented)
+// @public
 export const EntityPolicies: {
   allOf(policies: EntityPolicy[]): EntityPolicy;
   oneOf(policies: EntityPolicy[]): EntityPolicy;
@@ -250,7 +250,7 @@ export function getEntitySourceLocation(entity: Entity): {
   target: string;
 };
 
-// @public (undocumented)
+// @public
 interface GroupEntityV1alpha1 extends Entity {
   // (undocumented)
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
@@ -272,10 +272,10 @@ interface GroupEntityV1alpha1 extends Entity {
 export { GroupEntityV1alpha1 as GroupEntity };
 export { GroupEntityV1alpha1 };
 
-// @public (undocumented)
+// @public
 export const groupEntityV1alpha1Validator: KindValidator;
 
-// @public (undocumented)
+// @public
 export type JSONSchema = JSONSchema7 & {
   [key in string]?: JsonValue;
 };
@@ -305,16 +305,16 @@ export class KubernetesValidatorFunctions {
   static isValidObjectName(value: unknown): boolean;
 }
 
-// @public (undocumented)
+// @public
 type Location_2 = {
   id: string;
 } & LocationSpec;
 export { Location_2 as Location };
 
-// @public (undocumented)
+// @public
 export const LOCATION_ANNOTATION = 'backstage.io/managed-by-location';
 
-// @public (undocumented)
+// @public
 interface LocationEntityV1alpha1 extends Entity {
   // (undocumented)
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
@@ -330,23 +330,23 @@ interface LocationEntityV1alpha1 extends Entity {
 export { LocationEntityV1alpha1 as LocationEntity };
 export { LocationEntityV1alpha1 };
 
-// @public (undocumented)
+// @public
 export const locationEntityV1alpha1Validator: KindValidator;
 
-// @public @deprecated (undocumented)
+// @public @deprecated
 export const locationSchema: yup.SchemaOf<Location_2>;
 
-// @public (undocumented)
+// @public
 export type LocationSpec = {
   type: string;
   target: string;
   presence?: 'optional' | 'required';
 };
 
-// @public @deprecated (undocumented)
+// @public @deprecated
 export const locationSpecSchema: yup.SchemaOf<LocationSpec>;
 
-// @public (undocumented)
+// @public
 export function makeValidator(overrides?: Partial<Validators>): Validators;
 
 // @public
@@ -356,7 +356,7 @@ export class NoForeignRootFieldsEntityPolicy implements EntityPolicy {
   enforce(entity: Entity): Promise<Entity>;
 }
 
-// @public (undocumented)
+// @public
 export const ORIGIN_LOCATION_ANNOTATION =
   'backstage.io/managed-by-origin-location';
 
@@ -373,13 +373,9 @@ export function parseEntityRef(
     defaultKind: string;
     defaultNamespace: string;
   },
-): {
-  kind: string;
-  namespace: string;
-  name: string;
-};
+): EntityName;
 
-// @public (undocumented)
+// @public
 export function parseEntityRef(
   ref: EntityRef,
   context?: {
@@ -391,7 +387,7 @@ export function parseEntityRef(
   name: string;
 };
 
-// @public (undocumented)
+// @public
 export function parseEntityRef(
   ref: EntityRef,
   context?: {
@@ -409,28 +405,28 @@ export function parseLocationReference(ref: string): {
   target: string;
 };
 
-// @public (undocumented)
+// @public
 export const RELATION_API_CONSUMED_BY = 'apiConsumedBy';
 
-// @public (undocumented)
+// @public
 export const RELATION_API_PROVIDED_BY = 'apiProvidedBy';
 
-// @public (undocumented)
+// @public
 export const RELATION_CHILD_OF = 'childOf';
 
 // @public
 export const RELATION_CONSUMES_API = 'consumesApi';
 
-// @public (undocumented)
+// @public
 export const RELATION_DEPENDENCY_OF = 'dependencyOf';
 
 // @public
 export const RELATION_DEPENDS_ON = 'dependsOn';
 
-// @public (undocumented)
+// @public
 export const RELATION_HAS_MEMBER = 'hasMember';
 
-// @public (undocumented)
+// @public
 export const RELATION_HAS_PART = 'hasPart';
 
 // @public
@@ -439,7 +435,7 @@ export const RELATION_MEMBER_OF = 'memberOf';
 // @public
 export const RELATION_OWNED_BY = 'ownedBy';
 
-// @public (undocumented)
+// @public
 export const RELATION_OWNER_OF = 'ownerOf';
 
 // @public
@@ -448,10 +444,10 @@ export const RELATION_PARENT_OF = 'parentOf';
 // @public
 export const RELATION_PART_OF = 'partOf';
 
-// @public (undocumented)
+// @public
 export const RELATION_PROVIDES_API = 'providesApi';
 
-// @public (undocumented)
+// @public
 interface ResourceEntityV1alpha1 extends Entity {
   // (undocumented)
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
@@ -468,7 +464,7 @@ interface ResourceEntityV1alpha1 extends Entity {
 export { ResourceEntityV1alpha1 as ResourceEntity };
 export { ResourceEntityV1alpha1 };
 
-// @public (undocumented)
+// @public
 export const resourceEntityV1alpha1Validator: KindValidator;
 
 // @public
@@ -488,7 +484,7 @@ export function serializeEntityRef(
       },
 ): EntityRef;
 
-// @public (undocumented)
+// @public
 export const SOURCE_LOCATION_ANNOTATION = 'backstage.io/source-location';
 
 // @public
@@ -508,7 +504,7 @@ export function stringifyLocationReference(ref: {
   target: string;
 }): string;
 
-// @public (undocumented)
+// @public
 interface SystemEntityV1alpha1 extends Entity {
   // (undocumented)
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
@@ -523,10 +519,10 @@ interface SystemEntityV1alpha1 extends Entity {
 export { SystemEntityV1alpha1 as SystemEntity };
 export { SystemEntityV1alpha1 };
 
-// @public (undocumented)
+// @public
 export const systemEntityV1alpha1Validator: KindValidator;
 
-// @public (undocumented)
+// @public
 export interface TemplateEntityV1beta2 extends Entity {
   // (undocumented)
   apiVersion: 'backstage.io/v1beta2';
@@ -550,7 +546,7 @@ export interface TemplateEntityV1beta2 extends Entity {
   };
 }
 
-// @public (undocumented)
+// @public
 export const templateEntityV1beta2Validator: KindValidator;
 
 // @alpha
@@ -569,7 +565,7 @@ export type UNSTABLE_EntityStatusItem = {
 // @alpha
 export type UNSTABLE_EntityStatusLevel = 'info' | 'warning' | 'error';
 
-// @public (undocumented)
+// @public
 interface UserEntityV1alpha1 extends Entity {
   // (undocumented)
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
@@ -588,10 +584,10 @@ interface UserEntityV1alpha1 extends Entity {
 export { UserEntityV1alpha1 as UserEntity };
 export { UserEntityV1alpha1 };
 
-// @public (undocumented)
+// @public
 export const userEntityV1alpha1Validator: KindValidator;
 
-// @public (undocumented)
+// @public
 export type Validators = {
   isValidApiVersion(value: unknown): boolean;
   isValidKind(value: unknown): boolean;
@@ -609,5 +605,5 @@ export const VIEW_URL_ANNOTATION = 'backstage.io/view-url';
 
 // Warnings were encountered during analysis:
 //
-// src/entity/Entity.d.ts:38:5 - (ae-incompatible-release-tags) The symbol "status" is marked as @public, but its signature references "UNSTABLE_EntityStatus" which is marked as @alpha
+// src/entity/Entity.d.ts:41:5 - (ae-incompatible-release-tags) The symbol "status" is marked as @public, but its signature references "UNSTABLE_EntityStatus" which is marked as @alpha
 ```

packages/catalog-model/src/EntityPolicies.ts

@@ -52,7 +52,11 @@ class AnyEntityPolicy implements EntityPolicy {
   }
 }
 
-/** @public */
+/**
+ * Provides helpers for enforcing a set of {@link EntityPolicy} in an `and`/`or` expression.
+ *
+ * @public
+ */
 export const EntityPolicies = {
   allOf(policies: EntityPolicy[]): EntityPolicy {
     return new AllEntityPolicies(policies);

packages/catalog-model/src/entity/Entity.ts

@@ -21,8 +21,11 @@ import { UNSTABLE_EntityStatus } from './EntityStatus';
 /**
  * The parts of the format that's common to all versions/kinds of entity.
  *
+ * @remarks
+ *
+ * See also:
+ * {@link https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/}
  * @public
- * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/
  */
 export type Entity = {
   /**
@@ -63,9 +66,13 @@ export type Entity = {
 /**
  * Metadata fields common to all versions/kinds of entity.
  *
+ * @remarks
+ *
+ * See also:
+ * {@link https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#objectmeta-v1-meta}
+ * {@link https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/}
+ *
  * @public
- * @see https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#objectmeta-v1-meta
- * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/
  */
 export type EntityMeta = JsonObject & {
   /**

packages/catalog-model/src/entity/constants.ts

@@ -33,10 +33,15 @@ export const ENTITY_META_GENERATED_FIELDS = [
 ] as const;
 
 /**
- * Annotations for linking to entity from catalog pages.
+ * Annotation for linking to entity page from catalog pages.
  *
  * @public
  */
 export const VIEW_URL_ANNOTATION = 'backstage.io/view-url';
-/** @public */
+
+/**
+ * Annotation for linking to entity edit page from catalog pages.
+ *
+ * @public
+ */
 export const EDIT_URL_ANNOTATION = 'backstage.io/edit-url';

packages/catalog-model/src/entity/policies/FieldFormatEntityPolicy.ts

@@ -27,6 +27,8 @@ import { Entity } from '../Entity';
  * Ensures that the format of individual fields of the entity envelope
  * is valid.
  *
+ * @remarks
+ *
  * This does not take into account machine generated fields such as uid, etag
  * and generation.
  *

packages/catalog-model/src/entity/policies/SchemaValidEntityPolicy.ts

@@ -24,6 +24,8 @@ import { EntityPolicy } from './types';
 /**
  * Ensures that the entity spec is valid according to a schema.
  *
+ * @remarks
+ *
  * This should be the first policy in the list, to ensure that other downstream
  * policies can work with a structure that is at least valid in therms of the
  * typescript type.

packages/catalog-model/src/entity/ref.ts

@@ -69,6 +69,8 @@ export type EntityRefContext = {
  * Parses an entity reference, either on string or compound form, and always
  * returns a complete entity name including kind, namespace and name.
  *
+ * @remarks
+ *
  * This function automatically assumes the default namespace "default" unless
  * otherwise specified as part of the options, and will throw an error if no
  * kind was specified in the input reference and no default kind was given.
@@ -100,7 +102,9 @@ export function parseEntityName(
  * Parses an entity reference, either on string or compound form, and returns
  * a structure with a name, and optional kind and namespace.
  *
- * The options object can contain default values for the kind and namespace,
+ * @remarks
+ *
+ * The context object can contain default values for the kind and namespace,
  * that will be used if the input reference did not specify any.
  *
  * @public
@@ -111,12 +115,12 @@ export function parseEntityName(
 export function parseEntityRef(
   ref: EntityRef,
   context?: { defaultKind: string; defaultNamespace: string },
-): {
-  kind: string;
-  namespace: string;
-  name: string;
-};
-/** @public */
+): EntityName;
+/**
+ * parseEntityRef with optional Kind.
+ *
+ * @public
+ */
 export function parseEntityRef(
   ref: EntityRef,
   context?: { defaultKind: string },
@@ -125,7 +129,11 @@ export function parseEntityRef(
   namespace?: string;
   name: string;
 };
-/** @public */
+/**
+ * parseEntityRef with optional Namespace.
+ *
+ * @public
+ */
 export function parseEntityRef(
   ref: EntityRef,
   context?: { defaultNamespace: string },
@@ -134,6 +142,11 @@ export function parseEntityRef(
   namespace: string;
   name: string;
 };
+/**
+ * parseEntityRef with optional Kind and Namespace.
+ *
+ * @public
+ */
 export function parseEntityRef(
   ref: EntityRef,
   context: EntityRefContext = {},
@@ -223,6 +236,8 @@ export function serializeEntityRef(
  * Takes an entity or entity name/reference, and returns the string form of an
  * entity ref.
  *
+ * @remarks
+ *
  * This function creates a canonical and unique reference to the entity, converting
  * all parts of the name to lowercase and inserts the default namespace if needed.
  * It is typically not the best way to represent the entity reference to the user.
@@ -256,6 +271,8 @@ export function stringifyEntityRef(
 /**
  * Compares an entity to either a string reference or a compound reference.
  *
+ * @remarks
+ *
  * The comparison is case insensitive, and all of kind, namespace, and name
  * must match (after applying the optional context to the ref).
  *

packages/catalog-model/src/entity/util.ts

@@ -43,6 +43,8 @@ export function generateEntityEtag(): string {
  * Checks whether there are any significant changes going from the previous to
  * the next version of this entity.
  *
+ * @remarks
+ *
  * Significance, in this case, means that we do not compare generated fields
  * such as uid, etag and generation.
  *
@@ -98,6 +100,8 @@ export function entityHasChanges(previous: Entity, next: Entity): boolean {
  * Takes an old revision of an entity and a new desired state, and merges
  * them into a complete new state.
  *
+ * @remarks
+ *
  * The previous revision is expected to be a complete model loaded from the
  * catalog, including the uid, etag and generation fields.
  *

packages/catalog-model/src/kinds/ApiEntityV1alpha1.ts

@@ -18,7 +18,15 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/API.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';
 
-/** @public */
+/**
+ * Backstage API kind Entity. APIs describe the interfaces for Components to communicate.
+ *
+ * @remarks
+ *
+ * See {@link https://backstage.io/docs/features/software-catalog/system-model}
+ *
+ * @public
+ */
 export interface ApiEntityV1alpha1 extends Entity {
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
   kind: 'API';
@@ -31,6 +39,10 @@ export interface ApiEntityV1alpha1 extends Entity {
   };
 }
 
-/** @public */
+/**
+ * {@link KindValidator} for {@link ApiEntityV1alpha1}.
+ *
+ * @public
+ */
 export const apiEntityV1alpha1Validator =
   ajvCompiledJsonSchemaValidator(schema);

packages/catalog-model/src/kinds/ComponentEntityV1alpha1.ts

@@ -18,7 +18,15 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/Component.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';
 
-/** @public */
+/**
+ * Backstage catalog Component kind Entity. Represents a single, individual piece of software.
+ *
+ * @remarks
+ *
+ * See {@link https://backstage.io/docs/features/software-catalog/system-model}
+ *
+ * @public
+ */
 export interface ComponentEntityV1alpha1 extends Entity {
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
   kind: 'Component';
@@ -34,6 +42,10 @@ export interface ComponentEntityV1alpha1 extends Entity {
   };
 }
 
-/** @public */
+/**
+ * {@link KindValidator} for {@link ComponentEntityV1alpha1}.
+ *
+ * @public
+ */
 export const componentEntityV1alpha1Validator =
   ajvCompiledJsonSchemaValidator(schema);

packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts

@@ -18,7 +18,15 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/Domain.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';
 
-/** @public */
+/**
+ * Backstage Domain kind Entity. Domains group Systems together.
+ *
+ * @remarks
+ *
+ * See {@link https://backstage.io/docs/features/software-catalog/system-model}
+ *
+ * @public
+ */
 export interface DomainEntityV1alpha1 extends Entity {
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
   kind: 'Domain';
@@ -27,6 +35,10 @@ export interface DomainEntityV1alpha1 extends Entity {
   };
 }
 
-/** @public */
+/**
+ * {@link KindValidator} for {@link DomainEntityV1alpha1}.
+ *
+ * @public
+ */
 export const domainEntityV1alpha1Validator =
   ajvCompiledJsonSchemaValidator(schema);

packages/catalog-model/src/kinds/GroupEntityV1alpha1.ts

@@ -18,7 +18,11 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/Group.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';
 
-/** @public */
+/**
+ * Backstage catalog Group kind Entity.
+ *
+ * @public
+ */
 export interface GroupEntityV1alpha1 extends Entity {
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
   kind: 'Group';
@@ -35,6 +39,9 @@ export interface GroupEntityV1alpha1 extends Entity {
   };
 }
 
-/** @public */
+/**
+ * {@link KindValidator} for {@link GroupEntityV1alpha1}.
+ * @public
+ */
 export const groupEntityV1alpha1Validator =
   ajvCompiledJsonSchemaValidator(schema);

packages/catalog-model/src/kinds/LocationEntityV1alpha1.ts

@@ -18,7 +18,11 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/Location.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';
 
-/** @public */
+/**
+ * Backstage catalog Location kind Entity.
+ *
+ * @public
+ */
 export interface LocationEntityV1alpha1 extends Entity {
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
   kind: 'Location';
@@ -29,6 +33,10 @@ export interface LocationEntityV1alpha1 extends Entity {
   };
 }
 
-/** @public */
+/**
+ * {@link KindValidator} for {@link LocationEntityV1alpha1}.
+ *
+ * @public
+ */
 export const locationEntityV1alpha1Validator =
   ajvCompiledJsonSchemaValidator(schema);

packages/catalog-model/src/kinds/ResourceEntityV1alpha1.ts

@@ -18,7 +18,15 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/Resource.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';
 
-/** @public */
+/**
+ * Backstage catalog Resource kind Entity. Represents infrastructure required to operate Components.
+ *
+ * @remarks
+ *
+ * See {@link https://backstage.io/docs/features/software-catalog/system-model}
+ *
+ * @public
+ */
 export interface ResourceEntityV1alpha1 extends Entity {
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
   kind: 'Resource';
@@ -30,6 +38,10 @@ export interface ResourceEntityV1alpha1 extends Entity {
   };
 }
 
-/** @public */
+/**
+ * {@link KindValidator} for {@link ResourceEntityV1alpha1}.
+ *
+ * @public
+ */
 export const resourceEntityV1alpha1Validator =
   ajvCompiledJsonSchemaValidator(schema);

packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts

@@ -18,7 +18,15 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/System.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';
 
-/** @public */
+/**
+ * Backstage catalog System kind Entity. Systems group Comopnents, Resources and APIs together.
+ *
+ * @remarks
+ *
+ * See {@link https://backstage.io/docs/features/software-catalog/system-model}
+ *
+ * @public
+ */
 export interface SystemEntityV1alpha1 extends Entity {
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
   kind: 'System';
@@ -28,6 +36,10 @@ export interface SystemEntityV1alpha1 extends Entity {
   };
 }
 
-/** @public */
+/**
+ * {@link KindValidator} for {@link SystemEntityV1alpha1}.
+ *
+ * @public
+ */
 export const systemEntityV1alpha1Validator =
   ajvCompiledJsonSchemaValidator(schema);

packages/catalog-model/src/kinds/TemplateEntityV1beta2.ts

@@ -19,7 +19,11 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/Template.v1beta2.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';
 
-/** @public */
+/**
+ * Backstage catalog Template kind Entity. Templates are used by the Scaffolder plugin to create new Components.
+ *
+ * @public
+ */
 export interface TemplateEntityV1beta2 extends Entity {
   apiVersion: 'backstage.io/v1beta2';
   kind: 'Template';
@@ -38,6 +42,10 @@ export interface TemplateEntityV1beta2 extends Entity {
   };
 }
 
-/** @public */
+/**
+ * {@link KindValidator} for {@link TemplateEntityV1beta2}.
+ *
+ * @public
+ */
 export const templateEntityV1beta2Validator =
   ajvCompiledJsonSchemaValidator(schema);

packages/catalog-model/src/kinds/UserEntityV1alpha1.ts

@@ -18,7 +18,11 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/User.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';
 
-/** @public */
+/**
+ * Backstage catalog User kind Entity.
+ *
+ * @public
+ */
 export interface UserEntityV1alpha1 extends Entity {
   apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
   kind: 'User';
@@ -32,6 +36,10 @@ export interface UserEntityV1alpha1 extends Entity {
   };
 }
 
-/** @public */
+/**
+ * {@link KindValidator} for {@link UserEntityV1alpha1}.
+ *
+ * @public
+ */
 export const userEntityV1alpha1Validator =
   ajvCompiledJsonSchemaValidator(schema);

packages/catalog-model/src/kinds/relations.ts

@@ -24,61 +24,115 @@ Naming rules for relations in priority order:
 
 /**
  * An ownership relation where the owner is usually an organizational
- * entity (user or group), and the other entity can be anything.
+ * entity (user or group), and the other entity can be anything. Reversed
+ * direction of {@link RELATION_OWNER_OF}.
  *
  * @public
  */
 export const RELATION_OWNED_BY = 'ownedBy';
-/** @public */
+
+/**
+ * A relationship from an owner to the owned entity. Reversed direction of
+ * {@link RELATION_OWNED_BY}.
+ *
+ * @public
+ */
 export const RELATION_OWNER_OF = 'ownerOf';
 
 /**
- * A relation with an API entity, typically from a component
+ * A relation with an API entity, typically from a component. Reversed direction of
+ * {@link RELATION_API_CONSUMED_BY}.
  *
  * @public
  */
 export const RELATION_CONSUMES_API = 'consumesApi';
-/** @public */
+
+/**
+ * A relation of an API being consumed, typically by a component. Reversed direction of
+ * {@link RELATION_CONSUMES_API}.
+ *
+ * @public
+ */
 export const RELATION_API_CONSUMED_BY = 'apiConsumedBy';
-/** @public */
+
+/**
+ * A relation from an API provider entity (typically a component) to the API. Reversed direction of
+ * {@link RELATION_API_PROVIDED_BY}.
+ *
+ * @public
+ */
 export const RELATION_PROVIDES_API = 'providesApi';
-/** @public */
+
+/**
+ * A relation from an API to its provider entity (typically a component). Reversed direction of
+ * {@link RELATION_PROVIDES_API}.
+ *
+ * @public
+ */
 export const RELATION_API_PROVIDED_BY = 'apiProvidedBy';
 
 /**
- * A relation denoting a dependency on another entity.
+ * A relation denoting a dependency on another entity. Reversed direction of
+ * {@link RELATION_DEPENDENCY_OF}.
  *
  * @public
  */
 export const RELATION_DEPENDS_ON = 'dependsOn';
-/** @public */
+
+/**
+ * A relation denoting a reverse dependency by another entity. Reversed direction of
+ * {@link RELATION_DEPENDS_ON}.
+ *
+ * @public
+ */
 export const RELATION_DEPENDENCY_OF = 'dependencyOf';
 
 /**
  * A parent/child relation to build up a tree, used for example to describe
- * the organizational structure between groups.
+ * the organizational structure between groups. Reversed direction of
+ * {@link RELATION_CHILD_OF}.
  *
  * @public
  */
 export const RELATION_PARENT_OF = 'parentOf';
-/** @public */
+
+/**
+ * A relation from a child to a parent entity, used for example to describe
+ * the organizational structure between groups. Reversed direction of
+ * {@link RELATION_PARENT_OF}.
+ *
+ * @public
+ */
 export const RELATION_CHILD_OF = 'childOf';
 
 /**
- * A membership relation, typically for users in a group.
+ * A membership relation, typically for users in a group. Reversed direction of
+ * {@link RELATION_HAS_MEMBER}.
  *
  * @public
  */
 export const RELATION_MEMBER_OF = 'memberOf';
-/** @public */
+
+/**
+ * A relation from a group to its member, typcally a user in a group. Reversed direction of
+ * {@link RELATION_MEMBER_OF}.
+ *
+ * @public
+ */
 export const RELATION_HAS_MEMBER = 'hasMember';
 
 /**
  * A part/whole relation, typically for components in a system and systems
- * in a domain.
+ * in a domain. Reversed direction of {@link RELATION_HAS_PART}.
  *
  * @public
  */
 export const RELATION_PART_OF = 'partOf';
-/** @public */
+
+/**
+ * A relation from a containing entity to a contained entity. Reversed direction of
+ * {@link RELATION_PART_OF}.
+ *
+ * @public
+ */
 export const RELATION_HAS_PART = 'hasPart';

packages/catalog-model/src/location/annotation.ts

@@ -14,11 +14,20 @@
  * limitations under the License.
  */
 
-/** @public */
+/**
+ * Constant storing location annotation.
+ *
+ * @public */
 export const LOCATION_ANNOTATION = 'backstage.io/managed-by-location';
-/** @public */
+/**
+ * Constant storing origin location annotation
+ *
+ * @public */
 export const ORIGIN_LOCATION_ANNOTATION =
   'backstage.io/managed-by-origin-location';
 
-/** @public */
+/**
+ * Contant storing source location annotation
+ *
+ * @public */
 export const SOURCE_LOCATION_ANNOTATION = 'backstage.io/source-location';

packages/catalog-model/src/location/helpers.ts

@@ -65,6 +65,8 @@ export function parseLocationReference(ref: string): {
 /**
  * Turns a location reference into its string form.
  *
+ * @remarks
+ *
  * Note that the input type is not `LocationSpec`, because we do not want to
  * conflate the string form with the additional properties of that type.
  *
@@ -90,6 +92,8 @@ export function stringifyLocationReference(ref: {
 /**
  * Returns the source code location of the Entity, to the extent that one exists.
  *
+ * @remarks
+ *
  * If the returned location type is of type 'url', the target should be readable at least
  * using the UrlReader from `@backstage/backend-common`. If it is not of type 'url', the caller
  * needs to have explicit handling of each location type or signal that it is not supported.

packages/catalog-model/src/location/types.ts

@@ -14,17 +14,28 @@
  * limitations under the License.
  */
 
-/** @public */
+/**
+ * Holds the entity location information.
+ *
+ * @remarks
+ *
+ *  `presence` flag: when using repo importer plugin, location is being created before the component yaml file is merged to the main branch.
+ *  This flag is then set to indicate that the file can be not present.
+ *  default value: 'required'.
+ *
+ * @public
+ */
 export type LocationSpec = {
   type: string;
   target: string;
-  // When using repo importer plugin, location is being created before the component yaml file is merged to the main branch.
-  // This flag is then set to indicate that the file can be not present.
-  // default value: 'required'.
   presence?: 'optional' | 'required';
 };
 
-/** @public */
+/**
+ * Entity location for a specific entity.
+ *
+ * @public
+ */
 export type Location = {
   id: string;
 } & LocationSpec;

packages/catalog-model/src/location/validation.ts

@@ -18,8 +18,10 @@ import * as yup from 'yup';
 import { LocationSpec, Location } from './types';
 
 /**
+ * Deprecated.
+ *
  * @public
- * @deprecated Use JSONSchema or validators instead.
+ * @deprecated Use {@link JSONSchema} or validators instead.
  */
 export const locationSpecSchema: yup.SchemaOf<LocationSpec> = yup
   .object({
@@ -31,8 +33,10 @@ export const locationSpecSchema: yup.SchemaOf<LocationSpec> = yup
   .required();
 
 /**
+ * Deprecated.
+ *
  * @public
- * @deprecated Use JSONSchema or validators instead.
+ * @deprecated Use {@link JSONSchema} or validators instead.
  */
 export const locationSchema: yup.SchemaOf<Location> = yup
   .object({
@@ -45,8 +49,10 @@ export const locationSchema: yup.SchemaOf<Location> = yup
   .required();
 
 /**
+ * Deprecated.
+ *
  * @public
- * @deprecated Use JSONSchema or validators instead.
+ * @deprecated Use {@link JSONSchema} or validators instead.
  */
 export const analyzeLocationSchema: yup.SchemaOf<{ location: LocationSpec }> =
   yup

packages/catalog-model/src/types.ts

@@ -17,7 +17,11 @@
 import { JsonValue } from '@backstage/config';
 import { JSONSchema7 } from 'json-schema';
 
-/** @public */
+/**
+ * JSONSchema extendable by arbitrary JSON attributes
+ *
+ * @public
+ */
 export type JSONSchema = JSONSchema7 & { [key in string]?: JsonValue };
 
 /**
@@ -35,7 +39,9 @@ export type EntityName = {
  * A reference by name to an entity, either as a compact string representation,
  * or as a compound reference structure.
  *
- * The string representation is on the form [<kind>:][<namespace>/]<name>.
+ * @remarks
+ *
+ * The string representation is on the form `[<kind>:][<namespace>/]<name>`.
  *
  * Left-out parts of the reference need to be handled by the application,
  * either by rejecting the reference or by falling back to default values.

packages/catalog-model/src/validation/entityEnvelopeSchemaValidator.ts

@@ -25,6 +25,8 @@ import { compileAjvSchema, throwAjvError } from './ajv';
  * if it matches that schema, or throws a {@link globals#TypeError} describing the
  * errors.
  *
+ * @remarks
+ *
  * Note that this validator is only meant for applying the base schema checks;
  * it does not take custom policies or additional processor based validation
  * into account.
@@ -33,13 +35,15 @@ import { compileAjvSchema, throwAjvError } from './ajv';
  * own, it may contain `$ref` references to the following, which are resolved
  * automatically for you:
  *
- * - EntityEnvelope
- * - Entity
- * - EntityMeta
- * - common#<id>
+ * - {@link EntityEnvelope}
+ * - {@link Entity}
+ * - {@link EntityMeta}
+ * - `common#<id>`
+ *
+ * See also {@link https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema}
  *
  * @public
- * @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema
+ *
  */
 export function entityEnvelopeSchemaValidator<
   T extends EntityEnvelope = EntityEnvelope,

packages/catalog-model/src/validation/entityKindSchemaValidator.ts

@@ -24,6 +24,8 @@ import { compileAjvSchema, throwAjvError } from './ajv';
  * schema apiVersion/kind didn't apply to that data, or throws a
  * {@link globals#TypeError} describing actual errors.
  *
+ * @remarks
+ *
  * This validator is highly specialized, in that it has special treatment of
  * the `kind` and `apiVersion` root keys. This only works if your schema has
  * their rule set to `"enum"`:
@@ -47,13 +49,16 @@ import { compileAjvSchema, throwAjvError } from './ajv';
  * The given schema may contain `$ref` references to the following, which are
  * resolved automatically for you:
  *
- * - EntityEnvelope
- * - Entity
- * - EntityMeta
- * - common#<id>
+ * - {@link Entity}
+ *
+ * - {@link EntityEnvelope}
+ *
+ * - {@link EntityMeta}
+ *
+ * - `common#<id>`
+ * @see {@link https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema}
  *
  * @public
- * @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema
  */
 export function entityKindSchemaValidator<T extends Entity>(
   schema: unknown,

packages/catalog-model/src/validation/entitySchemaValidator.ts

@@ -24,21 +24,23 @@ import { compileAjvSchema, throwAjvError } from './ajv';
  * returns that data cast to an {@link Entity} (or the given subtype) if it
  * matches that schema, or throws a {@link globals#TypeError} describing the errors.
  *
+ * @remarks
+ *
  * Note that this validator is only meant for applying the base schema checks;
  * it does not take custom policies or additional processor based validation
  * into account.
  *
- * By default, the plain `Entity` schema is used. If you pass in your own, it
+ * By default, the plain {@link Entity} schema is used. If you pass in your own, it
  * may contain `$ref` references to the following, which are resolved
  * automatically for you:
  *
- * - EntityEnvelope
- * - Entity
- * - EntityMeta
- * - common#<id>
+ * - {@link Entity}
+ * - {@link EntityEnvelope}
+ * - {@link EntityMeta}
+ * - `common#<id>`
  *
  * @public
- * @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema
+ * @see {@link https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema}
  */
 export function entitySchemaValidator<T extends Entity = Entity>(
   schema?: unknown,

packages/catalog-model/src/validation/makeValidator.ts

@@ -30,7 +30,11 @@ const defaultValidators: Validators = {
   isValidTag: CommonValidatorFunctions.isValidTag,
 };
 
-/** @public */
+/**
+ * Creates a {@link Validators} object from `overrides`, with default values taken from {@link KubernetesValidatorFunctions}
+ *
+ * @public
+ */
 export function makeValidator(overrides: Partial<Validators> = {}): Validators {
   return {
     ...defaultValidators,

packages/catalog-model/src/validation/types.ts

@@ -14,7 +14,11 @@
  * limitations under the License.
  */
 
-/** @public */
+/**
+ * Type alias for implementing validators of various entity objects.
+ *
+ * @public
+ */
 export type Validators = {
   isValidApiVersion(value: unknown): boolean;
   isValidKind(value: unknown): boolean;