Skip to content

Fix grammar in language/types #5746

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kamil-tekiela merged 3 commits into from
Aug 7, 2026
Merged

Fix grammar in language/types #5746

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5b34d26
Fix grammar in language/types
kamil-tekiela Aug 7, 2026
c14dfe5
Change "para" to "simpara"
kamil-tekiela Aug 7, 2026
277520c
Review fixes
kamil-tekiela Aug 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions language/types/array.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -478,16 +478,16 @@ $arr[] = <replaceable>value</replaceable>;
// <replaceable>key</replaceable> may be an <type>int</type> or <type>string</type>
// <replaceable>value</replaceable> may be any value of any type</synopsis>

<para>
<simpara>
If <varname>$arr</varname> doesn't exist yet or is set to &null; or &false;, it will be created, so this is
also an alternative way to create an <type>array</type>. This practice is
however discouraged because if <varname>$arr</varname> already contains
some value (e.g. <type>string</type> from request variable) then this
value will stay in the place and <literal>[]</literal> may actually stand
value will stay in place and <literal>[]</literal> may actually stand
for <link linkend="language.types.string.substr">string access
operator</link>. It is always better to initialize a variable by a direct
assignment.
</para>
</simpara>
<note>
<simpara>
As of PHP 7.1.0, applying the empty index operator on a string throws a fatal
Expand Down Expand Up @@ -1052,17 +1052,17 @@ $error_descriptions[8] = "This is just an informal notice";
<literal>array($scalarValue)</literal>.
</para>

<para>
<simpara>
If an <type>object</type> is converted to an <type>array</type>, the result
is an <type>array</type> whose elements are the <type>object</type>'s
properties. The keys are the member variable names, with a few notable
exceptions: integer properties are unaccessible;
exceptions: integer properties are inaccessible;
private variables have the class name prepended to the variable
name; protected variables have a '*' prepended to the variable name. These
prepended values have <literal>NUL</literal> bytes on either side.
Uninitialized <link linkend="language.oop5.properties.typed-properties">typed properties</link>
are silently discarded.
</para>
</simpara>

<example>
<title>Converting to an Array</title>
Expand Down
4 changes: 2 additions & 2 deletions language/types/callable.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ print implode(' ', $new_numbers);

<simpara>
Static class methods can be used without instantiating an
<type>object</type> of that class by either, creating an array with
<type>object</type> of that class by either creating an array with
the class name at index 0 and the method name at index 1, or by using
the special syntax with the scope resolution operator
<literal>::</literal>, as in <literal>'ClassName::methodName'</literal>.
Expand Down Expand Up @@ -196,7 +196,7 @@ print implode(' ', $new_numbers);

