Document that --realloc-via-memory-grow only affects adapters (bytecodealliance#2613)

The flag is read in one place, `process_adapters`, on the branch for
modules that aren't libraries, so it has no effect unless an adapter is
passed with `--adapt`. It also doesn't synthesize a `cabi_realloc` for a
main module that lacks one, which is what the repro in bytecodealliance#2404 expected.

Neither the CLI description nor the `ComponentEncoder` setter said any of
this, so say it in both and bless the two help snapshots.

Author: Lstarsky0

crates/wit-component/src/encoding.rs

@@ -3466,10 +3466,16 @@ impl ComponentEncoder {
         Ok(self)
     }
 
-    /// True if the realloc and stack allocation should use memory.grow
-    /// The default is to use the main module realloc
-    /// Can be useful if cabi_realloc cannot be called before the host
+    /// Whether adapters use `memory.grow` for realloc and stack allocation.
+    ///
+    /// By default an adapter imports `cabi_realloc` from the main module.
+    /// Setting this to `true` makes it allocate with `memory.grow` instead,
+    /// which can be useful if `cabi_realloc` cannot be called before the host
     /// runtime is initialized.
+    ///
+    /// This only affects modules added with [`ComponentEncoder::adapter`]. It
+    /// has no effect on the main module and does not synthesize a
+    /// `cabi_realloc` for a module that doesn't export one.
     pub fn realloc_via_memory_grow(&mut self, value: bool) -> &mut Self {
         self.realloc_via_memory_grow = value;
         self

src/bin/wasm-tools/component.rs

@@ -192,7 +192,15 @@ struct ComponentEncoderOpts {
     )]
     validate: Option<Option<bool>>,
 
-    /// Use memory.grow to realloc memory and stack allocation.
+    /// Use memory.grow to realloc memory and stack allocation in adapters.
+    ///
+    /// This only affects adapter modules passed with `--adapt`. It makes an
+    /// adapter allocate with `memory.grow` instead of importing `cabi_realloc`
+    /// from the main module, which is the default. It does not synthesize a
+    /// `cabi_realloc` for a main module that doesn't export one.
+    ///
+    /// This can be useful if `cabi_realloc` cannot be called before the host
+    /// runtime is initialized.
     #[clap(long)]
     realloc_via_memory_grow: bool,
 

tests/cli/help-component-new-short.wat.stdout

@@ -27,7 +27,7 @@ Options:
           Whether or not to validate the output component [possible values:
           true, false]
       --realloc-via-memory-grow
-          Use memory.grow to realloc memory and stack allocation
+          Use memory.grow to realloc memory and stack allocation in adapters
       --merge-imports-based-on-semver[=<true|false>]
           Indicates whether imports into the final component are merged based on
           semver ranges [possible values: true, false]

tests/cli/help-component-new.wat.stdout

@@ -84,7 +84,15 @@ Options:
           [possible values: true, false]
 
       --realloc-via-memory-grow
-          Use memory.grow to realloc memory and stack allocation
+          Use memory.grow to realloc memory and stack allocation in adapters.
+          
+          This only affects adapter modules passed with `--adapt`. It makes an
+          adapter allocate with `memory.grow` instead of importing
+          `cabi_realloc` from the main module, which is the default. It does not
+          synthesize a `cabi_realloc` for a main module that doesn't export one.
+          
+          This can be useful if `cabi_realloc` cannot be called before the host
+          runtime is initialized.
 
       --merge-imports-based-on-semver[=<true|false>]
           Indicates whether imports into the final component are merged based on