From 34ad8e23477c662f26767991abcad2f4e2ac71aa Mon Sep 17 00:00:00 2001
From: Andrew Johnson <anj@anl.gov>
Date: Sat, 31 Dec 2022 19:10:49 -0600
Subject: [PATCH] Edits to Release Notes and postfix.h documentation

---
 documentation/RELEASE_NOTES.md    | 20 +++++++++++++-------
 modules/libcom/src/calc/postfix.h | 25 ++++++++++++++++---------
 2 files changed, 29 insertions(+), 16 deletions(-)

diff --git a/documentation/RELEASE_NOTES.md b/documentation/RELEASE_NOTES.md
index f15d6e2e7..a17b70f83 100644
--- a/documentation/RELEASE_NOTES.md
+++ b/documentation/RELEASE_NOTES.md
@@ -31,17 +31,23 @@ please send feedback about the feature to tech-talk.
 
 ### Tab completion for IOC shell
 
-When built with optional libreadline support, the interactive IOC shell will perform tab
-completion for command names as well as some arguments of built-in commands.
-eg. the record name argument of `dbpr`, and the path name argument of `cd`.
+When built with optional GNU libreadline support, the interactive IOC shell
+will perform tab completion for command names as well as for some arguments
+of the built-in commands. For example, the record name argument of `dbpr`,
+and the path name argument of `cd`.
 
-Externally defined commands have a limited ability to opt into completion with
-the newly added `iocshArgStringRecord` and `iocshArgStringPath` argument types.
-Both function identically to `iocshArgString` with an added hint about completion.
+Externally defined commands have a limited ability to opt into completion by
+using the new `iocshArgStringRecord` and `iocshArgStringPath` argument types.
+Both function identically to `iocshArgString` but indicate how to suggest
+completion strings.
 
 ### Add FMOD as CALC Expression
 
-The floating point modulo function `FMOD(NUM,DEN)` is added.
+The floating point modulo function `FMOD(NUM,DEN)` has been added to the CALC
+expression engine and is available to all software using that (calc and calcout
+record types, access security library and some extensions).
+
+-----
 
 ## EPICS Release 7.0.7
 
diff --git a/modules/libcom/src/calc/postfix.h b/modules/libcom/src/calc/postfix.h
index d4c4dea9b..c9fdc1ee7 100644
--- a/modules/libcom/src/calc/postfix.h
+++ b/modules/libcom/src/calc/postfix.h
@@ -203,10 +203,10 @@ extern "C" {
  *  unary minus.
  *
  *    - Examples:
- *      - e:=a%10;
- *      - d:=a/10%10;
- *      - c:=a/100%10;
- *      - b:=a/1000%10;
+ *      - e:=a%10
+ *      - d:=a/10%10
+ *      - c:=a/100%10
+ *      - b:=a/1000%10
  *      - b*4096+c*256+d*16+e
  *      - sqrt(a**2 + b**2)
  *
@@ -221,6 +221,8 @@ extern "C" {
  *    - n parameter maximum value: max(a, b, ...)
  *    - n parameter minimum value: min(a, b, ...)
  *    - Square root: sqr(a) or sqrt(a)
+ *    - Floating point modulo: fmod(num, den)
+ *  \since The fmod() function was added in UNRELEASED
  *
  * -# ***Trigonometric Functions***
  *  Standard circular trigonometric functions, with angles expressed in radians:
@@ -261,16 +263,21 @@ extern "C" {
  *    - Boolean not: !a
  *
  * -# ***Bitwise Operators***
- * The bitwise operators convert their arguments to an integer (by truncation),
- * perform the appropriate bitwise operation and convert back to a floating point
- * value. Unlike in C though, ^ is not a bitwise exclusive-or operator.
+ * Most bitwise operators convert their arguments to 32-bit signed integer (by
+ * truncation), perform the appropriate bitwise operation, then convert back
+ * to a floating point value. The arithmetic right shift operator >> thus
+ * retains the sign bit of the left-hand argument. The logical right shift
+ * operator >>> is performed on an unsigned integer though, so injects zeros
+ * while shifting. The right-hand shift argument is masked so only the lower
+ * 5 bits are used. Unlike in C, ^ is not a bitwise exclusive-or operator.
  *
  *    - Bitwise and: a & b or a and b
  *    - Bitwise or: a | b or a or b
  *    - Bitwise exclusive or: a xor b
  *    - Bitwise not (ones complement): ~a or not a
- *    - Bitwise left shift: a << b
- *    - Bitwise right shift: a >> b
+ *    - Arithmetic left shift: a << b
+ *    - Arithmetic right shift: a >> b
+ *    - Logical right shift: a >>> b
  *
  * -# ***Relational Operators***
  *  Standard numeric comparisons between two values: