Skip to content

Commit 192c33c

Browse files
mumumumumumu
committed
Rework documentation for dir functions
Include 8.5 deprecation for passing null to use the last opened directory. php/doc-en@5c7e9e1
1 parent bcac80d commit 192c33c

File tree

4 files changed

+229
-219
lines changed

4 files changed

+229
-219
lines changed

‎reference/dir/functions/closedir.xml‎

Lines changed: 65 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,97 @@
11
<?xml version="1.0" encoding="utf-8"?>
2-
<!-- splitted from ./ja/functions/dir.xml, last change in rev 1.1 -->
32
<!-- $Revision$ -->
4-
<!-- EN-Revision: b0b19b66183b28cebc1ffbcf1e2b8763f9d9c7b3 Maintainer: hirokawa Status: ready -->
5-
<!-- CREDITS: shimooka -->
3+
<!-- EN-Revision: 5c7e9e1351240b5f9e0858cdeba8f754a366d1b7 Maintainer: mumumu Status: ready -->
64
<refentry xml:id="function.closedir" xmlns="http://docbook.org/ns/docbook">
75
<refnamediv>
86
<refname>closedir</refname>
97
<refpurpose>ディレクトリハンドルをクローズする</refpurpose>
108
</refnamediv>
119

12-
1310
<refsect1 role="description">
1411
&reftitle.description;
1512
<methodsynopsis>
1613
<type>void</type><methodname>closedir</methodname>
1714
<methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>dir_handle</parameter><initializer>&null;</initializer></methodparam>
1815
</methodsynopsis>
19-
<para>
16+
<simpara>
2017
<parameter>dir_handle</parameter>
21-
で指定したディレクトリのストリームをクローズします。このストリームは、
22-
<function>opendir</function>により事前にオープンされていなければ
23-
なりません。
24-
</para>
18+
で指定したディレクトリのストリームをクローズします。
19+
</simpara>
2520
</refsect1>
2621

2722
<refsect1 role="parameters">
2823
&reftitle.parameters;
29-
<para>
30-
<variablelist>
31-
<varlistentry>
32-
<term><parameter>dir_handle</parameter></term>
33-
<listitem>
34-
<para>
35-
<function>opendir</function> が事前にオープンした
36-
ディレクトリハンドルを示す <type>resource</type>。
37-
ディレクトリハンドルを指定しなかった場合は、
38-
<function>opendir</function> が最後にオープンしたものを使用します。
39-
</para>
40-
</listitem>
41-
</varlistentry>
42-
</variablelist>
43-
</para>
24+
<variablelist>
25+
<varlistentry>
26+
<term><parameter>dir_handle</parameter></term>
27+
<listitem>
28+
<simpara>
29+
<function>opendir</function> が事前にオープンした
30+
ディレクトリハンドルを示す <type>resource</type>。
31+
<parameter>dir_handle</parameter> が &null; の場合は、
32+
<function>opendir</function> が最後にオープンしたものを使用します。
33+
</simpara>
34+
</listitem>
35+
</varlistentry>
36+
</variablelist>
4437
</refsect1>
4538

4639
<refsect1 role="returnvalues">
4740
&reftitle.returnvalues;
48-
<para>
41+
<simpara>
4942
&return.void;
50-
</para>
43+
</simpara>
44+
</refsect1>
45+
46+
<refsect1 role="changelog">
47+
&reftitle.changelog;
48+
<informaltable>
49+
<tgroup cols="2">
50+
<thead>
51+
<row>
52+
<entry>&Version;</entry>
53+
<entry>&Description;</entry>
54+
</row>
55+
</thead>
56+
<tbody>
57+
<row>
58+
<entry>8.5.0</entry>
59+
<entry>
60+
<parameter>dir_handle</parameter>
61+
に &null; を指定することは、推奨されなくなりました。
62+
代わりに、最後にオープンしたディレクトリハンドルを明示的に指定すべきです。
63+
</entry>
64+
</row>
65+
<row>
66+
<entry>8.0.0</entry>
67+
<entry>
68+
<parameter>dir_handle</parameter> は、nullable になりました。
69+
</entry>
70+
</row>
71+
</tbody>
72+
</tgroup>
73+
</informaltable>
5174
</refsect1>
5275

