fix some defects in repositories doc #9319

NathanQingyangXu · 2024-11-23T16:58:54Z

Hibernate Data is definitively highly interesting to MongoDB Hibernate integration project for it provides a good selling point to compete with Spring Data Mongo (I used to be a lover of Spring Data's method name based query feature, now I found it is not well-founded and technically Hibernate Data is much more powerful and makes more sense).

I found some obvious defects in the doc, though there are some I am not certain of so I left some comments to confirm.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license
and can be relicensed under the terms of the LGPL v2.1 license in the future at the maintainers' discretion.
For more information on licensing, please check here.

hibernate-github-bot · 2024-11-23T16:58:59Z

Thanks for your pull request!

This pull request does not follow the contribution rules. Could you have a look?

❌ All commit messages should start with a JIRA issue key matching pattern HHH-\d+
↳ Offending commits: [4380fa8, ba0fd59, 341d743]

› This message was automatically generated.

NathanQingyangXu · 2024-11-23T17:00:21Z

documentation/src/main/asciidoc/repositories/Repositories.adoc

@@ -16,6 +16,7 @@ public class Book {
    @Basic(optional = false)
    String title;

+    @Basic(optional = false)
    LocalDate publicationDate;


I found LocalDate is in the scope of Basic at https://docs.jboss.org/hibernate/orm/6.6/userguide/html_single/Hibernate_User_Guide.html#basic-basic-annotation:

NathanQingyangXu · 2024-11-23T17:01:31Z

documentation/src/main/asciidoc/repositories/Repositories.adoc

@@ -509,7 +510,7 @@ Since this is quite verbose, Hibernate doesn't require the use of `select new`,
 @Query("select isbn, ssn, name, title " +
       "from Author join books " +
       "where title like :pattern")
-List<AuthorBookSummary> summariesForTitle(@Pattern String pattern);
+List<AuthorBookSummary> summariesForTitle(String pattern);


seems @Pattern is not needed in method annotated @Query?

gavinking

Thanks Nathan, I have left comments.

gavinking · 2024-11-23T17:04:27Z

documentation/src/main/asciidoc/repositories/Configuration.adoc

@@ -126,7 +126,7 @@ It's always possible to instantiate a repository implementation directly.

 [source,java]
 ----
-Library library = new Library_(statelessSession);
+Library library = new Library(statelessSession);


Revert this one, please.

gavinking · 2024-11-23T17:06:38Z

documentation/src/main/asciidoc/repositories/Repositories.adoc

@@ -325,7 +326,7 @@ void add(Book... books);
 [NOTE]
 ====
 A future release of Jakarta Data might expand the list of built-in lifecycle annotations.
-In particular, we're hoping to add `@Persist`, `@Merge`, `@Refresh`, `@Lock`, and `@Remove`, mapping to the fundamental operations of `EntityManager`.
+In particular, we're hoping to add `@Persist`, `@Merge`, `@Refresh`, `@Lock`, and `@Remove` mapping to the fundamental operations of `EntityManager`.


Revert, I think that comma is necessary, even if the sentence structure is admittedly a bit inelegant.

gavinking · 2024-11-23T17:07:30Z

documentation/src/main/asciidoc/repositories/Repositories.adoc

@@ -168,7 +169,7 @@ The--perhaps surprising--answer is: it's completely up to you.
 === Organizing persistence operations

 Jakarta Data lets you freely assign persistence operations to repositories according to your own preference.
-In particular, Jakarta Data does not require that a repository interface inherit a built-in supertype declaring the basic "CRUD" operations, and so it's not necessary to have a separate repository interface for each entity.
+In particular, Jakarta Data does not require that a repository interface inherits a built-in supertype declaring the basic "CRUD" operations, and so it's not necessary to have a separate repository interface for each entity.


Revert, "inherit" is grammatically correct here; "inherits" is not.

gavinking · 2024-11-23T17:08:16Z

documentation/src/main/asciidoc/repositories/Repositories.adoc

@@ -16,6 +16,7 @@ public class Book {
    @Basic(optional = false)
    String title;

+    @Basic(optional = false)


Unclear on why you want to add this annotation.

for consistency reason. Seems LocalDate is in scope of @Basic? Anyway, if you are unclear, let me revert it back then.

Not sure what you mean by "in scope of" here.

gavinking · 2024-11-24T15:28:50Z

documentation/src/main/asciidoc/repositories/Repositories.adoc

@@ -113,7 +113,7 @@ This really isn't as bad as it sounds; overuse of lazy fetching is associated wi
 A future release of Jakarta Data will feature repositories backed by Jakarta Persistence stateful persistence contexts, but this functionality did not make the cut for Jakarta Data 1.0.
 ====

-The second big difference is that instead of providing a generic interface like `EntityManager` that's capable of performing persistence operations for any entity class, Jakarta Data requires that each interaction with the database go via a user-written method specific to just one entity type. The method is marked with annotations allowing Hibernate to fill in the method implementation.
+The second big difference is that instead of providing a generic interface like `EntityManager` that's capable of performing persistence operations for any entity class, Jakarta Data requires that each interaction with the database goes via a user-written method specific to just one entity type. The method is marked with annotations allowing Hibernate to fill in the method implementation.


@NathanQingyangXu this sentence is correct! English has a subjunctive mood just like Spanish does. Sure, plenty of English speakers don't use it in spoken English, but it's more correct in written English, and I do use it because I guess I read too much.

Here's what ChatGPT says about that sentence:

Yes, the sentence is grammatically correct. It conveys its meaning clearly and follows standard grammar rules. Here's a breakdown:

Subject-Verb Agreement:

The subject "Jakarta Data" correctly agrees with the verb "requires."

Subjunctive Mood:

The clause "that each interaction with the database go via a user-written method" uses the subjunctive mood correctly. The verb "go" (not "goes") is appropriate here because it's expressing a requirement or necessity.

Modifiers:

"Specific to just one entity type" modifies "method" appropriately, and the meaning is clear.
The sentence is well-constructed for a technical or formal context.

If you ask ChatGPT more about the subjunctive mood in English, I'm sure it will explain it to you.

FTR this comes from the same reason you say "if I were ten feet tall" instead of "if I was ten feet tall". Many English speakers will use "was" here, which isn't incorrect, but "were" is more elegant.

gavinking · 2024-11-24T15:33:45Z

documentation/src/main/asciidoc/repositories/Configuration.adoc

@@ -60,7 +60,7 @@ annotationProcessor 'org.hibernate.orm:hibernate-processor:7.0.0'

 === Excluding classes from processing

-There's three ways to limit the annotation processor to certain classes:
+There are three ways to limit the annotation processor to certain classes:


Note that I'm letting you change these because in principle (to a linguistic prescriptivist) "there's three ways" is grammatically "incorrect" in written English. But note that "there's many things" is something that's incredibly common in informal English and this phrase sounds completely correct to a native speaker. I would never ever notice this "mistake" in either written or spoken English.

fix some defects in repositories doc

4380fa8

NathanQingyangXu commented Nov 23, 2024

View reviewed changes

gavinking requested changes Nov 23, 2024

View reviewed changes

nathan.xu added 2 commits November 23, 2024 14:48

revert back a change

ba0fd59

revert back more changes

341d743

NathanQingyangXu requested a review from gavinking November 24, 2024 13:59

gavinking reviewed Nov 24, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix some defects in repositories doc #9319

fix some defects in repositories doc #9319

NathanQingyangXu commented Nov 23, 2024

hibernate-github-bot bot commented Nov 23, 2024 •

edited

Loading

NathanQingyangXu Nov 23, 2024

NathanQingyangXu Nov 23, 2024

gavinking left a comment

gavinking Nov 23, 2024

gavinking Nov 23, 2024

gavinking Nov 23, 2024

gavinking Nov 23, 2024

NathanQingyangXu Nov 24, 2024

gavinking Nov 24, 2024

gavinking Nov 24, 2024

gavinking Nov 24, 2024

gavinking Nov 24, 2024

fix some defects in repositories doc #9319

Are you sure you want to change the base?

fix some defects in repositories doc #9319

Conversation

NathanQingyangXu commented Nov 23, 2024

hibernate-github-bot bot commented Nov 23, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gavinking left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Subject-Verb Agreement:

Subjunctive Mood:

Modifiers:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hibernate-github-bot bot commented Nov 23, 2024 •

edited

Loading