docs(iam): explain service principal behavior with feature flag (#25484)

There recently was some confusion on how CDK calculates service principal names. Will it add region-specific suffixes, will it not?

It depends on a feature flag; document that now.

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: rix0rrr

packages/aws-cdk-lib/aws-iam/lib/principals.ts

@@ -513,16 +513,25 @@ export interface ServicePrincipalOpts {
 }
 
 /**
- * An IAM principal that represents an AWS service (i.e. sqs.amazonaws.com).
+ * An IAM principal that represents an AWS service (i.e. `sqs.amazonaws.com`).
  */
 export class ServicePrincipal extends PrincipalBase {
   /**
-   * Translate the given service principal name based on the region it's used in.
+   * Return the service principal name based on the region it's used in.
    *
-   * For example, for Chinese regions this may (depending on whether that's necessary
-   * for the given service principal) append `.cn` to the name.
+   * Some service principal names used to be different for different partitions,
+   * and some were not. This method would return the appropriate region-specific
+   * service principal name, getting that information from the `region-info`
+   * module.
    *
-   * The `region-info` module is used to obtain this information.
+   * These days all service principal names are standardized, and they are all
+   * of the form `<servicename>.amazonaws.com`.
+   *
+   * If the feature flag `@aws-cdk/aws-iam:standardizedServicePrincipals` is set, this
+   * method will always return its input. If this feature flag is not set, this
+   * method will perform the legacy behavior, which appends the region-specific
+   * domain suffix for some select services (for example, it would append `.cn`
+   * to some service principal names).
    *
    * @example
    * const principalName = iam.ServicePrincipal.servicePrincipalName('ec2.amazonaws.com');