5376
<refsect1 role="examples">
5477
&reftitle.examples;
55-
<para>
56-
<example>
57-
<title><function>closedir</function> の例</title>
58-
<programlisting role="php">
59-
<![CDATA[
60-
<?php
61-
$dir = "/etc/php5/";
78+
<simpara>
79+
完全なサンプルコードは、
80+
<function>opendir</function> のドキュメントを参照ください。
81+
</simpara>
82+
</refsect1>
6283

63-
// 既知のディレクトリをオープンし、変数にディレクトリを読み込んで閉じる
64-
if (is_dir($dir)) {
65-
if ($dh = opendir($dir)) {
66-
$directory = readdir($dh);
67-
closedir($dh);
68-
}
69-
}
70-
?>
71-
]]>
72-
</programlisting>
73-
</example>
74-
</para>
84+
<refsect1 role="seealso">
85+
&reftitle.seealso;
86+
<simplelist>
87+
<member><function>opendir</function></member>
88+
<member><function>readdir</function></member>
89+
<member><function>rewinddir</function></member>
90+
<member><function>dir</function></member>
91+
<member><function>is_dir</function></member>
92+
<member><function>glob</function></member>
93+
<member><function>scandir</function></member>
94+
</simplelist>
7595
</refsect1>
7696
</refentry>
7797
<!-- Keep this comment at the end of the file

‎reference/dir/functions/opendir.xml‎

Lines changed: 78 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- splitted from ./ja/functions/dir.xml, last change in rev 1.1 -->
4-
<!-- EN-Revision: b0b19b66183b28cebc1ffbcf1e2b8763f9d9c7b3 Maintainer: hirokawa Status: ready -->
5-
<!-- CREDITS: takagi -->
3+
<!-- EN-Revision: 5c7e9e1351240b5f9e0858cdeba8f754a366d1b7 Maintainer: mumumu Status: ready -->
64
<refentry xml:id="function.opendir" xmlns="http://docbook.org/ns/docbook">
75
<refnamediv>
86
<refname>opendir</refname>
@@ -16,56 +14,54 @@
1614
<methodparam><type>string</type><parameter>directory</parameter></methodparam>
1715
<methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>context</parameter><initializer>&null;</initializer></methodparam>
1816
</methodsynopsis>
19-
<para>
17+
<simpara>
2018
ディレクトリハンドルをオープンします。このハンドルは、この後
2119
<function>closedir</function>, <function>readdir</function>,
2220
<function>rewinddir</function> 関数コールで使用されます。
23-
</para>
21+
</simpara>
2422
</refsect1>
2523

2624
<refsect1 role="parameters">
2725
&reftitle.parameters;
28-
<para>
29-
<variablelist>
30-
<varlistentry>
31-
<term><parameter>directory</parameter></term>
32-
<listitem>
33-
<para>
34-
オープンするディレクトリのパス。
35-
</para>
36-
</listitem>
37-
</varlistentry>
38-
<varlistentry>
39-
<term><parameter>context</parameter></term>
40-
<listitem>
41-
<para>
42-
<parameter>context</parameter> パラメータの詳細については
43-
マニュアルの<link linkend="ref.stream">ストリーム</link>
44-
を参照ください。
45-
</para>
46-
</listitem>
47-
</varlistentry>
48-
</variablelist>
49-
</para>
26+
<variablelist>
27+
<varlistentry>
28+
<term><parameter>directory</parameter></term>
29+
<listitem>
30+
<simpara>
31+
オープンするディレクトリのパス。
32+
</simpara>
33+
</listitem>
34+
</varlistentry>
35+
<varlistentry>
36+
<term><parameter>context</parameter></term>
37+
<listitem>
38+
<simpara>
39+
<parameter>context</parameter> パラメータの詳細については
40+
マニュアルの<link linkend="ref.stream">ストリーム</link>
41+
を参照ください。
42+
</simpara>
43+
</listitem>
44+
</varlistentry>
45+
</variablelist>
5046
</refsect1>
5147

