Add code example links to individual method documentation in API refs guide #6626

S-Saranya1 · 2025-12-15T22:58:36Z

Add code examples near the individual method documentation in Java SDK API Refs guide

Motivation and Context

Enhance the Java SDK API Refs documentation to include code examples.

Modifications

Added createLinkToCodeExample method to DocumentationUtils.java to generate code example links from example-meta.json
Updated OperationDocProvider.java which is in codegen and responsible for generating Javadoc documentation for individual operation methods to include "Code Example" links in method @see sections, appearing after AWS API Documentation links

Testing

Ran the inject_examples.py script locally
Generated javadoc documentation for test services
Opened the package-summary.html files in browser and verified code examples sections are properly displayed
Confirmed examples are organized by categories and links work correctly

Screenshots (if appropriate)

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)

Checklist

I have read the CONTRIBUTING document
Local run of mvn install succeeds
My code follows the code style of this project
My change requires a change to the Javadoc documentation
I have updated the Javadoc documentation accordingly
I have added tests to cover my changes
All new and existing tests passed
I have added a changelog entry. Adding a new entry must be accomplished by running the scripts/new-change script and following the instructions. Commit the new file created by the script in .changes/next-release with your changes.
My change is to implement 1.11 parity feature and I have updated LaunchChangelog

License

I confirm that this pull request can be released under the Apache 2 license

codegen/src/main/java/software/amazon/awssdk/codegen/internal/DocumentationUtils.java

zoewangg · 2025-12-16T21:36:39Z

codegen/src/main/java/software/amazon/awssdk/codegen/internal/DocumentationUtils.java

+     * @param operationName the name of the operation to find an example for
+     * @return a '@see also' HTML link to the code example, or empty string if no example found
+     */
+    public static String createLinkToCodeExample(Metadata metadata, String operationName) {


Can we add some codegen tests? we can create a mock example.json file

Any updates?

zoewangg · 2025-12-16T21:37:02Z

codegen/src/main/java/software/amazon/awssdk/codegen/internal/DocumentationUtils.java

+                return String.format("<a href=\"%s\" target=\"_top\">Code Example</a>", url);
+            }
+
+            return "";


Should we just use null to indicate there's no example, so here, we'd return Optional.empty()?

Hmm, we're not using null here. we're returning an empty string ("") right, so based on the check we have in OperationDocProvider.java, it wont show example when its empty string.

Right, I was suggesting using null to denote lack of example instead of empty string

codegen/src/main/java/software/amazon/awssdk/codegen/internal/DocumentationUtils.java

sonarqubecloud · 2025-12-18T20:00:05Z

Quality Gate failed

Failed conditions
30.9% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

zoewangg · 2025-12-19T03:27:23Z

codegen/src/main/java/software/amazon/awssdk/codegen/docs/OperationDocProvider.java

            docBuilder.see(crosslink);
        }
+
+        String exampleMetaPath = "software/amazon/awssdk/codegen/example-meta.json";


Can we create a constant?

zoewangg · 2025-12-19T03:29:24Z

...n/src/main/java/software/amazon/awssdk/codegen/emitters/tasks/PackageInfoGeneratorTasks.java

+        javadoc.append("<p>The following code examples show how to use this service with the AWS SDK for Java v2:</p>")
+               .append("\n");
+
+        Map<String, String> categoryMapping = new java.util.LinkedHashMap<>();


Can we initialize this map in ctor?

zoewangg · 2025-12-19T03:32:30Z

codegen/src/main/java/software/amazon/awssdk/codegen/internal/DocumentationUtils.java

+                return String.format("<a href=\"%s\" target=\"_top\">Code Example</a>", url);
+            }
+
+            return "";


Right, I was suggesting using null to denote lack of example instead of empty string

zoewangg · 2025-12-19T03:37:47Z

...n/src/main/java/software/amazon/awssdk/codegen/emitters/tasks/PackageInfoGeneratorTasks.java

 /**
 * Emits the package-info.java for the base service package. Includes the service
 * level documentation.
 */


Can we update javadoc?

zoewangg · 2025-12-19T03:39:26Z

...n/src/main/java/software/amazon/awssdk/codegen/emitters/tasks/PackageInfoGeneratorTasks.java

