[Saved Objects] Documents intended use of removeReferencesTo (#153711)

## Summary
Updates comments for `removeReferencesTo` (SO Repository) and
`authorizeRemoveReferences` (SO Security Extension) methods with remarks
regarding the intended use and authorization.

Currently the only use case for `removeReferencesTo` is the delete
method of the tags client. If the authorization check is changed to
authorize an update for each referencing object, lingering references in
objects which the user is not authorized to update may be left behind
when a tag is deleted. We will leave the current implementation in place
until a decision about if & how to manage referential integrity occurs.

This PR documents the current intended use case for `removeReferencesTo`
as: "to provide clean up of any references to an object which is being
deleted (e.g. deleting a tag)."

See issue #135259 and discussion
[here](#135259 (comment)),
for background.

packages/core/saved-objects/core-saved-objects-api-server/src/saved_objects_repository.ts

@@ -306,9 +306,17 @@ export interface ISavedObjectsRepository {
   /**
    * Updates all objects containing a reference to the given {type, id} tuple to remove the said reference.
    *
-   * @remarks Will throw a conflict error if the `update_by_query` operation returns any failure. In that case
-   *          some references might have been removed, and some were not. It is the caller's responsibility
-   *          to handle and fix this situation if it was to happen.
+   * @remarks
+   * Will throw a conflict error if the `update_by_query` operation returns any failure. In that case some
+   * references might have been removed, and some were not. It is the caller's responsibility to handle and fix
+   * this situation if it was to happen.
+   *
+   * Intended use is to provide clean up of any references to an object which is being deleted (e.g. deleting
+   * a tag). See discussion here: https://github.com/elastic/kibana/issues/135259#issuecomment-1482515139
+   *
+   * When security is enabled, authorization for this method is based only on authorization to delete the object
+   * represented by the {type, id} tuple. Therefore it is recommended only to call this method for the intended
+   * use case.
    *
    * @param {string} type - the type of the object to remove references to
    * @param {string} id - the ID of the object to remove references to

packages/core/saved-objects/core-saved-objects-server/src/extensions/security.ts

@@ -407,7 +407,12 @@ export interface ISavedObjectsSecurityExtension {
   ) => Promise<CheckAuthorizationResult<A>>;
 
   /**
-   * Performs authorization for the REMOVE_REFERENCES security action
+   * Performs authorization for the REMOVE_REFERENCES security action. Checks for authorization
+   * to delete the object to which references are to be removed. In reality, the operation is an
+   * UPDATE to all objects that reference the given object, but the intended use for the
+   * removeReferencesTo method is to clean up any references to an object which is being deleted
+   * (e.g. deleting a tag).
+   * See discussion here: https://github.com/elastic/kibana/issues/135259#issuecomment-1482515139
    * @param params the namespace and object to authorize
    * @returns CheckAuthorizationResult - the resulting authorization level and authorization map
    */