From c57f6ebee17a0f2ee3cfefc0a9d77c99f0ae0ccc Mon Sep 17 00:00:00 2001
From: Mikhail Alferov <malferov@gmail.com>
Date: Mon, 24 Feb 2025 15:31:44 +0300
Subject: [PATCH] memory-get-usage.xml Clarify what kind of memory we are
 talking about

The current description confuses the reader and does not explain who allocates memory to whom. I'm not sure about the accuracy of the proposed formulations, but it seems that the changes better explain the difference between function calls without arguments or with the value `false`, or with the argument `true`.

I think that mentioning the engine, Zend Memory Manager (ZMM), or other internal details would be redundant, and the current description is enough to understand the difference.

Please check the proposal and make corrections to eliminate linguistic or semantic inaccuracies, if any, in the updated text.

And if the suggestion is OK, I will make the same changes with `memory_get_peak_usage()` ;-)
---
 reference/info/functions/memory-get-usage.xml | 25 +++++++++++--------
 1 file changed, 14 insertions(+), 11 deletions(-)

diff --git a/reference/info/functions/memory-get-usage.xml b/reference/info/functions/memory-get-usage.xml
index 1d2e401efaf6..0646233df976 100644
--- a/reference/info/functions/memory-get-usage.xml
+++ b/reference/info/functions/memory-get-usage.xml
@@ -3,9 +3,9 @@
 <refentry xml:id="function.memory-get-usage" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>memory_get_usage</refname>
-  <refpurpose>Returns the amount of memory allocated to PHP</refpurpose>
+  <refpurpose>Returns the amount of memory consumed by PHP script or allocated by system to PHP process</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
@@ -13,8 +13,8 @@
    <methodparam choice="opt"><type>bool</type><parameter>real_usage</parameter><initializer>&false;</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Returns the amount of memory, in bytes, that's currently being
-   allocated to your PHP script.
+   Returns the amount of memory, in bytes, that the PHP script is
+   currently using.
   </para>
  </refsect1>
 
@@ -27,15 +27,17 @@
      <listitem>
       <para>
        Set this to &true; to get total memory allocated from
-       system, including unused pages. 
-       If not set or &false; only the used memory is reported.
+       the system to the PHP process, including unused memory pages.
+       If not set or &false; only the memory used by PHP script is reported.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <note>
-   <para>PHP does not track memory that is not allocated by <literal>emalloc()</literal></para>
+   <para>
+    PHP tracks only memory that is allocated by the internal function <literal>emalloc()</literal>.
+   </para>
   </note>
  </refsect1>
 
@@ -54,18 +56,19 @@
     <programlisting role="php">
 <![CDATA[
 <?php
+
 // This is only an example, the numbers below will
-// differ depending on your system
+// differ depending on the specific system
 
-echo memory_get_usage() . "\n"; // 36640
+echo memory_get_usage(), "\n"; // 36640
 
 $a = str_repeat("Hello", 4242);
 
-echo memory_get_usage() . "\n"; // 57960
+echo memory_get_usage(), "\n"; // 57960
 
 unset($a);
 
-echo memory_get_usage() . "\n"; // 36744
+echo memory_get_usage(), "\n"; // 36744
 
 ?>
 ]]>