permission-node: separate doc comment summaries with @remarks tag

Signed-off-by: Mike Lewis <mtlewis@users.noreply.github.com>

plugins/permission-node/src/index.ts

@@ -19,7 +19,6 @@
  *
  * @packageDocumentation
  */
-
 export * from './integration';
 export * from './policy';
 export * from './types';

plugins/permission-node/src/integration/createConditionExports.ts

@@ -49,7 +49,11 @@ export type Conditions<
 
 /**
  * Creates the recommended condition-related exports for a given plugin based on the built-in
- * {@link PermissionRule}s it supports. It returns a `conditions` object containing a
+ * {@link PermissionRule}s it supports.
+ *
+ * @remarks
+ *
+ * The function returns a `conditions` object containing a
  * {@link @backstage/plugin-permission-common#PermissionCondition} factory for each of the
  * supplied {@link PermissionRule}s, along with a `createConditions` function which builds the
  * wrapper object needed to enclose conditions when authoring {@link PermissionPolicy} implementations.

plugins/permission-node/src/integration/createConditionFactory.ts

@@ -19,6 +19,8 @@ import { PermissionRule } from '../types';
 /**
  * Creates a condition factory function for a given authorization rule and parameter types.
  *
+ * @remarks
+ *
  * For example, an isEntityOwner rule for catalog entities might take an array of entityRef strings.
  * The rule itself defines _how_ to check a given resource, whereas a condition also includes _what_
  * to verify.

plugins/permission-node/src/integration/createPermissionIntegrationRouter.ts

@@ -97,6 +97,8 @@ const applyConditions = <TResource>(
  * conditional authorization for their resources should add the router created by this function
  * to their express app inside their `createRouter` implementation.
  *
+ * @remarks
+ *
  * To make this concrete, we can use the Backstage software catalog as an example. The catalog has
  * conditional rules around access to specific _entities_ in the catalog. The _type_ of resource is
  * captured here as `resourceType`, a string identifier (`catalog-entity` in this example) that can

plugins/permission-node/src/policy/types.ts

@@ -25,9 +25,12 @@ import { BackstageIdentity } from '@backstage/plugin-auth-backend';
 /**
  * An authorization request to be evaluated by the {@link PermissionPolicy}.
  *
+ * @remarks
+ *
  * This differs from {@link @backstage/permission-common#AuthorizeRequest} in that `resourceRef`
  * should never be provided. This forces policies to be written in a way that's compatible with
  * filtering collections of resources at data load time.
+ *
  * @public
  */
 export type PolicyAuthorizeRequest = Omit<AuthorizeRequest, 'resourceRef'>;
@@ -35,6 +38,8 @@ export type PolicyAuthorizeRequest = Omit<AuthorizeRequest, 'resourceRef'>;
 /**
  * A conditional result to an authorization request, returned by the {@link PermissionPolicy}.
  *
+ * @remarks
+ *
  * This indicates that the policy allows authorization for the request, given that the returned
  * conditions hold when evaluated. The conditions will be evaluated by the corresponding plugin
  * which knows about the referenced permission rules.
@@ -54,6 +59,7 @@ export type ConditionalPolicyResult = {
 
 /**
  * The result of evaluating an authorization request with a {@link PermissionPolicy}.
+ *
  * @public
  */
 export type PolicyResult =
@@ -63,6 +69,8 @@ export type PolicyResult =
 /**
  * A policy to evaluate authorization requests for any permissioned action performed in Backstage.
  *
+ * @remarks
+ *
  * This takes as input a permission and an optional Backstage identity, and should return ALLOW if
  * the user is permitted to execute that action; otherwise DENY. For permissions relating to
  * resources, such a catalog entities, a conditional response can also be returned. This states
@@ -71,6 +79,7 @@ export type PolicyResult =
  * Conditions are a rule, and parameters to evaluate against that rule. For example, the rule might
  * be `isOwner` and the parameters a collection of entityRefs; if one of the entityRefs matches
  * the `owner` field on a catalog entity, this would resolve to ALLOW.
+ *
  * @public
  */
 export interface PermissionPolicy {

plugins/permission-node/src/types.ts

@@ -20,6 +20,8 @@ import type { PermissionCriteria } from '@backstage/plugin-permission-common';
  * A conditional rule that can be provided in an
  * {@link @backstage/permission-common#AuthorizeResult} response to an authorization request.
  *
+ * @remarks
+ *
  * Rules can either be evaluated against a resource loaded in memory, or used as filters when
  * loading a collection of resources from a data source. The `apply` and `toQuery` methods implement
  * these two concepts.
@@ -27,6 +29,7 @@ import type { PermissionCriteria } from '@backstage/plugin-permission-common';
  * The two operations should always have the same logical result. If they don’t, the effective
  * outcome of an authorization operation will sometimes differ depending on how the authorization
  * check was performed.
+ *
  * @public
  */
 export type PermissionRule<