From e97b233e1a6ab65f854f969fdf6dfd8436abe0d2 Mon Sep 17 00:00:00 2001
From: Mikhail Alferov <malferov@gmail.com>
Date: Sun, 10 Nov 2024 18:00:17 +0300
Subject: [PATCH] userlandnaming.xml Explain the identifier, symbol;
 personalization

I'm sure I've made some mistakes in my wording and I hope I'll be corrected, but I think the reader would like a little more clarity for the terms in this section.
---
 appendices/userlandnaming.xml | 34 +++++++++++++++++++++-------------
 1 file changed, 21 insertions(+), 13 deletions(-)

diff --git a/appendices/userlandnaming.xml b/appendices/userlandnaming.xml
index 95fe76f8e3b8..ef9c8ab78be1 100644
--- a/appendices/userlandnaming.xml
+++ b/appendices/userlandnaming.xml
@@ -3,10 +3,12 @@
 <appendix xml:id="userlandnaming" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Userland Naming Guide</title>
  <para>
-  The following is a guide for how to best choose names for identifiers
+  The following is a guide for how to best choose names for identifiers (or
+  the part of lexical tokens also called a symbols),
   in userland PHP code. When choosing names for any code that creates symbols
-  in the global namespace, it is important to take into account the following
-  guidelines to prevent future versions of PHP from clashing with your
+  in the <link linkend="features.gc.refcounting-basics">symbol table</link>
+  of the global namespace, it is important to take into account the following
+  guidelines to prevent future versions of PHP from clashing with user
   symbols.
  </para>
 
@@ -20,9 +22,11 @@
    <listitem><para>functions</para></listitem>
    <listitem><para>classes</para></listitem>
    <listitem><para>interfaces</para></listitem>
+   <listitem><para>traits</para></listitem>
+   <listitem><para>enumerations</para></listitem>
    <listitem><para>constants (not class constants)</para></listitem>
    <listitem>
-    <para>variables defined outside of functions/methods</para>
+    <para>variables defined outside of functions and methods</para>
    </listitem>
   </itemizedlist>
  </section>
@@ -33,7 +37,7 @@
    The following list gives an overview of which rights the PHP project
    reserves for itself, when choosing names for new internal identifiers.
    The definitive guide is the official
-   <link xlink:href="&url.userlandnaming.cs;">CODING STANDARDS</link>:
+   <link xlink:href="&url.userlandnaming.cs;">Coding Standards</link>:
   </para>
 
   <itemizedlist>
@@ -47,14 +51,15 @@
     <para>
      Function names use underscores between words, while class names use
      both the <literal>camelCase</literal> and <literal>PascalCase</literal>
-     rules.
+     rules of the identifiers format style.
     </para>
    </listitem>
    <listitem>
     <para>
      PHP will prefix any global symbols of an extension with the name of
-     the extension. (In the past, there have been numerous
-     exceptions to this rule.) Examples:
+     the extension. (In the past, there have been numerous exceptions to this rule
+     which have resulted in identifiers that do not follow the naming rules.)
+     Examples:
     </para>
 
     <itemizedlist>
@@ -99,7 +104,7 @@
  <section xml:id="userlandnaming.tips">
   <title>Tips</title>
   <para>
-   In order to write future-proof code, it is recommended that you don't
+   In order to write future-proof code, it is recommended don't
    place many variables, functions or classes in the global namespace. This will
    prevent naming conflicts with 3rd party code as well as possible
    future additions to the language.
@@ -116,18 +121,21 @@
 
 namespace MyProject;
 
-function my_function() {
+function my_function()
+{
     return true;
 }
 
 \MyProject\my_function();
+
+?>
 ]]>
    </programlisting>
   </informalexample>
   <para>
-   This still needs you to keep track of already used namespaces, but once you
-   have decided on a namespace you will be using you can add all functions and
-   classes to it without having to think about conflicts again.
+   This still needs to keep track of already used namespaces, but once programmer
+   has decided on a namespace that will be using then functions and
+   classes can be added to it without having to think about conflicts again.
   </para>
   <para>
    It is considered best practice to limit the number of variables added to