chore(codebuild): improve the doc for subnetSelection (#26592)

If `vpc` is specified with `subnetSelection` undefined, according to this:

https://github.com/aws/aws-cdk/blob/d5c64cba9aa8af8e92af4893657d144ef8e4f873/packages/aws-cdk-lib/aws-ec2/lib/vpc.ts#L655-L660

CDK will look for `PRIVATE_WITH_EGRESS`, `PRIVATE_ISOLATED`, and `PUBLIC` in order. If customer does not have `PRIVATE_WITH_EGRESS` subnets, they will need to have vpc endpoints if they need to access AWS services such as AWS Secrets Manager or Amazon ECR.

This PR improves the doc to clarify.


Closes #<issue number here>.

----

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

Author: pahud

packages/aws-cdk-lib/aws-codebuild/lib/project.ts

@@ -616,9 +616,18 @@ export interface CommonProjectProps {
   /**
    * Where to place the network interfaces within the VPC.
    *
-   * Only used if 'vpc' is supplied.
+   * To access AWS services, your CodeBuild project needs to be in one of the following types of subnets:
+   *
+   * 1. Subnets with access to the internet (of type PRIVATE_WITH_EGRESS).
+   * 2. Private subnets unconnected to the internet, but with [VPC endpoints](https://docs.aws.amazon.com/codebuild/latest/userguide/use-vpc-endpoints-with-codebuild.html) for the necessary services.
+   *
+   * If you don't specify a subnet selection, the default behavior is to use PRIVATE_WITH_EGRESS subnets first if they exist,
+   * then PRIVATE_WITHOUT_EGRESS, and finally PUBLIC subnets. If your VPC doesn't have PRIVATE_WITH_EGRESS subnets but you need
+   * AWS service access, add VPC Endpoints to your private subnets.
+   *
+   * @see https://docs.aws.amazon.com/codebuild/latest/userguide/vpc-support.html for more details.
    *
-   * @default - All private subnets.
+   * @default - private subnets if available else public subnets
    */
   readonly subnetSelection?: ec2.SubnetSelection;