add more words and subsections to Hibernate Processor doc chapter

Author: gavinking

documentation/src/main/asciidoc/introduction/Processor.adoc

@@ -5,6 +5,14 @@ The _static metamodel generator_ is a standard part of JPA.
 // It's an annotation processor that produces a statically-typed metamodel of the entity classes in a Java program.
 We've actually already seen its handiwork in the code examples <<main-hibernate,earlier>>: it's the author of the class `Book_`, which contains the static metamodel of the <<book,entity class>> `Book`.
 
+Hibernate comes with an annotation processor which does much more than just this.
+It's capable of automatically generating:
+
+- <<static-metamodel,JPA metamodel>> classes, as we've already seen,
+- link:{doc-data-repositories-url}#data-static-metamodel[Jakarta Data metamodel] classes,
+- static <<generated-query-methods,query methods>> and <<generated-finder-methods,finder methods>>, and
+- implementations of <<static-or-instance,repository interfaces>>, including link:{doc-data-repositories-url}#repository-interfaces[Jakarta Data repositories].
+
 [[metamodel-generator]]
 .Hibernate Processor
 ****
@@ -42,6 +50,17 @@ We've already seen how to set up the annotation processor in the <<hello-hiberna
 For more details on how to integrate the Hibernate Processor, check out the {generator-guide}[Static Metamodel Generator] section in the User Guide.
 ====
 
+[[static-metamodel]]
+=== The static metamodel
+
+We've already seen several ways to use the JPA static metamodel.
+Metamodel references are useful for expressing, in a completely type-safe way:
+
+- <<criteria-queries,Criteria queries>>,
+- eager fetching via an <<entity-graph,entity graph>>,
+- dynamic <<restrictions-and-ordering,restriction and sorting>>, and
+- references to named <<named-queries,queries>> and named entity graphs.
+
 Here's an example of the sort of code that's generated for an entity class, as mandated by the JPA specification:
 
 [source,java]
@@ -169,23 +188,10 @@ Actually, Hibernate Processor doesn't require that such annotations be applied t
 We've already been using metamodel references like `Book_.authors` and `Book.AUTHORS` in the previous chapters.
 So now let's see what else Hibernate Processor can do for us.
 
-.Hibernate Processor and Jakarta Data
-****
-// For many years we've followed a three-step process: implement, learn from experience, and then standardize.
-//
-The functionality we're about to describe was developed before Jakarta Data took on its current shape, and directly triggered the apocalypse which lead to the final form of the specification.
-Therefore, there's massive overlap between the functionality described in this chapter, and the functionality available via the Jakarta Data annotations.
-On the other hand, Jakarta Data can't do _everything_ described below, and in particular it doesn't yet come with built-in support for stateful persistence contexts or reactive sessions.
-// We are currently working hard to standardize these capabilities, but writing great specifications takes time.
+[[finders-queries-repositories]]
+=== Finder methods, query methods, and repositories
 
-We've therefore opted _not_ to rewrite this chapter in a Jakarta Data-centric way, and instead refer you to link:{doc-data-repositories-url}[Introducing Hibernate Data Repositories] for information about the standard Jakarta Data APIs.
-
-As Jakarta Data matures, even more of this functionality might be made obsolete, at least in the form described here.
-We're working hard to make this happen.
-****
-
-Automatic generation of _finder methods_ and _query methods_ is a relatively new feature of Hibernate Processor, and an extension to the functionality defined by the JPA specification.
-In this chapter, we're going to explore these features.
+Automatic generation of _finder methods_ and _query methods_ is a relatively new feature of Hibernate Processor--originally introduced as an experiment--which ultimately grew into a whole new way to use Hibernate.
 
 We're going to meet three different kinds of generated method:
 
@@ -198,7 +204,25 @@ We're also going to see two ways that these methods can be called:
 - as static methods of a generated abstract class, or
 - as <<static-or-instance,instance methods of an interface>> with a generated implementation which may even be <<cdi-bean-injection,injected>>.
 
-To whet our appetites, let's see how this works for a `@NamedQuery`.
+Back in <<organizing-persistence>>, we walked you through a few different ways to organize your code with the help of Hibernate Processor.
+That journey terminated at the idea of a repository, but we emphasized that you aren't required to stay all the way to the end of the line.
+Repositories are a sweet spot for many users, but they might not be your sweet spot, and that's OK.
+Hibernate Processor is perfectly happy to generate `static` implementations of `@HQL`, `@SQL`, and `@Find` methods, eliminating the need to inject or instantiate a repository object.
+
+.Hibernate Processor and Jakarta Data
+****
+// For many years we've followed a three-step process: implement, learn from experience, and then standardize.
+//
+The functionality we're about to describe was developed before Jakarta Data took on its current shape, and directly triggered the apocalypse which lead to the final form of the specification.
+Therefore, there's massive overlap between the functionality described in this chapter, and the functionality available via the Jakarta Data annotations.
+On the other hand, Jakarta Data can't do _everything_ described below, and in particular it doesn't yet come with built-in support for stateful persistence contexts or reactive sessions.
+// We are currently working hard to standardize these capabilities, but writing great specifications takes time.
+
+We've therefore opted _not_ to rewrite this chapter in a Jakarta Data-centric way, and instead refer you to link:{doc-data-repositories-url}[Introducing Hibernate Data Repositories] for information about the standard Jakarta Data APIs.
+
+As Jakarta Data matures, even more of this functionality might be made obsolete, at least in the form described here.
+We're working hard to make that happen.
+****
 
 [CAUTION]
 ====
@@ -207,6 +231,8 @@ Hibernate Processor is not currently able to generate finder methods and query m
 (On the other hand, the <<object-relational-mapping,O/R mappings>> may be specified in XML, since they're not needed by the Processor.)
 ====
 
+To whet our appetites, let's see how it works for a `@NamedQuery`.
+
 [[generated-named-queries]]
 === Named queries and Hibernate Processor