<example>
<title>
Calling various types of callables with <function>call_user_function</function>
Calling various types of callables with <function>call_user_func</function>
</title>
<programlisting role="php">
<![CDATA[
Expand Down
13 changes: 7 additions & 6 deletions language/types/declarations.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,12 @@
otherwise a <classname>TypeError</classname> is thrown.
</para>

<para>
<simpara>
Every single type that PHP supports, with the exception of
<type>resource</type> can be used within a user-land type declaration.
<type>resource</type>, can be used within a user-land type declaration.
This page contains a changelog of availability of the different types
and documentation about usage of them in type declarations.
</para>
</simpara>

<note>
<para>
Expand Down Expand Up @@ -137,7 +137,7 @@
<title>Atomic Types Usage Notes</title>

<simpara>
Atomic types have straight forward behaviour with some minor caveats which
Atomic types have straightforward behaviour with some minor caveats which
are described in this section.
</simpara>

Expand Down Expand Up @@ -219,7 +219,8 @@ function &test(): void {}
If a pass-by-reference parameter has a type declaration, the type of the
variable is <emphasis>only</emphasis> checked on function entry, at the
beginning of the call, but not when the function returns.
This means that a function can change the type of variable reference.
This means that a function can change the type of the variable
passed by reference.
</simpara>
<example>
<title>Typed pass-by-reference Parameters</title>
Expand Down Expand Up @@ -307,7 +308,7 @@ Stack trace:
<simpara>
It is also possible to achieve nullable arguments by making
&null; the default value.
This is not recommended as if the default value is changed in a child
This is not recommended because if the default value is changed in a child
class a type compatibility violation will be raised as the
<type>null</type> type will need to be added to the type declaration.
This behavior is also deprecated since PHP 8.4.
Expand Down
52 changes: 26 additions & 26 deletions language/types/float.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<sect1 xml:id="language.types.float" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Floating point numbers</title>
<title>Floating-point numbers</title>

<para>
Floating point numbers (also known as "floats", "doubles", or "real numbers")
<simpara>
Floating-point numbers (also known as "floats", "doubles", or "real numbers")
can be specified using any of the following syntaxes:
</para>
</simpara>

<informalexample>
<programlisting role="php">
Expand Down Expand Up @@ -42,36 +42,36 @@ EXPONENT_DNUM (({LNUM} | {DNUM}) [eE][+-]? {LNUM})
</para>

<warning xml:id="warn.float-precision">
<title>Floating point precision</title>
<title>Floating-point precision</title>

<para>
Floating point numbers have limited precision. Although it depends on the
<simpara>
Floating-point numbers have limited precision. Although it depends on the
system, PHP typically uses the IEEE 754 double precision format, which will
give a maximum relative error due to rounding in the order of 1.11e-16.
Non elementary arithmetic operations may give larger errors, and, of course,
Non-elementary arithmetic operations may give larger errors, and, of course,
error propagation must be considered when several operations are
compounded.
</para>
</simpara>

<para>
Additionally, rational numbers that are exactly representable as floating
point numbers in base 10, like <literal>0.1</literal> or
<literal>0.7</literal>, do not have an exact representation as floating
point numbers in base 2, which is used internally, no matter the size of
<simpara>
Additionally, rational numbers that are exactly representable as floating-point
numbers in base 10, like <literal>0.1</literal> or
<literal>0.7</literal>, do not have an exact representation as floating-point
numbers in base 2, which is used internally, no matter the size of
the mantissa. Hence, they cannot be converted into their internal binary
counterparts without a small loss of precision. This can lead to confusing
results: for example, <literal>floor((0.1+0.7)*10)</literal> will usually
return <literal>7</literal> instead of the expected <literal>8</literal>,
since the internal representation will be something like
<literal>7.9999999999999991118...</literal>.
</para>
</simpara>

<para>
So never trust floating number results to the last digit, and do not compare
floating point numbers directly for equality. If higher precision is
<simpara>
So never trust floating-point number results to the last digit, and do not compare
floating-point numbers directly for equality. If higher precision is
necessary, the <link linkend="ref.bc">arbitrary precision math functions</link>
and <link linkend="ref.gmp">gmp</link> functions are available.
</para>
</simpara>

<para>
For a "simple" explanation, see the <link xlink:href="&url.floating.point.guide;">floating point guide</link>
Expand Down Expand Up @@ -117,18 +117,18 @@ EXPONENT_DNUM (({LNUM} | {DNUM}) [eE][+-]? {LNUM})
<sect2 xml:id="language.types.float.comparison">
<title>Comparing floats</title>

<para>
As noted in the warning above, testing floating point values for equality is
<simpara>
As noted in the warning above, testing floating-point values for equality is
problematic, due to the way that they are represented internally. However,
there are ways to make comparisons of floating point values that work around
there are ways to make comparisons of floating-point values that work around
these limitations.
</para>
</simpara>

<para>
To test floating point values for equality, an upper bound on the relative
<simpara>
To test floating-point values for equality, an upper bound on the relative
error due to rounding is used. This value is known as the machine epsilon,
or unit roundoff, and is the smallest acceptable difference in calculations.
</para>
</simpara>

<para>
<varname>$a</varname> and <varname>$b</varname> are equal to 5 digits of
Expand Down
19 changes: 10 additions & 9 deletions language/types/integer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
&reftitle.seealso;
<para>
<simplelist>
<member><link linkend="language.types.float">Floating point numbers</link></member>
<member><link linkend="language.types.float">Floating-point numbers</link></member>
<member><link linkend="book.bc">Arbitrary precision / BCMath</link></member>
<member><link linkend="book.gmp">Arbitrary length integer / GMP</link></member>
</simplelist>
Expand All @@ -29,12 +29,12 @@
can be used to denote a negative <type>int</type>.
</simpara>

<para>
<simpara>
To use octal notation, precede the number with a <literal>0</literal> (zero).
As of PHP 8.1.0, octal notation can also be preceded with <literal>0o</literal> or <literal>0O</literal>.
To use hexadecimal notation precede the number with <literal>0x</literal>.
To use binary notation precede the number with <literal>0b</literal>.
</para>
To use hexadecimal notation, precede the number with <literal>0x</literal>.
To use binary notation, precede the number with <literal>0b</literal>.
</simpara>

<para>
As of PHP 7.4.0, integer literals may contain underscores (<literal>_</literal>) between digits,
Expand Down Expand Up @@ -125,13 +125,13 @@ var_dump(PHP_INT_MAX + 1); // 32-bit system: float(2147483648)
<sect2 xml:id="language.types.integer.division">
<title>Integer division</title>

<para>
There is no <type>int</type> division operator in PHP, to achieve this
<simpara>
There is no <type>int</type> division operator in PHP. To achieve this,
use the <function>intdiv</function> function.
<literal>1/2</literal> yields the <type>float</type> <literal>0.5</literal>.
The value can be cast to an <type>int</type> to round it towards zero, or
the <function>round</function> function provides finer control over rounding.
</para>
</simpara>

<example>
<title>Divisions</title>
Expand Down Expand Up @@ -185,7 +185,8 @@ var_dump(round(25/7)); // float(4)
<simpara>
When converting from <type>float</type> to <type>int</type>, the number
will be rounded <emphasis>towards zero</emphasis>.
As of PHP 8.1.0, a deprecation notice is emitted when implicitly converting a non-integral &float; to &integer; which loses precision.
As of PHP 8.1.0, a deprecation notice is emitted when implicitly converting
a non-integral &float; to an &integer; which loses precision.
</simpara>

<example>
Expand Down
8 changes: 4 additions & 4 deletions language/types/iterable.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,19 @@
<sect1 xml:id="language.types.iterable">
<title>Iterables</title>

<para>
<type>Iterable</type> is a built-in compile time type alias for
<simpara>
<type>Iterable</type> is a built-in compile-time type alias for
<!-- Need to improve rendering of free-standing type elements in PhD
<type class="union"><type>array</type><type>Traversable</type></type>.
-->
<literal>array|Traversable</literal>.
From its introduction in PHP 7.1.0 and prior to PHP 8.2.0,
<type>iterable</type> was a built-in pseudo-type that acted as the
aforementioned type alias and can be used as a type declaration.
aforementioned type alias and could be used as a type declaration.
An iterable type can be used in &foreach; and with
<command>yield from</command> within a
<link linkend="language.generators">generator</link>.
</para>
</simpara>

<note>
<para>
Expand Down
8 changes: 4 additions & 4 deletions language/types/mixed.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,10 @@
Available as of PHP 8.0.0.
</para>

<para>
<type>mixed</type> is, in type theory parlance, the top type.
Meaning every other type is a subtype of it.
</para>
<simpara>
<type>mixed</type> is, in type theory parlance, the top type,
meaning every other type is a subtype of it.
</simpara>

@jordikroon jordikroon Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While I agree with the changes. This phrase is that advanced that I don't believe the majority of the people that read the documentation will understand. Read: Non-native speakers.

My suggestion:
<type>mixed</type> is a special type that accepts values of any other type.

@kamil-tekiela kamil-tekiela Aug 7, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's already on the page a couple of lines above it. I agree, it's difficult to understand, but not sure that dumbing it down is a good idea. It says exactly what it was supposed to say for people who are interested in type theory. An average reader will stop on the first paragraph.


</sect1>
<!-- Keep this comment at the end of the file
Expand Down
8 changes: 4 additions & 4 deletions language/types/never.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@
<link linkend="language.types.type-system.composite.union">union type</link>
declaration. Available as of PHP 8.1.0.
</para>
<para>
<type>never</type> is, in type theory parlance, the bottom type.
Meaning it is the subtype of every other type and can replace any other
<simpara>
<type>never</type> is, in type theory parlance, the bottom type,
meaning it is the subtype of every other type and can replace any other
return type during inheritance.
</para>
</simpara>

</sect1>
<!-- Keep this comment at the end of the file
Expand Down
6 changes: 3 additions & 3 deletions language/types/null.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@
&null;.
</para>

<para>
Undefined, and <function>unset</function> variables will resolve to the
<simpara>
Undefined and <function>unset</function> variables resolve to the
value &null;.
</para>
</simpara>

<sect2 xml:id="language.types.null.syntax">
<title>Syntax</title>
Expand Down
14 changes: 7 additions & 7 deletions language/types/numeric-strings.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ var_dump("2E1" == "020"); // true, "2E1" is 2 * (10 ^ 1), or 20
<sect2 xml:id="language.types.numeric-string.conversion">
<title>Strings used in numeric contexts</title>
<para>
When a <type>string</type> needs to be evaluated as number (e.g. arithmetic
When a <type>string</type> needs to be evaluated as a number (e.g. arithmetic
operations, <type>int</type> type declaration, etc.) the following
steps are taken to determine the outcome:

Expand All @@ -81,7 +81,7 @@ var_dump("2E1" == "020"); // true, "2E1" is 2 * (10 ^ 1), or 20
</listitem>
<listitem>
<simpara>
The <type>string</type> is not numeric, throw a
If the <type>string</type> is not numeric, throw a
<classname>TypeError</classname>.
</simpara>
</listitem>
Expand All @@ -91,12 +91,12 @@ var_dump("2E1" == "020"); // true, "2E1" is 2 * (10 ^ 1), or 20

<sect2 xml:id="language.types.numeric-string.prior">
<title>Behavior prior to PHP 8.0.0</title>
<para>
Prior to PHP 8.0.0, a <type>string</type> was considered numeric only if it
had <emphasis>leading</emphasis> whitespaces, if it had
<simpara>
Prior to PHP 8.0.0, a <type>string</type> was considered numeric if it only
had <emphasis>leading</emphasis> whitespaces. If it had
<emphasis>trailing</emphasis> whitespaces then the string was considered to
be leading numeric.
</para>
</simpara>

<para>
Prior to PHP 8.0.0, when a string was used in a numeric context it would
Expand All @@ -110,7 +110,7 @@ var_dump("2E1" == "020"); // true, "2E1" is 2 * (10 ^ 1), or 20
</listitem>
<listitem>
<simpara>
If the string is not numeric, an <constant>E_WARNING</constant> was
If the string was not numeric, an <constant>E_WARNING</constant> was
raised and the value <literal>0</literal> would be returned.
</simpara>
</listitem>
Expand Down
8 changes: 4 additions & 4 deletions language/types/object.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,15 +41,15 @@ $bar->do_foo();
<sect2 xml:id="language.types.object.casting">
<title>Converting to object</title>

<para>
<simpara>
If an <type>object</type> is converted to an <type>object</type>, it is not
modified. If a value of any other type is converted to an
<type>object</type>, a new instance of the <classname>stdClass</classname>
built-in class is created. If the value was &null;, the new instance will be
empty. An <type>array</type> converts to an <type>object</type> with properties
named by keys and corresponding values. Note that in this case before PHP 7.2.0 numeric keys
have been inaccessible unless iterated.
</para>
named by keys and with their corresponding values.
Prior to PHP 7.2.0, numeric keys would have been inaccessible unless iterated.
</simpara>

<example>
<title>Casting to an Object</title>
Expand Down
6 changes: 3 additions & 3 deletions language/types/relative-class-types.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@
<sect1 xml:id="language.types.relative-class-types">
<title>Relative class types</title>

<para>
These types declarations can only be used within classes.
</para>
<simpara>
These type declarations can only be used within classes.
</simpara>

<sect2 xml:id="language.types.relative-class-types.self">
<title><type>self</type></title>
Expand Down
Loading