HHH-16801 document 'is true', 'is not true', 'is false', 'is not false' operators

Author: gavinking

documentation/src/main/asciidoc/querylanguage/Expressions.adoc

@@ -1133,13 +1133,14 @@ from Book where price between 1.0 and 100.0
 ==== Operators for dealing with null
 
 The following operators make it easier to deal with null values.
+These predicates never evaluate to `null`.
 
 [cols="20,20,15,~"]
 |===
 | Operator | Negation | Type | Semantics
 
-| `is null` | `is not null` | Unary postfix | `true` if the value to the left is null
-| `is distinct from` | `is not distinct from` | Binary | `true` if the value on the left is equal to the value on the right, or if both are null
+| `is null` | `is not null` | Unary postfix | `true` if the value to the left is null, or false if it is not null
+| `is distinct from` | `is not distinct from` | Binary | `true` if the value on the left is equal to the value on the right, or if both values are null, and false otherwise
 |===
 
 [[null-predicate-example]]
@@ -1148,6 +1149,33 @@ The following operators make it easier to deal with null values.
 from Author where nomDePlume is not null
 ----
 
+[[boolean-predicate]]
+==== Operators for dealing with boolean values
+
+These operators perform comparisons on values of type `boolean`.
+These predicates never evaluate to `null`.
+
+[NOTE]
+====
+The values `true` and `false` of the `boolean` basic type are different to the logical `true` or `false` produced by a predicate.
+====
+
+For _logical_ operations on <<conditional-expressions,predicates>>, see <<logical-operators>> below.
+
+[cols="20,20,15,~"]
+|===
+| Operator | Negation | Type | Semantics
+
+| `is true` | `is not true` | Unary postfix | `true` if the value to the left is `true`, or `false` otherwise
+| `is false` | `is not false` | Binary | `true` if the value to the left is `false`, or `false` otherwise
+|===
+
+[[null-predicate-example]]
+[source, hql]
+----
+from Book where discontinued is not true
+----
+
 [[collection-operators]]
 ==== Collection predicates
 

documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc

@@ -1226,6 +1226,27 @@ include::{example-dir-hql}/HQLTest.java[tags=hql-null-predicate-example]
 ----
 ====
 
+[[boolean-predicate]]
+==== Operators for dealing with boolean values
+
+These operators perform comparisons on values of type `boolean`.
+These predicates never evaluate to `null`.
+
+[NOTE]
+====
+The values `true` and `false` of the `boolean` basic type are different to the logical `true` or `false` produced by a predicate.
+====
+
+For _logical_ operations on <<conditional-expressions,predicates>>, see <<logical-operators>> below.
+
+[cols="20,20,15,~"]
+|===
+| Operator | Negation | Type | Semantics
+
+| `is true` | `is not true` | Unary postfix | `true` if the value to the left is `true`, or `false` otherwise
+| `is false` | `is not false` | Binary | `true` if the value to the left is `false`, or `false` otherwise
+|===
+
 [[hql-like-predicate]]
 ==== String pattern matching