three minor improvements

api/src/main/java/jakarta/persistence/InheritanceType.java

@@ -17,7 +17,7 @@
 package jakarta.persistence;
 
 /**
- * Enumerated the options for mapping entity inheritance.
+ * Enumerates the options for mapping entity inheritance.
  *
  * @see Inheritance#strategy
  *

spec/src/main/asciidoc/ch02-entities.adoc

@@ -2308,29 +2308,31 @@ public class ShoppingCart extends Cart {
 
 The mapping of class hierarchies is specified through metadata.
 
-There are three basic strategies that are
-used when mapping a class or class hierarchy to a relational database:
-
-* a single table per class hierarchy
-* a joined subclass strategy, in which fields
-that are specific to a subclass are mapped to a separate table than the
-fields that are common to the parent class, and a join is performed to
-instantiate the subclass.
-* a table per concrete entity class
-
-An implementation is required to support the
-single table per class hierarchy inheritance mapping strategy and the
-joined subclass strategy.
+There are three basic strategies which may be used when mapping an
+entity class hierarchy to tables in a relational database.
+
+* With a _single table per class hierarchy_, every field declared by
+  any class in the hierarchy maps to a column of the same table.
+  A subclass shares the table of its superclasses.
+* With a _table per concrete entity class_, every field declared or
+  inherited by a given subclass is mapped to the same table, but each
+  concrete class in the hierarchy has its own separate table.
+* For the _joined subclass_ strategy, any field which is declared by
+  a subclass is mapped to a separate table from the fields which are
+  declared by its superclass. Table joins may be used to retrieve all
+  fields declared and inherited by the subclass.
+
+An implementation is required to support the single table per class
+hierarchy inheritance mapping strategy and the joined subclass strategy.
 
 [NOTE]
 ====
-Support for the table per concrete class
-inheritance mapping strategy is optional in this release. Applications
-that use this mapping strategy will not be portable.
+Support for the table per concrete class inheritance mapping strategy
+is optional in this release. Applications that use this mapping strategy
+are not portable between all providers.
 
-Support for the combination of inheritance
-strategies within a single entity inheritance hierarchy is not required
-by this specification.
+Support for the combination of inheritance strategies within a single entity
+inheritance hierarchy is not required by this specification.
 ====
 
 ==== Single Table per Class Hierarchy Strategy

spec/src/main/asciidoc/ch04-query-language.adoc

@@ -2038,7 +2038,7 @@ unknown value. See <<a5676>>.
 An input parameter might be _single-valued_ or _collection-valued_.
 An input parameter which occurs directly to the right of the `IN` keyword
 in an `IN` predicate, as defined in <<a5107>>, is collection-valued. Every
-other input parameter is single-valued
+other input parameter is single-valued.
 
 The API for the binding concrete arguments to query parameters is described
 in <<a3125>>.

spec/src/main/asciidoc/ch11-metadata-for-or-mapping.adoc

@@ -1319,10 +1319,10 @@ Address address;
 
 ==== DiscriminatorColumn Annotation [[a14530]]
 
-For the SINGLE_TABLE mapping strategy, and
-typically also for the JOINED strategy, the persistence provider will
+For the `SINGLE_TABLE` mapping strategy, and
+typically also for the `JOINED` strategy, the persistence provider will
 use a type discriminator column. The `DiscriminatorColumn` annotation is
-used to define the discriminator column for the SINGLE_TABLE and JOINED
+used to define the discriminator column for the `SINGLE_TABLE` and `JOINED`
 inheritance mapping strategies.
 
 The strategy and the discriminator
@@ -1337,8 +1337,8 @@ specified on an entity class (including on an abstract entity class).
 
 If the `DiscriminatorColumn` annotation is
 missing, and a discriminator column is required, the name of the
-discriminator column defaults to "DTYPE" and the discriminator type to
-STRING.
+discriminator column defaults to `DTYPE` and the discriminator type to
+`STRING`.
 
 <<a14548>> lists the annotation elements
 that may be specified for the `DiscriminatorColumn` annotation and their
@@ -2238,7 +2238,7 @@ hierarchy.
 
 If the `Inheritance` annotation is not
 specified or if no inheritance type is specified for an entity class
-hierarchy, the SINGLE_TABLE mapping strategy is used.
+hierarchy, the `SINGLE_TABLE` mapping strategy is used.
 
 Support for the combination of inheritance
 strategies is not required by this specification. Portable applications
@@ -2281,7 +2281,7 @@ public @interface Inheritance {
 |InheritanceType
 |strategy
 |(Optional) The inheritance strategy to use for the entity inheritance hierarchy.
-|InheritanceType.SINGLE_TABLE
+|`InheritanceType.SINGLE_TABLE`
 |===
 
 *Example:*
@@ -2386,7 +2386,7 @@ by this foreign key column. When used with entity relationship mappings
 other than the cases described below, the referenced column is in the
 table of the target entity. When used with a unidirectional OneToMany
 foreign key mapping, the referenced column is in the table of the source
-entity. When used inside a JoinTable annotation, the referenced key
+entity. When used inside a `JoinTable` annotation, the referenced key
 column is in the entity table of the owning entity, or inverse entity if
 the join is part of the inverse join definition. When used in a
 collection table mapping, the referenced column is in the table of the
@@ -4544,7 +4544,7 @@ specifies a primary key column that is used as a foreign key to join to
 another table.
 
 The `PrimaryKeyJoinColumn` annotation is used
-to join the primary table of an entity subclass in the JOINED mapping
+to join the primary table of an entity subclass in the `JOINED` mapping
 strategy to the primary table of its superclass; it is used within a
 `SecondaryTable` annotation to join a secondary table to a primary
 table; and it may be used in a `OneToOne` mapping in which the primary
@@ -4567,7 +4567,7 @@ that may be specified for the `PrimaryKeyJoinColumn` annotation and
 their default values.
 
 If no `PrimaryKeyJoinColumn` annotation is
-specified for a subclass in the JOINED mapping strategy, the foreign key
+specified for a subclass in the `JOINED` mapping strategy, the foreign key
 columns are assumed to have the same names as the primary key columns of
 the primary table of the superclass.
 
@@ -4594,20 +4594,20 @@ public @interface PrimaryKeyJoinColumn {
 |name
 |(Optional) The name of the primary key column of the current table.
 |The same name
-as the primary key column of the primary table of the superclass (JOINED
+as the primary key column of the primary table of the superclass (`JOINED`
 mapping strategy); the same name as the primary key column of the
-primary table (SecondaryTable mapping); or the same name as the primary
-key column for the table for the referencing entity (OneToOne mapping).
+primary table (`SecondaryTable` mapping); or the same name as the primary
+key column for the table for the referencing entity (`OneToOne` mapping).
 
 |String
 |referencedColumnName
 |(Optional) The name of the primary key column of the table being joined to.
 |The
 same name as the primary key column of the primary table of the
-superclass (JOINED mapping strategy); the same name as the primary key
-column of the primary table (SecondaryTable mapping); or the same name
+superclass (`JOINED` mapping strategy); the same name as the primary key
+column of the primary table (`SecondaryTable` mapping); or the same name
 as the primary key column of the table for the referenced entity
-(OneToOne mapping).
+(`OneToOne` mapping).
 
 |String
 |columnDefinition
@@ -5049,7 +5049,7 @@ allocating sequence numbers from the sequence.
 
 ==== SequenceGenerators Annotation [[a16205]]
 
-The SequenceGenerators annotation can be used
+The `SequenceGenerators` annotation can be used
 to specify multiple sequence generators.
 
 [source,java]
@@ -5077,8 +5077,8 @@ public @interface SequenceGenerators {
 The `Table` annotation specifies the
 primary table for the annotated entity. Additional tables may be
 specified by using the `SecondaryTable` or `SecondaryTables`
-annotation.footnote:[When a joined
-inheritance strategy is used, the Table annotation is used to specify a
+annotation.footnote:[When a `JOINED`
+inheritance strategy is used, the `Table` annotation is used to specify a
 primary table for the subclass-specific state if the default is not
 used.]
 
@@ -5133,7 +5133,7 @@ public @interface Table {
 |(Optional) Unique constraints that are to be
 placed on the table. These are only used if table generation is in
 effect. These constraints apply in addition to any constraints specified
-by the Column and JoinColumn annotations and constraints entailed by
+by the `Column` and `JoinColumn` annotations and constraints entailed by
 primary key mappings.
 |No additional
 constraints
@@ -5346,7 +5346,7 @@ public class Address {
 
 ==== TableGenerators Annotation
 
-The TableGenerators annotation can be used to
+The `TableGenerators` annotation can be used to
 specify multiple table generators.
 
 [source,java]
@@ -5768,8 +5768,8 @@ See <<a15873>> for the rules that pertain to the generation of order columns.
 ===== DiscriminatorColumn
 
 A discriminator column is generated for the
-SINGLE_TABLE mapping strategy and may optionally be generated by the
-provider for use with the JOINED inheritance strategy. The
+`SINGLE_TABLE` mapping strategy and may optionally be generated by the
+provider for use with the `JOINED` inheritance strategy. The
 `DiscriminatorColumn` annotation may be used to control the mapping of
 the discriminator column. See <<a14530>> for the rules that pertain to
 discriminator columns.
@@ -5899,8 +5899,8 @@ be used to override such mappings.
 
 The `PrimaryKeyJoinColumn` annotation
 specifies that a primary key column is to be used as a foreign key. This
-annotation is used in the specification of the JOINED mapping strategy
-and for joining a secondary table to a primary table in a OneToOne
+annotation is used in the specification of the `JOINED` mapping strategy
+and for joining a secondary table to a primary table in a `OneToOne`
 relationship mapping. In general, the foreign key definitions created
 should be expected to be provider-dependent and database-dependent.
 Applications that are sensitive to the exact mapping that is used should