Skip to content

PHP 8.4: Document SplObjectStorage::seek() #4048

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
merged 7 commits into from
Nov 12, 2024
Merged

PHP 8.4: Document SplObjectStorage::seek() #4048

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7df91dc
PHP 8.4: Document SplObjectStorage::seek()
Girgias Nov 12, 2024
3549763
Add info in versions.xml
Girgias Nov 12, 2024
42b2034
Document SplObjectStorage::seek()
nielsdos Nov 12, 2024
5a9c684
Change para to simpara in errors of SeekableIterator::seek()
nielsdos Nov 12, 2024
465c1de
Document ArrayIterator::seek()
nielsdos Nov 12, 2024
62259b1
fix
nielsdos Nov 12, 2024
38bfa49
Fix some markup issues
Girgias Nov 12, 2024
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
14 changes: 12 additions & 2 deletions reference/spl/arrayiterator/seek.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<refentry xml:id="arrayiterator.seek" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>ArrayIterator::seek</refname>
<refpurpose>Seek to position</refpurpose>
<refpurpose>Seeks to a position</refpurpose>
</refnamediv>

<refsect1 role="description">
Expand All @@ -13,7 +13,9 @@
<methodparam><type>int</type><parameter>offset</parameter></methodparam>
</methodsynopsis>

&warn.undocumented.func;
<simpara>
Seeks to a given position in the iterator.
</simpara>
</refsect1>

<refsect1 role="parameters">
Expand All @@ -32,6 +34,14 @@
</para>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<simpara>
Throws an <classname>OutOfBoundsException</classname>
if the <parameter>offset</parameter> is not seekable.
</simpara>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Expand Down
4 changes: 2 additions & 2 deletions reference/spl/seekableiterator/seek.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,10 +43,10 @@

<refsect1 role="errors">
&reftitle.errors;
<para>
<simpara>
Implementations should throw an <classname>OutOfBoundsException</classname>
if the <parameter>offset</parameter> is not seekable.
</para>
</simpara>
</refsect1>

<refsect1 role="examples">
Expand Down
76 changes: 31 additions & 45 deletions reference/spl/splobjectstorage/seek.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<refentry xml:id="splobjectstorage.seek" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>SplObjectStorage::seek</refname>
<refpurpose>Description</refpurpose>
<refpurpose>Seeks iterator to a position</refpurpose>
</refnamediv>

<refsect1 role="description">
Expand All @@ -11,26 +11,26 @@
<modifier>public</modifier> <type>void</type><methodname>SplObjectStorage::seek</methodname>
<methodparam><type>int</type><parameter>offset</parameter></methodparam>
</methodsynopsis>
&warn.undocumented.func;

<simpara>
Description.
Seeks to a given position in the iterator.
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<simpara>
<para>
<variablelist>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<simpara>
Description.
The position to seek to.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</simpara>
</para>
Copy link
Member Author

Choose a reason for hiding this comment

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

Ideally this wrapping para should be removed, but I'm fine to leave the <para> tag if it is pre-exiting

Copy link
Member

Choose a reason for hiding this comment

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

The simpara came out of the stub generator, but that was wrong so I changed it back to para: php/php-src#16764

</refsect1>

<refsect1 role="returnvalues">
Expand All @@ -43,71 +43,57 @@
<refsect1 role="errors">
&reftitle.errors;
<simpara>
When does this function issue <constant>E_*</constant> level errors,
and/or throw <exceptionname>Exception</exceptionname>s.
Throws an <classname>OutOfBoundsException</classname>
if the <parameter>offset</parameter> is not seekable.
</simpara>
</refsect1>

<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.X.0</entry>
<entry>
Description
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example xml:id="splobjectstorage.seek.example.basic">
<title><methodname>SplObjectStorage::seek</methodname> example</title>
<simpara>
Description.
Seeks to item position 2 in the iterator.
</simpara>
<programlisting role="php">
<![CDATA[
<?php
echo "Code example";
class Test {
public function __construct(public string $marker) {}
}
$a = new Test("a");
$b = new Test("b");
$c = new Test("c");
$storage = new SplObjectStorage();
$storage[$a] = "first";
$storage[$b] = "second";
$storage[$c] = "third";
$storage->seek(2);
var_dump($storage->key());
var_dump($storage->current());
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Code example
int(2)
object(Test)#3 (1) {
["marker"]=>
string(1) "c"
}
]]>
</screen>
</example>
</refsect1>

<refsect1 role="notes">
&reftitle.notes;
<note>
<simpara>
Any notes that don't fit anywhere else should go here.
</simpara>
</note>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><methodname>ClassName::otherMethodName</methodname></member>
<member><function>some_function</function></member>
<member><link linkend="some.id.chunk.to.link">something appendix</link></member>
<member><classname>SeekableIterator</classname></member>
</simplelist>
</refsect1>

Expand Down
Loading