improve package doc for o.h.query.sqm

hibernate-core/src/main/java/org/hibernate/package-info.java

@@ -16,7 +16,7 @@
  * <p>
  * Playing important supporting roles here, we also have
  * {@link org.hibernate.Transaction}, {@link org.hibernate.Filter},
- * and {@link org.hibernate.Cache}
+ * and {@link org.hibernate.Cache}.
  * <p>
  * APIs related to querying are now defined under the namespace
  * {@link org.hibernate.query}.

hibernate-core/src/main/java/org/hibernate/query/sqm/package-info.java

@@ -10,21 +10,37 @@
  *
  * <h3>Semantic Query Model (SQM)</h3>
  *
- * SQM is a tree (AST) based representation of the semantic interpretation of a query
- * (HQL or Criteria). It is "semantic" in the sense that it is more than a simple syntax
- * tree.
+ * An SQM is a tree representing the semantic interpretation of a query.
+ * It's "semantic" in the sense that it contains more information than a
+ * simple syntax tree.
  *
  * <h3>HQL</h3>
  *
- * HQL is interpreted into an SQM with the help of ANTRL parsed generator. The entry point
- * into the transformation is {@link org.hibernate.query.hql.internal.SemanticQueryBuilder}.
+ * HQL is interpreted as an SQM with the help of an ANTRL-generated parser.
+ * The class {@link org.hibernate.query.hql.internal.SemanticQueryBuilder}
+ * is responsible for visiting the syntax tree produced by the parser and
+ * building an SQM.
  *
  * <h3>Criteria queries</h3>
  *
- * The SQM tree implements the JPA criteria query contracts. Our implementation of the JPA
+ * The SQM tree nodes directly implement the JPA criteria query contracts.
+ * For example, {@link org.hibernate.query.sqm.tree.from.SqmFrom} implements
+ * {@link jakarta.persistence.criteria.From}.
+ * <p>
+ * Our implementation of the JPA
  * {@link jakarta.persistence.criteria.CriteriaBuilder} interface is
- * {@link org.hibernate.query.sqm.internal.SqmCriteriaNodeBuilder}. It produced SQM nodes
- * that are arranged into an SQM tree via the standard JPA criteria building approach.
+ * {@link org.hibernate.query.sqm.internal.SqmCriteriaNodeBuilder}.
+ * It instantiates SQM nodes and arranges them into SQM tree using the
+ * standard operations for building a JPA criteria query.
+ *
+ * <h3>Transforming SQM to SQL</h3>
+ *
+ * The package {@link org.hibernate.sql.ast} defines an AST representing
+ * SQL. To generate SQL from SQM, we must transform the SQM tree to a
+ * SQL AST tree. This process is described
+ * {@linkplain org.hibernate.query.hql here}, and is handled by a
+ * {@link org.hibernate.query.sqm.sql.internal.StandardSqmTranslator}
+ * and a {@link org.hibernate.sql.ast.SqlAstTranslator}.
  *
  * @apiNote This entire package is in an incubating state.
  */

hibernate-core/src/main/java/org/hibernate/sql/ast/package-info.java

@@ -7,6 +7,9 @@
 
 /**
  * Package defining a SQL AST for use in generation of SQL.
+ * <p>
+ * The SQL AST is an intermediate product of the {@linkplain org.hibernate.query.hql process}
+ * of translating a HQL or criteria query to SQL.
  */
 @Incubating
 package org.hibernate.sql.ast;