developer guide added in comments (#6058)

Author: Fred1155

test/v2-migration-tests/src/test/resources/software/amazon/awssdk/v2migrationtests/maven-nocompile/after/src/main/java/foo/bar/S3Transforms.java

@@ -41,19 +41,19 @@ public class S3Transforms {
     String key;
 
     void s3Pojos() {
-        MultiFactorAuthentication mfa = /*AWS SDK for Java v2 migration: v2 does not have a MultiFactorAuthentication POJO. Please manually set the String value on the request POJO.*/new MultiFactorAuthentication("serialNum", "token");
+        MultiFactorAuthentication mfa = /*AWS SDK for Java v2 migration: v2 does not have a MultiFactorAuthentication POJO. Please manually set the String value on the request POJO. Please reference https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3-client.html#V1-MultifactorAuthentication*/new MultiFactorAuthentication("serialNum", "token");
 
         DeleteObjectRequest deleteVersionRequest =
             DeleteObjectRequest.builder().bucket("bucket").key("key").versionId("id").mfa(mfa)
                 .build();
     }
 
     void setBucketAcl() {
-        /*AWS SDK for Java v2 migration: Transform for AccessControlList and CannedAccessControlList not supported. In v2, CannedAccessControlList is replaced by BucketCannedACL for buckets and ObjectCannedACL for objects.*/s3.setBucketAcl(bucket, CannedAccessControlList.AuthenticatedRead);
+        /*AWS SDK for Java v2 migration: Transform for AccessControlList and CannedAccessControlList not supported. In v2, CannedAccessControlList is replaced by BucketCannedACL for buckets and ObjectCannedACL for objects. Please reference https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3-client.html#V1-AccessControlList*/s3.setBucketAcl(bucket, CannedAccessControlList.AuthenticatedRead);
     }
 
     void setObjectAcl() {
-        /*AWS SDK for Java v2 migration: Transform for AccessControlList and CannedAccessControlList not supported. In v2, CannedAccessControlList is replaced by BucketCannedACL for buckets and ObjectCannedACL for objects.*/s3.setObjectAcl(bucket, key, CannedAccessControlList.PublicRead);
+        /*AWS SDK for Java v2 migration: Transform for AccessControlList and CannedAccessControlList not supported. In v2, CannedAccessControlList is replaced by BucketCannedACL for buckets and ObjectCannedACL for objects. Please reference https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3-client.html#V1-AccessControlList*/s3.setObjectAcl(bucket, key, CannedAccessControlList.PublicRead);
     }
 
     void upload_streamWithLiteralLength(S3TransferManager tm) {

test/v2-migration-tests/src/test/resources/software/amazon/awssdk/v2migrationtests/maven/after/src/main/java/foo/bar/S3.java

@@ -373,7 +373,7 @@ private void setBucketConfigs(S3Client s3, String bucket) {
         s3.putBucketInventoryConfiguration(PutBucketInventoryConfigurationRequest.builder().bucket(bucket).inventoryConfiguration(InventoryConfiguration.builder()
             .build())
             .build());
-        /*AWS SDK for Java v2 migration: Transform for setBucketLifecycleConfiguration method not supported. Please manually migrate your code by using builder pattern, updating from BucketLifecycleConfiguration.Rule to LifecycleRule, StorageClass to TransitionStorageClass, and adjust imports and names.*/s3.putBucketLifecycleConfiguration(PutBucketLifecycleConfigurationRequest.builder().bucket(bucket).lifecycleConfiguration(BucketLifecycleConfiguration.builder()
+        /*AWS SDK for Java v2 migration: Transform for setBucketLifecycleConfiguration method not supported. Please manually migrate your code by using builder pattern, updating from BucketLifecycleConfiguration.Rule to LifecycleRule, StorageClass to TransitionStorageClass, and adjust imports and names. Please reference https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3-client.html#V1-setBucketLifecycleConfiguration*/s3.putBucketLifecycleConfiguration(PutBucketLifecycleConfigurationRequest.builder().bucket(bucket).lifecycleConfiguration(BucketLifecycleConfiguration.builder()
         .build())
         .build());
         s3.putBucketMetricsConfiguration(PutBucketMetricsConfigurationRequest.builder().bucket(bucket).metricsConfiguration(MetricsConfiguration.builder()
@@ -388,7 +388,7 @@ private void setBucketConfigs(S3Client s3, String bucket) {
         s3.putBucketReplication(PutBucketReplicationRequest.builder().bucket(bucket).replicationConfiguration(ReplicationConfiguration.builder()
             .build())
             .build());
-        /*AWS SDK for Java v2 migration: Transform for setBucketTaggingConfiguration method not supported. Please manually migrate your code by using builder pattern, replacing TagSet.setTag() with .tagSet(Arrays.asList(Tag.builder())), and use Tagging instead of BucketTaggingConfiguration, and adjust imports and names.*/s3.putBucketTagging(PutBucketTaggingRequest.builder().bucket(bucket).tagging(Tagging.builder()
+        /*AWS SDK for Java v2 migration: Transform for setBucketTaggingConfiguration method not supported. Please manually migrate your code by using builder pattern, replacing TagSet.setTag() with .tagSet(Arrays.asList(Tag.builder())), and use Tagging instead of BucketTaggingConfiguration, and adjust imports and names. Please reference https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3-client.html#V1-setBucketTaggingConfiguration*/s3.putBucketTagging(PutBucketTaggingRequest.builder().bucket(bucket).tagging(Tagging.builder()
         .build())
         .build());
         s3.putBucketWebsite(PutBucketWebsiteRequest.builder().bucket(bucket).websiteConfiguration(WebsiteConfiguration.builder()

test/v2-migration-tests/src/test/resources/software/amazon/awssdk/v2migrationtests/maven/after/src/main/java/foo/bar/S3RequestConstructor.java

@@ -398,7 +398,7 @@ public void requestconstructor() {
                 .build());
 
 
-        /*AWS SDK for Java v2 migration: Transform for setBucketLifecycleConfiguration method not supported. Please manually migrate your code by using builder pattern, updating from BucketLifecycleConfiguration.Rule to LifecycleRule, StorageClass to TransitionStorageClass, and adjust imports and names.*/s3.putBucketLifecycleConfiguration(
+        /*AWS SDK for Java v2 migration: Transform for setBucketLifecycleConfiguration method not supported. Please manually migrate your code by using builder pattern, updating from BucketLifecycleConfiguration.Rule to LifecycleRule, StorageClass to TransitionStorageClass, and adjust imports and names. Please reference https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3-client.html#V1-setBucketLifecycleConfiguration*/s3.putBucketLifecycleConfiguration(
         PutBucketLifecycleConfigurationRequest.builder().bucket(bucketName).lifecycleConfiguration(BucketLifecycleConfiguration.builder()
             .build())
             .build());
@@ -433,7 +433,7 @@ public void requestconstructor() {
                 .build())
                 .build());
 
-        /*AWS SDK for Java v2 migration: Transform for setBucketTaggingConfiguration method not supported. Please manually migrate your code by using builder pattern, replacing TagSet.setTag() with .tagSet(Arrays.asList(Tag.builder())), and use Tagging instead of BucketTaggingConfiguration, and adjust imports and names.*/s3.putBucketTagging(
+        /*AWS SDK for Java v2 migration: Transform for setBucketTaggingConfiguration method not supported. Please manually migrate your code by using builder pattern, replacing TagSet.setTag() with .tagSet(Arrays.asList(Tag.builder())), and use Tagging instead of BucketTaggingConfiguration, and adjust imports and names. Please reference https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3-client.html#V1-setBucketTaggingConfiguration*/s3.putBucketTagging(
         PutBucketTaggingRequest.builder().bucket(bucketName).tagging(Tagging.builder()
             .build())
             .build());

v2-migration/src/main/java/software/amazon/awssdk/v2migration/S3AddImportsAndComments.java

@@ -90,45 +90,44 @@ public J.MethodInvocation visitMethodInvocation(J.MethodInvocation method, Execu
             if (isSetObjectAcl || isSetBucketAcl) {
                 removeV1S3ModelImport("CannedAccessControlList");
                 maybeAddV2CannedAclImport(method.getArguments(), isSetObjectAcl, isSetBucketAcl);
-
-                // TODO: add the developer guide link in the comments once the doc is published.
                 String comment = "Transform for AccessControlList and CannedAccessControlList not supported. "
                                  + "In v2, CannedAccessControlList is replaced by BucketCannedACL for buckets and "
-                                 + "ObjectCannedACL for objects.";
+                                 + "ObjectCannedACL for objects." + devGuideLink("AccessControlList");
                 return method.withComments(createComments(comment));
             }
             if (LIST_NEXT_BATCH_OBJECTS.matches(method)) {
-                // TODO: add the developer guide link in the comments once the doc is published.
                 String comment = "Transform for listNextBatchOfObjects method not supported. "
                                  + "listNextBatchOfObjects() only exists in SDK v1, for SDK v2 use either "
                                  + "listObjectsV2Paginator().stream() for automatic pagination"
                                  + " or manually handle pagination with listObjectsV2() and nextToken in the response for more "
-                                 + "control";
+                                 + "control" + devGuideLink(method.getSimpleName());
                 return method.withComments(createComments(comment));
             }
             if (LIST_NEXT_BATCH_VERSIONS.matches(method)) {
-                // TODO: add the developer guide link in the comments once the doc is published.
                 String comment = "Transform for listNextBatchOfVersions method not supported."
                                 + "listNextBatchOfVersions() only exists in SDK v1, for SDK v2 use either "
                                 + "listObjectVersionsPaginator().stream for automatic pagination"
-                                + " or manually handle pagination with listObjectVersions() and VersionIdMarker/KeyMarker. ";
+                                + " or manually handle pagination with listObjectVersions() and VersionIdMarker/KeyMarker."
+                                + devGuideLink(method.getSimpleName());
                 return method.withComments(createComments(comment));
             }
             if (SET_REGION.matches(method)) {
                 String comment = "Transform for setRegion method not supported. Please manually "
-                                 + "migrate your code by configuring the region in the s3 client builder";
+                                 + "migrate your code by configuring the region in the s3 client builder"
+                                 + devGuideLink(method.getSimpleName());
                 return method.withComments(createComments(comment));
             }
             if (SET_S3CLIENT_OPTIONS.matches(method)) {
                 String comment = "Transform for setS3ClientOptions method not supported. Please manually "
                                  + "migrate setS3ClientOptions by configuring the equivalent settings in "
-                                 + "S3Configuration.builder() when building your S3Client.";
+                                 + "S3Configuration.builder() when building your S3Client."
+                                 + devGuideLink(method.getSimpleName());
                 return method.withComments(createComments(comment));
             }
             if (SELECT_OBJECT_CONTENT.matches(method)) {
                 String comment = "Note: selectObjectContent is only supported in AWS SDK v2 with S3AsyncClient. "
                                  + "Please manually migrate to event-based response handling using "
-                                 + "SelectObjectContentEventStream";
+                                 + "SelectObjectContentEventStream" + devGuideLink(method.getSimpleName());
                 return method.withComments(createComments(comment));
             }
 
@@ -156,15 +155,15 @@ public J.MethodInvocation visitMethodInvocation(J.MethodInvocation method, Execu
             }
 
             if (SET_BUCKET_LOGGING.matches(method)) {
-                // TODO: add the developer guide link in the comments once the doc is published.
                 removeV1S3ModelImport("BucketLoggingConfiguration");
                 addV2S3ModelImport("BucketLoggingStatus");
                 addV2S3ModelImport("LoggingEnabled");
 
                 String comment = "Transform for setBucketLoggingConfiguration method not "
                                  + "supported. The method is renamed to putBucketLogging. Please manually migrate your code by "
                                  + "replacing BucketLoggingConfiguration with BucketLoggingStatus and LoggingEnabled builders, "
-                                 + "and updating the method name and parameters";
+                                 + "and updating the method name and parameters"
+                                 + devGuideLink(method.getSimpleName());
                 return method.withComments(createComments(comment));
             }
 
@@ -177,20 +176,18 @@ public J.MethodInvocation visitMethodInvocation(J.MethodInvocation method, Execu
             }
 
             if (SET_LIFECYCLE_CONFIGURATION.matches(method)) {
-                // TODO: add the developer guide link in the comments once the doc is published.
                 String comment = "Transform for setBucketLifecycleConfiguration method not supported. Please manually migrate"
                                  + " your code by using builder pattern, updating from BucketLifecycleConfiguration.Rule to "
                                  + "LifecycleRule, StorageClass to TransitionStorageClass, and adjust "
-                                 + "imports and names.";
+                                 + "imports and names." + devGuideLink(method.getSimpleName());
                 return method.withComments(createComments(comment));
             }
 
             if (SET_TAGGING_CONFIGURATION.matches(method)) {
-                // TODO: add the developer guide link in the comments once the doc is published.
                 String comment = "Transform for setBucketTaggingConfiguration method not supported. Please manually migrate"
                                  + " your code by using builder pattern, replacing TagSet.setTag() with .tagSet(Arrays.asList"
                                  + "(Tag.builder())), and use Tagging instead of BucketTaggingConfiguration, and adjust imports"
-                                 + " and names.";
+                                 + " and names." + devGuideLink(method.getSimpleName());
                 return method.withComments(createComments(comment));
             }
 
@@ -209,21 +206,23 @@ public J.NewClass visitNewClass(J.NewClass newClass, ExecutionContext ctx) {
             if (type.isAssignableFrom(MULTI_FACTOR_AUTH) || setBucketVersionUsingMFA) {
                 removeV1S3ModelImport("MultiFactorAuthentication");
                 String comment = "v2 does not have a MultiFactorAuthentication POJO. Please manually set the String value on "
-                                 + "the request POJO.";
+                                 + "the request POJO." + devGuideLink("MultifactorAuthentication");
                 return newClass.withComments(createComments(comment));
             }
 
             if (type.isAssignableFrom(GET_OBJECT_REQUEST) && newClass.getArguments().size() == 1) {
                 removeV1S3ModelImport("S3ObjectId");
                 String comment = "v2 does not have S3ObjectId class. Please manually migrate the code by setting the configs "
-                                 + "directly into the request builder pattern.";
+                                 + "directly into the request builder pattern."
+                                 + devGuideLink("getObject-using-V1s-S3ObjectId");
                 return newClass.withComments(createComments(comment));
             }
 
             if (type.isAssignableFrom(INITIATE_MPU) && newClass.getArguments().size() == 3) {
                 String comment = "Transform for ObjectMetadata in initiateMultipartUpload() method is not supported. Please "
                                  + "manually migrate your code by replacing ObjectMetadata with individual setter methods "
-                                 + "or metadata map in the request builder.";
+                                 + "or metadata map in the request builder."
+                                 + devGuideLink("initiateMultipartUpload");
                 return newClass.withComments(createComments(comment));
             }
 
@@ -242,12 +241,12 @@ public J.NewClass visitNewClass(J.NewClass newClass, ExecutionContext ctx) {
             }
 
             if (type.isAssignableFrom(BUCKET_NOTIFICATION_CONFIG)) {
-                // TODO: add the developer guide link in the comments once the doc is published.
                 String comment = "Transform for BucketNotificationConfiguration class is not supported. "
                                  + "BucketNotificationConfiguration is renamed to NotificationConfiguration. There is no common"
                                  + " abstract class for lambdaFunction/topic/queue configurations. Use specific builders "
                                  + "instead of addConfiguration() to add configurations. Change the vararg arguments or EnumSet "
-                                 + "in specific configurations constructor to List<String> in v2";
+                                 + "in specific configurations constructor to List<String> in v2"
+                                 + devGuideLink("BucketNotificationConfiguration");
                 return newClass.withComments(createComments(comment));
             }
 
@@ -277,5 +276,11 @@ private void removeV1S3ModelImport(String className) {
         private void addV2S3ModelImport(String className) {
             doAfterVisit(new AddImport<>(V2_S3_MODEL_PKG + className, null, false));
         }
+
+        private String devGuideLink(String name) {
+            String prefix = " Please reference https://docs.aws.amazon"
+                            + ".com/sdk-for-java/latest/developer-guide/migration-s3-client.html#V1-";
+            return prefix + name;
+        }
     }
 }