docs(core): update CustomResource documentation (#18156)

Make the use and implications of CustomResources in the `core` library
a bit more clear.

Strongly direct users to the `custom-resources` module.


----

*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/core/lib/custom-resource-provider/custom-resource-provider.ts

@@ -111,8 +111,26 @@ export enum CustomResourceProviderRuntime {
 }
 
 /**
- * An AWS-Lambda backed custom resource provider.
+ * An AWS-Lambda backed custom resource provider, for CDK Construct Library constructs
  *
+ * This is a provider for `CustomResource` constructs, backed by an AWS Lambda
+ * Function. It only supports NodeJS runtimes.
+ *
+ * **This is not a generic custom resource provider class**. It is specifically
+ * intended to be used only by constructs in the AWS CDK Construct Library, and
+ * only exists here because of reverse dependency issues (for example, it cannot
+ * use `iam.PolicyStatement` objects, since the `iam` library already depends on
+ * the CDK `core` library and we cannot have cyclic dependencies).
+ *
+ * If you are not writing constructs for the AWS Construct Library, you should
+ * use the `Provider` class in the `custom-resources` module instead, which has
+ * a better API and supports all Lambda runtimes, not just Node.
+ *
+ * N.B.: When you are writing Custom Resource Providers, there are a number of
+ * lifecycle events you have to pay attention to. These are documented in the
+ * README of the `custom-resources` module. Be sure to give the documentation
+ * in that module a read, regardless of whether you end up using the Provider
+ * class in there or this one.
  */
 export class CustomResourceProvider extends CoreConstruct {
   /**

packages/@aws-cdk/core/lib/custom-resource.ts

@@ -98,11 +98,25 @@ export interface CustomResourceProps {
 }
 
 /**
- * Custom resource that is implemented using a Lambda
+ * Instantiation of a custom resource, whose implementation is provided a Provider
  *
- * As a custom resource author, you should be publishing a subclass of this class
- * that hides the choice of provider, and accepts a strongly-typed properties
- * object with the properties your provider accepts.
+ * This class is intended to be used by construct library authors. Application
+ * builder should not be able to tell whether or not a construct is backed by
+ * a custom resource, and so the use of this class should be invisible.
+ *
+ * Instead, construct library authors declare a custom construct that hides the
+ * choice of provider, and accepts a strongly-typed properties object with the
+ * properties your provider accepts.
+ *
+ * Your custom resource provider (identified by the `serviceToken` property)
+ * can be one of 4 constructs:
+ *
+ * - If you are authoring a construct library or application, we recommend you
+ *   use the `Provider` class in the `custom-resources` module.
+ * - If you are authoring a construct for the CDK's AWS Construct Library,
+ *   you should use the `CustomResourceProvider` construct in this package.
+ * - If you want full control over the provider, you can always directly use
+ *   a Lambda Function or SNS Topic by passing the ARN into `serviceToken`.
  *
  * @resource AWS::CloudFormation::CustomResource
  */