5248
<refsect1 role="returnvalues">
5349
&reftitle.returnvalues;
54-
<para>
55-
成功した場合にディレクトリハンドルの <type>resource</type> 、
50+
<simpara>
51+
成功した場合にディレクトリハンドルを返します。
5652
&return.falseforfailure;
57-
</para>
53+
</simpara>
5854
</refsect1>
5955

6056
<refsect1 role="errors">
6157
&reftitle.errors;
6258
&fs.emits.warning.on.failure;
63-
<para>
59+
<simpara>
6460
<parameter>directory</parameter> が有効なディレクトリでない場合、
6561
権限の制限によりディレクトリがオープンできない場合、
6662
またはファイルシステムのエラー時に起こりえます。
67-
</para>
68-
</refsect1>
63+
</simpara>
64+
</refsect1>
6965

7066
<refsect1 role="changelog">
7167
&reftitle.changelog;
@@ -91,49 +87,69 @@
9187

9288
<refsect1 role="examples">
9389
&reftitle.examples;
94-
<para>
95-
<example>
96-
<title><function>opendir</function> の例</title>
97-
<programlisting role="php">
90+
<example>
91+
<title>
92+
ディレクトリ中の全てのエントリを表示します。
93+
ただし、特別な <literal>.</literal> と
94+
<literal>..</literal> ディレクトリはスキップします。
95+
</title>
96+
<simpara>
97+
ファイル名やディレクトリ名は、
98+
PHP が &false; と見なす文字列
99+
(例: <literal>"0"</literal> という名前のディレクトリ)
100+
の可能性があり、かつ <function>readdir</function>
101+
は全てのディレクトリエントリを読み取ったあとに &false; を返します。
102+
そのため、PHP が &false;
103+
とみなすディレクトリ名と、
104+
全てのディレクトリエントリを読み取ったことを適切に区別するためには、
105+
<link linkend="language.operators.comparison">比較演算子</link> <literal>===</literal>
106+
を使う必要があります。
107+
</simpara>
108+
<programlisting role="php">
98109
<![CDATA[
99110
<?php
100-
$dir = "/etc/php5/";
101111
102-
// 既知のディレクトリをオープンし、その内容を読み込みます。
103-
if (is_dir($dir)) {
104-
if ($dh = opendir($dir)) {
105-
while (($file = readdir($dh)) !== false) {
106-
echo "filename: $file : filetype: " . filetype($dir . $file) . "\n";
112+
if ($handle = opendir('/path/to/files')) {
113+
echo "Entries:\n";
114+
115+
/* Correctly handling directory entries that may be considered falsy */
116+
while (false !== ($entry = readdir($handle))) {
117+
if ($entry === '.' || $entry === '..') {
118+
continue;
107119
}
108-
closedir($dh);
120+
echo "$entry\n";
109121
}
122+
123+
closedir($handle);
110124
}
111125
?>
112126
]]>
113-
</programlisting>
114-
&example.outputs.similar;
115-
<screen>
127+
</programlisting>
128+
&example.outputs.similar;
129+
<screen>
116130
<![CDATA[
117-
filename: . : filetype: dir
118-
filename: .. : filetype: dir
119-
filename: apache : filetype: dir
120-
filename: cgi : filetype: dir
121-
filename: cli : filetype: dir
131+
Entries:
132+
base
133+
en
134+
fr
135+
output.md
136+
test.php
122137
]]>
123-
</screen>
124-
</example>
125-
</para>
138+
</screen>
139+
</example>
126140
</refsect1>
127141

128142
<refsect1 role="seealso">
129143
&reftitle.seealso;
130-
<para>
131-
<simplelist>
132-
<member><function>is_dir</function></member>
133-
<member><function>readdir</function></member>
134-
<member><function>dir</function></member>
135-
</simplelist>
136-
</para>
144+
<simplelist>
145+
<member><function>readdir</function></member>
146+
<member><function>rewinddir</function></member>
147+
<member><function>closedir</function></member>
148+
<member><function>dir</function></member>
149+
<member><function>is_dir</function></member>
150+
<member><function>glob</function></member>
151+
<member><function>scandir</function></member>
152+
</simplelist>
137153
</refsect1>
138154
</refentry>
139155
<!-- Keep this comment at the end of the file

0 commit comments

Comments
 (0)