From 7300df967ea7f96c053f704677b6a359e3a219ff Mon Sep 17 00:00:00 2001
From: Joe Bowbeer <joe.bowbeer@gmail.com>
Date: Tue, 22 Oct 2024 12:07:46 -0700
Subject: [PATCH] doc: Update --max-semi-space-size description

Signed-off-by: Joe Bowbeer <joe.bowbeer@gmail.com>
---
 doc/api/cli.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index cd2f4c27f322ba..9ac3309c84b231 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -3543,8 +3543,14 @@ an increase of 1 MiB to semi-space applies to each of the three individual
 semi-spaces and causes the heap size to increase by 3 MiB. The throughput
 improvement depends on your workload (see [#42511][]).
 
-The default value is 16 MiB for 64-bit systems and 8 MiB for 32-bit systems. To
-get the best configuration for your application, you should try different
+In <=v19 the default value is 16 MiB for 64-bit systems and 8 MiB for 32-bit systems.
+In v20 and later, however, the default value depends on the memory limit
+and will be smaller than in previous versions for memory limits of 2 GiB or less.
+
+For example, a memory limit of 512 MiB will default to 1 MiB of semi space in v20,
+whereas in v18 the default for 64-bit systems was 16 MiB.
+
+To get the best configuration for your application, you should try different
 max-semi-space-size values when running benchmarks for your application.
 
 For example, benchmark on a 64-bit systems: