micronaut-projects / micronaut-data

Ahead of Time Data Repositories
Apache License 2.0
459 stars 196 forks source link

Docs should not point to Spring Data / JPA docs to explain Micronaut APIs #2938

Open mikehearn opened 1 month ago

mikehearn commented 1 month ago

Issue description

Some of the JavaDocs and guides are a bit lazy and say things like "A repository interface for performing CRUD (Create, Read, Update, Delete). This is a blocking variant and is largely based on the same interface in Spring Data, however includes integrated validation support" which is great if you happen to already know Spring Data but is not useful if you don't.

Another example: https://micronaut-projects.github.io/micronaut-data/latest/guide/#sqlAssociationMapping

mikehearn commented 1 month ago

Another example:

https://micronaut-projects.github.io/micronaut-data/latest/api/io/micronaut/transaction/annotation/TransactionalEventListener.html

What does "transaction aware event listener" actually mean. The description is repeated in javadoc and user guide but it's never explained how exactly a transaction aware event listener differs from a normal one. Presumably it means it runs inside the transaction instead of outside it?

mikehearn commented 1 month ago

Another one: https://micronaut-projects.github.io/micronaut-data/latest/api/io/micronaut/transaction/TransactionDefinition.html

This is a fork of Spring's PlatformTransactionManager modernizing it to use enums, SLF4J and decoupling from Spring. Interface that defines Spring-compliant transaction properties. Based on the propagation behavior definitions analogous to EJB CMT attributes.