Skip to content

chore: Move introductory text for Javadoc examples into the <pre> block. #12217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jinseopkim0 merged 2 commits into from
Mar 27, 2026
Merged

chore: Move introductory text for Javadoc examples into the <pre> block. #12217

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
593709a
chore: Move introductory text for Javadoc examples into the <pre> block.
jinseopkim0 Mar 26, 2026
404a064
Merge branch 'main' into datastore_doc
jinseopkim0 Mar 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions ...store-v1-proto-client/src/main/java/com/google/datastore/v1/client/DatastoreEmulator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,8 @@
/**
* An extension to {@link Datastore} that provides lifecycle management for a datastore emulator.
*
* <p>In order to use the emulator for a JUnit 4 test you might do something like this:
*
* <pre>
* // In order to use the emulator for a JUnit 4 test you might do something like this:
Comment on lines 38 to +39
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

While moving the introductory text into the 

 block makes it more convenient for copy-pasting, it is generally better for Javadoc readability to have descriptive text as a paragraph before the code example. This approach makes the generated documentation cleaner and more semantically correct. The previous implementation was more idiomatic for Javadoc.

  

    

      

        Suggested change
      

    

    

      

          

            
             * <pre>
          

          

            
             * // In order to use the emulator for a JUnit 4 test you might do something like this:
          

          

            
             * <p>In order to use the emulator for a JUnit 4 test you might do something like this:</p>
          

          

            
             *
          

          

            
             * <pre>

* public class MyTest {
*
* static DatastoreEmulator datastore;
Expand Down
3 changes: 1 addition & 2 deletions ...astore-v1-proto-client/src/main/java/com/google/datastore/v1/client/DatastoreOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,8 @@
/**
* An immutable object containing settings for the datastore.
*
* <p>Example for connecting to a datastore:
*
* <pre>
* // Example for connecting to a datastore:
Comment on lines 29 to +30
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For better Javadoc readability and semantic correctness, introductory text for code examples should be in a paragraph preceding the 

 block. Placing it as a comment inside the block, as done here, can make the generated documentation less clean. The original approach is generally preferred.

  

    

      

        Suggested change
      

    

    

      

          

            
             * <pre>
          

          

            
             * // Example for connecting to a datastore:
          

          

            
             * <p>Example for connecting to a datastore:</p>
          

          

            
             *
          

          

            
             * <pre>

* DatastoreOptions options = new DatastoreOptions.Builder()
* .projectId("my-project-id")
* .credential(DatastoreHelper.getComputeEngineCredential())
Expand Down
Loading