+        StringBuilder result = new StringBuilder();
+        String[] lines = codeExamplesJavadoc.split("\n");
+        for (String line : lines) {
+            if (!line.trim().isEmpty()) {
+                result.append(line);
+                if (!line.equals(lines[lines.length - 1])) {
+                    result.append(System.lineSeparator()).append(" * ");
+                }
+            }
+        }


It's not straighforward what this block is trying to do. Can we create a separate method with documentation?

zoewangg · 2025-12-19T03:42:32Z

...n/src/main/java/software/amazon/awssdk/codegen/emitters/tasks/PackageInfoGeneratorTasks.java

+
+
+    private String generateCodeExamplesJavadoc(List<DocumentationUtils.ExampleData> examples) {
+        Map<String, List<DocumentationUtils.ExampleData>> categorizedExamples = new java.util.LinkedHashMap<>();


Let's replace qualified name with import. new java.util.LinkedHashMap<>(); -> new LinkedHashMap<>())

Can be shortened to the following:

Map<String, List<DocumentationUtils.ExampleData>> categorizedExamples = examples.stream().collect(Collectors.groupingBy(DocumentationUtils.ExampleData::getCategory, LinkedHashMap::new, Collectors.toList()));

zoewangg · 2025-12-19T03:53:27Z

...n/src/main/java/software/amazon/awssdk/codegen/emitters/tasks/PackageInfoGeneratorTasks.java

+        for (Map.Entry<String, String> entry : categoryMapping.entrySet()) {
+            String category = entry.getKey();
+            String displayName = entry.getValue();
+            List<DocumentationUtils.ExampleData> categoryExamples = categorizedExamples.get(category);
+            if (categoryExamples != null && !categoryExamples.isEmpty()) {
+                appendCategorySection(javadoc, displayName, categoryExamples);
+            }
+        }
+
+        for (Map.Entry<String, List<DocumentationUtils.ExampleData>> entry : categorizedExamples.entrySet()) {
+            String category = entry.getKey();
+            if (!categoryMapping.containsKey(category)) {
+                List<DocumentationUtils.ExampleData> categoryExamples = entry.getValue();
+                if (!categoryExamples.isEmpty()) {
+                    appendCategorySection(javadoc, category, categoryExamples);
+                }
+            }
+        }


It's not very straighforward what those two loop do. Can we create separat methods with descriptive method names (ideally with javadocs).

zoewangg · 2025-12-19T03:56:48Z

codegen/src/main/java/software/amazon/awssdk/codegen/internal/DocumentationUtils.java

+    private static Map<String, JsonNode> serviceNodeCache;
+    private static Map<String, String> normalizedServiceKeyMap;


Doesn't seem thread safe. Suggesting creating a class instead of using static util methods for the new functionalities.

Add code example links to individual method documentation

c306af1

S-Saranya1 requested a review from a team as a code owner December 15, 2025 22:58

zoewangg requested changes Dec 16, 2025

View reviewed changes

zoewangg mentioned this pull request Dec 17, 2025

Add code examples to package summary pages in API refs guide #6625

Closed

12 tasks

S-Saranya1 added 5 commits December 17, 2025 10:02

Address PR feedback

700aec0

Fixing build failure

dd0c522

Add code examples to package summary pages

35e541b

Fixing build failure

6fb8b85

Minor changes

ac222ce

zoewangg reviewed Dec 19, 2025

View reviewed changes



		private String generateCodeExamplesJavadoc(List<DocumentationUtils.ExampleData> examples) {
		Map<String, List<DocumentationUtils.ExampleData>> categorizedExamples = new java.util.LinkedHashMap<>();

		private static Map<String, JsonNode> serviceNodeCache;
		private static Map<String, String> normalizedServiceKeyMap;

Add code example links to individual method documentation in API refs guide #6626

Are you sure you want to change the base?

Add code example links to individual method documentation in API refs guide #6626

Conversation

S-Saranya1 commented Dec 15, 2025

Motivation and Context

Modifications

Testing

Screenshots (if appropriate)

Types of changes

Checklist

License

Uh oh!

Uh oh!

Uh oh!

zoewangg Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud bot commented Dec 18, 2025

Quality Gate failed

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zoewangg Dec 16, 2025 •

edited

Loading