Merge pull request #1790 from opensafely-core/evansd/logical-terminology

Clean up logical terminology

docs/how-to/errors.md

@@ -816,7 +816,7 @@ age = patients.age_on("2023-01-01")
 dataset.age_group = case(
    when(age < 10).then(1),
    when(age > 80).then(2),
-   default="unknown",
+   otherwise="unknown",
 )
 ```
 
@@ -842,7 +842,7 @@ age = patients.age_on("2023-01-01")
 dataset.age_group = case(
    when(age < 10).then(1),
    when(age > 80).then(2),
-   default=0,
+   otherwise=0,
 )
 ```
 

docs/how-to/examples.md

@@ -107,7 +107,7 @@ dataset.age_band = case(
         when(age < 60).then("40-59"),
         when(age < 80).then("60-79"),
         when(age >= 80).then("80+"),
-        default="missing",
+        otherwise="missing",
 )
 dataset.define_population(patients.exists_for_patient())
 ```
@@ -227,7 +227,7 @@ dataset.imd_quintile = case(
     when(imd < int(32844 * 3 / 5)).then("3"),
     when(imd < int(32844 * 4 / 5)).then("4"),
     when(imd < int(32844 * 5 / 5)).then("5 (least deprived)"),
-    default="unknown"
+    otherwise="unknown"
 )
 dataset.define_population(patients.exists_for_patient())
 ```

docs/includes/generated_docs/language__functions.md

@@ -1,6 +1,6 @@
 
 <h4 class="attr-heading" id="case" data-toc-label="case" markdown>
-  <tt><strong>case</strong>(<em>*when_thens</em>, <em>default=None</em>)</tt>
+  <tt><strong>case</strong>(<em>*when_thens</em>, <em>otherwise=None</em>, <em>default=None</em>)</tt>
 </h4>
 <div markdown="block" class="indent">
 Take a sequence of condition-values of the form:
@@ -9,16 +9,16 @@ when(condition).then(value)
 ```
 
 And evaluate them in order, returning the value of the first condition which
-evaluates True. If no condition matches and a `default` is specified then return
-that, otherwise return NULL.
+evaluates True. If no condition matches, return the `otherwise` value; if no
+`otherwise` value is specified then return NULL.
 
 For example:
 ```py
 category = case(
     when(size < 10).then("small"),
     when(size < 20).then("medium"),
     when(size >= 20).then("large"),
-    default="unknown",
+    otherwise="unknown",
 )
 ```
 
@@ -31,14 +31,17 @@ A simpler form is available when there is a single condition.  This example:
 ```py
 category = case(
     when(size < 15).then("small"),
-    default="large",
+    otherwise="large",
 )
 ```
 
 can be rewritten as:
 ```py
 category = when(size < 15).then("small").otherwise("large")
 ```
+
+Note that the `default` argument is an older alias for `otherwise`: it will be
+removed in future versions of ehrQL and should not be used.
 </div>